历史版本21 :API入门 返回文档
编辑时间: 内容长度:图片数:目录数: 修改原因:

目录:

1. 什么是 API编辑

API（Application Programming Interface）是一种允许不同软件组件之间相互通信、交换信息的工具，他提供了一种统一的、规范化的途径，开发者只需遵循这些建立在互通基础上的规则，就能轻松地实现数据传输、功能调用等操作。

外部人员调用 API 时，无需深入研究系统的源代码或理解内部处理的细节，只需传递一些特定格式的信息，就能得到他们需要的数据或执行特定的操作。

例如可以判断是否为法定节假日的 API：https://timor.tech/api/holiday/info/2024-01-25；访问后，如下图所示：

1706167082272881.png

type 值说明如下：

值
说明
0
工作日
1周末
2节日
3调休补班

访问该链接，可判断 2024-01-25 为工作日。用户可以把 2024-01-25 替换为任意相同格式的日期，查询是否为工作日。

这就是 API ，您无需深入了解他的内部实现，只需要传递一些特定格式的信息，即可获取到期望的内容。

2. 接口说明编辑

2.1 http 请求方法

API 接口可以分为以下几类：HTTP类型接口、RPC接口、Webservice接口、数据库访问接口等。

我们常说的 API 一般是指以 HTTP 协议进行传输的 API 接口，常见的 HTTP 请求方式包括：GET、POST、PUT、DELETE 等。

http 请求方式
说明
GET

用来向指定的 URL 请求获取资源，比如 HTML 文档、图片、视频等；GET 请求通常用于请求获取数据，而不会对服务器端数据进行修改

GET 请求一般会将参数写在网址后面，用?连接，多个参数之间用&连接。例如：

30.png

GET 请求的特点是请求参数明文传输，不适合传输敏感信息；传递的数据大小有限制，4kb 左右（不同浏览器会有差异）

POST

向指定资源提交数据进行处理请求（例如提交表单或者上传文件）；POST 请求可能会导致新的资源的建立和 / 或已有资源的修改

与 GET 请求不同，Post 请求将数据放在请求体中，而不是 URL 中，所以相对安全，数据不会暴露在 URL 中

Post 请求没有数据长度限制

示例：

31.png


PUT

用于替换资源，如果资源不存在则创建新的资源

与 GET 请求不同，PUT请求会替换掉指定位置的原有数据，而不是简单地获取数据

常见的使用场景包括更新用户信息、上传文件、修改配置等

PUT 方式和 POST 方式极为相似，都可以向服务器提交数据：

  • PUT 方式通常指定了资源的存放位置(即提交数据时指定的位置)

  • POST 方式所提交的数据由服务器决定存放位置(可能是新增数据，也可能是更新数据)

DELETE

用于请求服务器删除指定资源

可在 URL 和请求体中传递参数

需慎重使用 DELETE 请求，他可能会删除服务器上重要的资源

2.2 如何看接口文档

调用 API 时，我们需要了解接口地址、请求方法、接口权限、请求参数等内容，才能成功调用该接口。

例如：获取部门用户详情 接口。

内容说明
接口描述

简单描述接口的逻辑和作用

接口权限

说明接口的访问权限，例如需要登录、需要特定的角色等

接口地址

这个地址表示的是网络地址，即url，我们需要调用接口url，获取响应内容

请求方法

常见的请求方法为 GET 和 POST

请求参数

用来传递信息的变量。即需要请求的字段名的名称和规则：都是哪些字段，字段的类型是什么，是否必填字段等等

  • URL传参

  • Headers 请求头

  • Body 请求内容

响应内容接口返回的字段名称和规则
错误码对接口的错误用代码进行归类，以便能快速找到错误原因，解决问题
示例给出一些请求示例，可以帮助开发者理解接口的使用方式

2.3 postman 中调用接口示例

本节给出在 postman 中调用 GET 请求、POST 请求的示例。

2.3.1 GET 请求

示例接口：调用企业微信接口时获取 access_token：获取access_token

在 FDL 中调用该接口的完整示例可参见：API取数-获取企业微信人员信息

内容
示例接口说明
接口描述调用企业微信接口时获取 access_token
接口权限

33.png

调用接口时，传入要使用应用的 secret 即可

接口地址https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
请求方法GET
请求参数32.png
响应内容

1706237919758808.png

36.png

在GET请求中，遇到参数 / Params / Querys 均是以 URL传参的形式进行传递。

在POSTMAN中，可以直接用 URL传参形式，也可以在 Params 处填写 KEY 和 VALUE，会自动进行拼接。

001.png


点击 send 按钮后，返回内容如下图所示：

至此，一个 GET 请求的 API 被成功调用。

002.png

2.3.2 POST 请求

POST请求一般由Url 、 Headers 、 Body组成，如果在 POST 请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用URL参数传递参数，而POST请求的接口文档里面的参数一般指Body。

示例接口：获取企业内部应用的accessToken

在 FDL 中调用该接口的完整示例可参见：API取数-钉钉获取部门列表

内容
示例接口说明
接口描述企业内部应用调用本接口获取accessToken
接口权限1706240658338893.png
接口地址

https://api.dingtalk.com/v1.0/oauth2/accessToken

调用该 API 时，Body 处的格式选择 row-json

1706240739425600.png

请求方法POST
请求参数40.png
响应内容41.png
错误码42.png
示例示例

postman 中调用该接口如下图所示：

003.png


点击 send 按钮后，返回内容如下图所示：

至此，一个 POST 请求的 API 被成功调用。

1706254083708836.png

3. FDL 的 API 相关功能编辑

1）调用 API

在 数据同步 节点、参数赋值 节点、API 输入 算子中，可调用第三方接口，获取数据。

2）创建 API 

数据服务 功能，可以将加工、融合后的数据封装发布为规范化 API 接口数据，供外部系统调用，实现数据价值输出及共享开放。

3）将数据输出到 API

可通过 API 输出 算子，将处理好的数据输出到 API 中。

4. FDL 中调用 API 说明编辑

调用 API 前，需先阅读该 API 的接口文档，了解接口的接口地址、请求方法、接口权限、请求参数等内容，才能成功调用该接口。

本节在 FDL 中调用 API。

3.1 调用 API 说明

在 FDL 中调用 API时，有以下设置项：

48.png


3.1.1 请求方法&URL地址

1）请求方法：HTTP 请求方法有 GET、POST、PUT、DELETE 等

FDL 支持GET和POST两种请求方式，若您需要使用PUT或者 DELETE 请求方法，POST 方法也能满足需求。

2）URL 地址：调用接口的 url 。

3.1.2 Params

1706254834659834.png

填写请求参数，内容为：URL 传参(Query参数)，添加的参数会直接显示在 URL 中。

通常用于 GET 请求，也可以用于其他类型的请求。

例如https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=XXXX&corpsecret=XXX，？后面的  corpid 和 corpsecret 就是添加的参数。

3.1.3 Authorization

验证是否有权限从服务器访问所需的数据。

它允许用户在发送 API 请求之前配置和添加身份验证信息，以便访问受保护的 API 资源。API 提供商通常需要使用 API 密钥、访问令牌、用户名和密码等信息进行身份验证，以确保只有经过身份验证的用户才能访问受保护的 API 资源。

简单理解，鉴权就像门禁，你要想进入小区，就得通过门禁卡来验证身份，这就是鉴权。

FDL 支持的认证方式：No Auth、Bearer Token、Basic Auth、其他认证（将Authorization选项原样放入、且支持参数输入）。

1）No Auth（无身份验证）

不需要提供任何凭据或参数；适用于不需要身份验证的 API 。

2）Bearer Token

Bearer Token 允许使用访问密钥（例如JSON Web Token（JWT））对请求进行身份验证。token 是文本字符串，包含在请求 header 中。

使用 Bearer Token：

  • 从下拉菜单中选择 Bearer Token。

  • 在令牌字段中，输入您的 API 密钥值；或为了增加安全性，将其存储在变量中并按名称引用该变量。

1706257833722066.png

3）Basic Auth

基本身份验证是一种比较简单的授权类型，经过验证的用户名和密码才能访问数据资源。

使用 Basic Auth：

  • 从下拉菜单中选择 Basic Auth。

  • 输入用户名和密码。

1706258183881494.png

4）认证方式还有：Inherit auth from parent （从父类继承身份验证）、Digest Auth、Hawk Authentication 等等，本文不再详细介绍，用户可自行百度了解。

3.1.4 Headers











FDL 中支持的授权：

  • 无认证（默认）

  • Bearer Token：在输入框中输入 token 验证

  • Basic Auth：输入用户名和密码验证

  • 其他认证：将Authorization选项原样放入、且支持参数输入





3.2 调用 GET 请求示例

示例接口：调用企业微信接口时获取 access_token：获取access_token

内容
示例接口说明
接口描述调用企业微信接口时获取 access_token
接口权限

33.png

调用接口时，传入要使用应用的 secret 即可

接口地址https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
请求方法GET
请求参数32.png
响应内容

1706237919758808.png

36.png

在GET请求中，遇到参数 / Params / Querys 均是以 URL传参的形式进行传递。

在POSTMAN中，可以直接用 URL传参形式，也可以在 Params 处填写 KEY 和 VALUE，会自动进行拼接。

1706238043683458.png

点击 send 按钮后，返回内容如下图所示：

至此，一个 GET 请求的 API 被成功调用。

37.png

3.3 调用 POST 请求示例

POST请求一般由Url 、 Headers 、 Body组成，如果在POST请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用URL参数传递参数，而POST请求的接口文档里面的参数一般指Body。

示例接口：获取企业内部应用的accessToken

内容
示例接口说明
接口描述企业内部应用调用本接口获取accessToken
接口权限1706240658338893.png
接口地址

https://api.dingtalk.com/v1.0/oauth2/accessToken

调用该 API 时，Body 处的格式选择 row-json

1706240739425600.png

请求方法POST
请求参数40.png
响应内容41.png
错误码42.png
示例示例

postman 中调用该接口如下图所示：


43.png

点击 send 按钮后，返回内容如下图所示：

至此，一个 POST 请求的 API 被成功调用。

1706248795236340.png











3. FDL 的 API 相关功能编辑