1. 概述
1.1 版本说明
| FineDataLink 版本 | 功能变动 |
|---|---|
| 1.5 | 数据来源中的数据源类型支持 API |
| 4.1.3 | 支持分页取数，详情参见：API输入-分页取数 |
| 4.1.7.3 | 「高级配置」中支持指定响应数据字符编码方式，详情参见：数据同步-API |
| 历史版本更新 | ||||||||||||||||||
|
1.2 应用场景
用户希望取出 API 数据后做进一步的数据处理再保存，此时，数据同步-API 不能满足需求。
1.3 功能说明
「数据转换」节点中新增「API 输入」算子，使用「API 输入」算子接口取数后，可继续使用其他算子对接口数据进行处理。如下图所示：
注1：若接口返回值为较简单的 JSON 格式，不需要复杂的解析处理，可直接使用 数据同步-API 进行接口取数。
注2：「API 输入」算子从 API 接口取数时，可使用参数，参数值可为动态，参数使用的位置请参见本文第四章说明，具体示例请参见本文第五章说明。
2. 前提条件
1）关于 API 接口信息介绍，详情参见：API入门
2）在使用 API 接口进行取数时，可以提前用 Postman 或者其他 API 调试工具进行测试，确保 API 的可用性。如下图所示：
3）需要注册「接口协议（定时）」功能点。
3. 使用限制
1）当前 FDL 内置的请求超时时间是 10s，如果 API 查询返回时间超过 10s 将导致任务失败。
若用户的数据量较大，接口请求时间较长，4.0.13 及之后版本的 FDL 接口取数时可以在 Header 内使用 FDLTimeout 字段增大超时时间。
需注意参数名称为FDLTimeout，用户不能自定义参数名的大小写（参数名大小写敏感）；参数值需要写入正整数，且单位为秒（s）。如下图所示：
注：若数据量较大，JSON 格式数据建议取消勾选「将解析后的JSON数据展开为二维表」，否则会增加加载响应时间。
2）API 接口取数时，可以在「返回值处理」设置项中对 JSON 数据进行解析，但对比 JSON解析算子 ，功能上有一定限制，如下表所示：
| 对比项 | 区别 |
|---|---|
| JSON解析算子 | 1）JSON解析算子 中可一次性解析多个字段，返回值处理设置项中只能解析一个字段 2）返回值处理设置项中若勾选「将解析后的JSON数据展开为二维表」，将只能解析一层路径；JSON解析算子 可以解析多层路径 |
| 接口取数时，返回值处理设置项（本文 4.1 节内容） |
所以，若接口返回值为较简单的 JSON 格式，不需要复杂的解析处理，可在返回值处理设置项中进行解析；否则，建议使用 JSON解析算子 进行解析。
4. 功能概述
API 取数时，设置界面如下图所示：
注1：从 API 接口取出的数据，可输出为参数（使用参数输出算子、参数赋值节点、全局参数-赋值参数）；或输出到数据库、接口、简道云、文件系统等位置中。
注2：API 接口取数时，当 API 使用了 https ，可以取消证书有效性验证；在 Headers 内新增一个参数，参数名为SSL-certificate-verification，值为 false 即可。详情请参见：注意事项
4.1 各设置项说明
| 序号 | 内容 | 说明 | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| A | 请求方法 | FDL 支持 GET 和 POST 两种请求方式。关于 API 接口说明详情参见：API入门 注：FDL 支持 GET 和 POST 两种请求方式，若您需要使用 PUT 或者 DELETE 请求方法，POST 方法也能满足需求 | ||||||||||||||||||||||
| B | 接口地址 | 需要调用接口的 URL | ||||||||||||||||||||||
| C | 请求参数 URL 传参(Query参数) |
| ||||||||||||||||||||||
| D | Authorization 认证类型 |
| ||||||||||||||||||||||
| E | Headers 请求参数 |
| ||||||||||||||||||||||
| F | Body 请求内容 | 注：选择POST请求方式时展示此选项 Body中支持格式选择，TEXT、JSON、XML body 内容写法如下：
格式为：GET:"a=123&b=456" POST:{"a":123,"b"=456} | ||||||||||||||||||||||
| G | TLS/SSL 自签名认证 | 当 API配置了 https 时，支持自签名证书 配置自签名证书后，当进行 https 请求时，按照 SSL/TLS 协议进行请求处理 注：支持.p12、.jks的文件类型
| ||||||||||||||||||||||
| H | 响应内容如果是JSON格式，可进行后续的处理 | 为空默认解析首层节点，可用「$.父节点.子节点」的格式自定义解析层级，例如： 一层：$.store；两层：$.store.book 详情请参见本文 4.2 节内容 | ||||||||||||||||||||||
| I | 调用频率控制 | 应用场景： 有的接口限制了调用频率，比如有接口一分钟只能调用 3 次，超过这个限制定时任务就会报错 设置「调用频率控制」为每分钟执行 3 次，分页取数时，若页数为 6 页，第一分钟的前几秒调用 3 次 API 取前 3 页数据，等第二分钟到来后，再调用 3 次取最后 3 页数据 功能说明： 在一个任务实例中，分页取数多次调用 API 受「调用频率控制」控制 控制频率：秒/分钟/小时/天
例如控制调用频率为 1 分钟一次，则任务执行后可以看到日志，API 一分钟调用一次： | ||||||||||||||||||||||
| J | 分页取数 | 详情请参见：API输入-分页取数 | ||||||||||||||||||||||
| k | 响应字符编码 | 指定响应数据字符编码方式 支持 UTF-8、UTF-16、GBK 三种方式 将按照字符编码方式解析 API 响应数据 |
4.2 返回值处理说明
接口数据返回值如果是 JSON 格式，想要取出指定的 JSON 数组，可以使用「返回值处理」直接解析 JSON 数据。
数据类型转换列表：
| 类型分类 | 字段类型 |
|---|---|
| 整数类 | long，int |
| 字符串类 | string |
| 浮点类 | double，float |
| 布尔类 | boolean |
| 日期时间类 | date |
| 其他类型 | 显示为空 |
以 http://fine-doc.oss-cn-shanghai.aliyuncs.com/book.json 为例。
4.2.1 默认返回值
API 取数默认返回的结果将包括所有对象，同时解析首层的节点
即返回 store、store.book、store.bicycle、store.bicycle.color、store.bicycle.price 数据。
4.2.2 指定返回值
可以填写自定义的 JSON 路径控制只返回结果中的单个 JSON 对象或者 JSON 数组
使用「父节点.子节点」的格式自定义解析层级，例如： 一层：store；两层：store.book；三层：store.book.author
例如想要取出 store 对象中 book 数组数据，可以在路径中输入：$.store.book，可以获取到 book 数组下的所有数据，如下图所示：
例如想要取出 store 对象中的数据，可以在路径中输入：$.store，可以获取到 store 对象下的首层节点的数据：book、bicycle、bicycle.color、bicycle.price，如下图所示：
更多 JSON 解析表达式详情参见：JSONPath表达式
4.3 与参数功能配合使用说明
4.3.1 说明
API 接口取数时，支持引用参数的设置项为：
| 设置项 | 说明 | 备注 |
|---|---|---|
| 序号C：请求参数(Query参数) | 参数值支持引用参数 | FDL 中配置和使用参数说明请参见：如何配置并使用参数 |
| 序号D：Authorization 认证类型 | Bearer Token：Token值支持引用参数 其他认证：Authorization 值支持引用参数 | |
| 序号E：Headers 请求参数 | 支持引用参数 | |
| 序号F：Body 请求内容 | Body 内容中支持引用参数 |
接口数据输出为参数说明如下表所示：
| 说明 |
|---|
| 参数赋值 节点、参数输出 算子、全局参数-赋值参数 都支持将 API 数据输出为参数，支持获取API响应的响应头header、响应体body、状态码 参数赋值节点、全局参数-赋值参数适用场景： 1）接口返回值为较简单的 JSON 格式，不需要复杂的解析处理 2）全局参数-赋值参数与参数赋值节点区别：全局参数-赋值参数输出的参数，可供多个定时任务使用；参数赋值节点输出的参数，只能供参数赋值节点的下游节点使用 参数输出算子适用场景： 1）接口取数后，数据需要进行复杂处理后，再输出为参数 2）一般情况下使用流程： 示例参考： API取数-获取企业微信人员信息 文档的第一章到 2.2 节内容 |
接口取数时引用参数说明：使用参数
4.3.2 注意事项
1）无论是接口取数时引用参数，或者接口数据输出为参数，都建议参数设置默认值，便于引用参数的节点/算子查看效果；若参数值动态变化（例如每个参数值只能生效 2 分钟），调试任务时，想查看参数引用效果需要更新参数默认值。
注：定时任务每次运行都会获取最新参数值来执行。
2）调用接口时使用参数：
若参数存在空值，调用接口将获取不到数据，所有在调用接口前，需要过滤掉空值。
需要的参数可能需要加密，建议使用 SparkSQL编码、加密、解密函数 实现
若需要动态生成签名值，建议使用「Spark SQL」算子，或使用函数将对应的值拼接出来（SQL 脚本、新增计算列等）。
