1. 什么是 API
API（Application Programming Interface）是一种允许不同软件组件之间相互通信、交换信息的工具，他提供了一种统一的、规范化的途径，开发者只需遵循这些建立在互通基础上的规则，就能轻松地实现数据传输、功能调用等操作。
外部人员调用 API 时，无需深入研究系统的源代码或理解内部处理的细节，只需传递一些特定格式的信息，就能得到他们需要的数据或执行特定的操作。
例如可以判断是否为法定节假日的 API：https://timor.tech/api/holiday/info/2024-01-25；访问后，如下图所示：
type 值说明如下：
| 值 | 说明 |
|---|---|
| 0 | 工作日 |
| 1 | 周末 |
| 2 | 节日 |
| 3 | 调休补班 |
访问该链接，可判断 2024-01-25 为工作日。用户可以把 2024-01-25 替换为任意相同格式的日期，查询是否为工作日。
2. 接口说明
2.1 HTTP 请求方法
API 接口可以分为以下几类：HTTP类型接口、RPC接口、Webservice接口、数据库访问接口等。
我们常说的 API 一般是指以 HTTP 协议进行传输的 API 接口，常见的 HTTP 请求方式包括：GET、POST、PUT、DELETE 等。
| HTTP 请求方式 | 说明 |
|---|---|
| GET | 用来向指定的 URL 请求获取资源，比如 HTML 文档、图片、视频等；GET 请求通常用于请求获取数据，而不会对服务器端数据进行修改 GET 请求一般会将参数写在网址后面，用?连接，多个参数之间用&连接。例如：
GET 请求的特点是请求参数明文传输，不适合传输敏感信息；传递的数据大小有限制，4kb 左右（不同浏览器会有差异） |
| POST | 向指定资源提交数据进行处理请求（例如提交表单或者上传文件）；POST 请求可能会导致新的资源的建立和 / 或已有资源的修改 与 GET 请求不同，POST 请求将数据放在请求体中，而不是 URL 中，所以相对安全，数据不会暴露在 URL 中 POST 请求没有数据长度限制 示例：
|
| PUT | 用于替换资源，如果资源不存在则创建新的资源 与 GET 请求不同，PUT请求会替换掉指定位置的原有数据，而不是简单地获取数据 常见的使用场景包括更新用户信息、上传文件、修改配置等 PUT 方式和 POST 方式极为相似，都可以向服务器提交数据：
|
| DELETE | 用于请求服务器删除指定资源 可在 URL 和请求体中传递参数 需慎重使用 DELETE 请求，他可能会删除服务器上重要的资源 |
2.2 如何看接口文档
调用 API 时，我们需要了解接口地址、请求方法、接口权限、请求参数等内容，才能成功调用该接口。
例如：获取部门用户详情 接口。
| 内容 | 说明 |
|---|---|
| 接口描述 | 简单描述接口的逻辑和作用 |
| 接口权限 | 说明接口的访问权限，例如需要登录、需要特定的角色等 |
| 接口地址 | 这个地址表示的是网络地址，即 URL，我们需要调用接口 URL，获取响应内容 |
| 请求方法 | 常见的请求方法为 GET 和 POST |
| 请求参数 | 用来传递信息的变量。即需要请求的字段名的名称和规则：都是哪些字段，字段的类型是什么，是否必填字段等等
1）GET 请求方法参数说明：
2）POST 请求方法参数说明： POST 请求一般由 URL、 Headers 、 Body组成，如果在 POST 请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用 URL 参数传递参数，而 POST 请求的接口文档里面的参数一般指 Body |
| 响应内容 | 接口返回的字段名称和规则 |
| 错误码 | 对接口的错误用代码进行归类，以便能快速找到错误原因，解决问题 |
| 示例 | 给出一些请求示例，可以帮助开发者理解接口的使用方式 |
2.3 Postman 中调用接口示例
本节给出在 Postman 中调用 GET 请求、POST 请求的示例。
2.3.1 GET 请求
示例接口：调用企业微信接口时获取 access_token：获取access_token
在 FDL 中调用该接口的完整示例可参见：API取数-获取企业微信人员信息
| 内容 | 示例接口说明 |
|---|---|
| 接口描述 | 调用企业微信接口时获取 access_token |
| 接口权限 |
调用接口时，传入要使用应用的 secret 即可 |
| 接口地址 | https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET |
| 请求方法 | GET |
| 请求参数 | |
| 响应内容 |
|
在GET请求中，遇到参数 / Params / Querys 均是以 URL 传参的形式进行传递。
在 Postman 中，可以直接用 URL 传参形式，也可以在 Params 处填写 KEY 和 VALUE，会自动进行拼接。
点击 send 按钮后，返回内容如下图所示：
至此，一个 GET 请求的 API 被成功调用。
2.3.2 POST 请求
POST 请求一般由 URL 、 Headers 、 Body组成，如果在 POST 请求的接口文档里遇到 Params / Querys 则需以像GET请求一样使用 URL 参数传递参数，而 POST 请求的接口文档里面的参数一般指Body。
示例接口：获取企业内部应用的accessToken
在 FDL 中调用该接口的完整示例可参见：API取数-钉钉获取部门列表
| 内容 | 示例接口说明 |
|---|---|
| 接口描述 | 企业内部应用调用本接口获取accessToken |
| 接口权限 | |
| 接口地址 | https://api.dingtalk.com/v1.0/oauth2/accessToken 调用该 API 时，Headers 处参数为 Content-Type ，值为 application/json（Postman 中 选择 POST 请求方式时，Headers 处默认有该参数） 下图 5-8 行为 Body 内容
|
| 请求方法 | POST |
| 请求参数 | 参数在 Body 内
|
| 响应内容 | |
| 错误码 | |
| 示例 | 示例 |
Postman 中调用该接口如下图所示：
点击 send 按钮后，返回内容如下图所示：
至此，一个 POST 请求的 API 被成功调用。
3. FDL 的 API 相关功能
1）调用 API
在 数据同步 节点、参数赋值 节点、API 输入 算子中，可调用第三方接口，获取接口数据。
2）创建 API
数据服务 功能，可以将加工、融合后的数据封装发布为规范化 API 接口数据，供外部系统调用，实现数据价值输出及共享开放。
3）将数据输出到 API
可通过 API 输出 算子，将处理好的数据输出到 API 中。
4. 如何在 FDL 中调用 API
调用 API 前，需先阅读该 API 的接口文档，了解接口的接口地址、请求方法、接口权限、请求参数等内容，才能成功调用该接口。
4.1 调用 API 时各设置项含义
在 FDL 中调用 API时，有以下设置项：
4.1.1 请求方法&URL地址
1）请求方法：HTTP 请求方法有 GET、POST、PUT、DELETE 等
FDL 支持 GET 和 POST 两种请求方式，若您需要使用PUT或者 DELETE 请求方法，POST 方法也能满足需求。
2）URL 地址：调用接口的 URL 。
4.1.2 Params
填写请求参数，内容为：URL 传参(Query参数)，添加的参数会直接显示在 URL 中。
通常用于 GET 请求，也可以用于其他类型的请求。
例如https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=XXXX&corpsecret=XXX，？后面的 corpid 和 corpsecret 就是添加的参数。
4.1.3 Authorization
验证是否有权限从服务器访问所需的数据。
它允许用户在发送 API 请求之前配置和添加身份验证信息，以便访问受保护的 API 资源。API 提供商通常需要使用 API 密钥、访问令牌、用户名和密码等信息进行身份验证，以确保只有经过身份验证的用户才能访问受保护的 API 资源。
简单理解，鉴权就像门禁，你要想进入小区，就得通过门禁卡来验证身份，这就是鉴权。
FDL 支持的认证方式：No Auth、Bearer Token、Basic Auth、其他认证（将 Authorization 选项原样放入、且支持参数输入）；若认证方式非 No Auth、Bearer Token、Basic Auth ，在 FDL 中选择「其他认证」即可。
1）No Auth（无身份验证）
不需要提供任何凭据或参数；适用于不需要身份验证的 API 。
2）Bearer Token
Bearer Token 允许使用访问密钥（例如JSON Web Token（JWT））对请求进行身份验证。token 是文本字符串，包含在请求 header 中。
使用 Bearer Token：
从下拉菜单中选择 Bearer Token。
在令牌字段中，输入您的 API 密钥值；或为了增加安全性，将其存储在变量中并按名称引用该变量。
3）Basic Auth
基本身份验证是一种比较简单的授权类型，经过验证的用户名和密码才能访问数据资源。
使用 Basic Auth：
从下拉菜单中选择 Basic Auth。
输入用户名和密码。
4）认证方式还有：Inherit auth from parent （从父类继承身份验证）、Digest Auth、Hawk Authentication 等等，本文不再详细介绍，用户可自行百度了解。
4.1.4 Headers
Headers 简称请求头，是 HTTP 协议传输过程中规定的一组键值对，用来描述客户端的环境信息、请求偏好或身份验证等。请求头是 HTTP 请求的一部分，包含了操作系统、浏览器类型、请求方法（GET，POST 等）、语言等信息。服务器根据这些信息来处理请求并生成适当的响应。
例如： V3版本请求体&签名机制 文档中，说明了 Headers 参数，调用相关接口时，需填入 Headers 参数 。完整示例请参见：使用FDL接口形式实现阿里云服务器数据监听
1）Accept
该字段描述了客户端希望收到的内容类型，如text/plain（纯文本）、text/html（html文档）、image/png（png图片）、application/json（json类型）等。
2）Accept-Charset
浏览器能识别的字符集，例如 Accept-Charset: utf-8。
3）Authorization
用于提供身份验证信息，以确认请求的合法性。
4）Content-Type
在 HTTP 协议消息头中，使用 Content-Type 来表示请求和响应中的媒体类型信息。它用来告诉服务端如何处理请求的数据，以及告诉客户端（一般是浏览器）如何解析响应的数据，比如显示图片，解析并展示 html 等。
通常只会用在 POST 和 PUT 方法的请求中。
| 常见 Content-Type | 说明 |
|---|---|
| application/json | JSON 是一种轻量级的数据格式，以「键-值」对的方式组织的数据 使用 application/json ，需要参数本身就是 json 格式的数据，参数会被直接放到请求实体里，不进行任何处理。服务端/客户端会按 json 格式解析数据 |
| application/x-www-form-urlencoded | 请求参数格式key1=val1&key2=val2的方式进行拼接，并放到请求实体里面，如果是中文或特殊字符等会自动进行 URL 转码。一般用于表单提交 |
| application/xml | 与 application/json 类似，这里用的是 xml 格式的数据 |
| multipart/form-data | 与 application/x-www-form-urlencoded 不同，这是一个多部分多媒体类型 首先生成一个 boundary 用于分割不同的字段，在请求实体里每个参数以------boundary开始，然后是附加信息和参数名，然后是空行，最后是参数内容。 多个参数将会有多个 boundary 块。如果传输的是文件，还要包含文件名和文件类型信息。最后以------boundary–为结束标识。multipart/form-data 支持文件上传的格式，一般需要上传文件的表单则用该类型 |
| text/xml | 表示传输的数据是 XML 格式的文本 |
| text/plain | 表示传输的数据是纯文本，没有特定的格式或结构 通常用来传输与格式无关的文本、文本消息等 |
5）还有很多类型，本文不再详细介绍，用户可自行百度了解。
FDL 中：
1）Content-Type 说明：
支持 application/x-www-form-urlencoded、application/json、application/xml、multipart/form-data、text/xml、text/plain 请求格式。
允许用户在 Headers 内对 Content-Type 进行自定义设置，即 Content-Type 的下拉框支持输入非下拉列表值。
2）可自定义 Headers 参数。
4.1.5 Body
FDL 中选择 POST 请求方式时展示此选项
用于传递客户端向服务器发送的数据。通常用于 POST、PUT 等需要在请求中传递数据的 HTTP 方法。
不同的 API 可以要求不同格式的请求体，常见的有 JSON、XML、form-data 等。
FDL 中，Body 与 Content-Type 双向联动：
| Body一级选项 | Body二级选项 | Content-Type默认值 | 说明 |
|---|---|---|---|
| form-data | multipart/form-data | 允许添加多行、每行均为自定义输入、支持引用参数； | |
| x-www-form-urlencoded | application/x-www-form-urlencoded | 允许添加多行、每行均为自定义输入、支持引用参数； | |
| raw | JSON | application/json | |
| XML | application/xml | ||
| TEXT | text/plain |
4.1.6 TLS/SSL 自签名认证
当 API配置了 https 时，支持自签名证书。
配置自签名证书后，当进行 https 请求时，按照 SSL/TLS 协议进行请求处理。
注：支持.p12、.jks的文件类型。
4.2 调用 API 示例
请参见：API取数概述
上一篇：定时任务版本管理
