最新历史版本 :API输入 返回文档
编辑时间: 内容长度:图片数:目录数: 修改原因:
[helpvideo]13439[/helpvideo]

目录:

1. 概述编辑

1.1 版本说明

FineDataLink 版本功能变动
1.5数据来源中的数据源类型支持 API
4.1.7.3「高级配置」中支持指定响应数据字符编码方式，详情参见：数据同步-API
4.2.9.4JSON 解析后支持自定义输出字段


历史版本更新
FineDataLink 版本功能变动
4.0.9

  • 请求类型为POST时，「请求参数」支持传入XML格式数据

  • 对于GET与POST请求，支持输出XML格式数据，支持预览XML响应结果

4.0.10API交互优化、支持 text/plain 格式的请求内容
4.0.11API中 webservice 接口取数优化，详情参见：API 输入- webservice
4.0.13JSON 返回值处理优化
4.0.17API 支持自定义认证
4.0.19数据去向支持 API 输出，同时数据来源 API 支持关闭 SSL 证书验证，详情参见 API关闭证书验证
4.0.23

API 配置中的 body 请求内容支持使用 Content-Type 为 form-data 和 x-www-form-urlencoded 请求格式，

允许添加多行、每行均为自定义输入、支持引用参数

4.1.1

  • 当 API 配置了 https 时，支持自签名证书

  • 支持控制 API 调用频率

4.1.3支持分页取数，详情参见：API输入-分页取数

1.2 应用场景

用户希望取出 API 数据后做进一步的数据处理再保存，此时，数据同步-API 不能满足需求。

1.3 功能说明

「数据转换」节点中新增「API 输入」算子，使用「API 输入」算子接口取数后，可继续使用其他算子对接口数据进行处理。如下图所示：

注1：若接口返回值为较简单的 JSON 格式，不需要复杂的解析处理，可直接使用 数据同步-API 进行接口取数。

注2：「API 输入」算子从 API 接口取数时，可使用参数，参数值可为动态，参数使用的位置请参见本文第四章说明，具体示例请参见本文第五章说明。

6.png

2. 前提条件编辑

1）关于 API 接口信息介绍，详情参见：API入门

2）在使用 API 接口进行取数时，可以提前用 Postman 或者其他 API 调试工具进行测试，确保 API 的可用性。如下图所示：

1721112518798920.png

3）需要注册「接口协议（定时）」功能点。

3. 使用限制编辑

1）当前 FDL 内置的请求超时时间是 10s，如果 API 查询返回时间超过 10s 将导致任务失败。

若用户的数据量较大，接口请求时间较长，4.0.13 及之后版本的 FDL 接口取数时可以在 Header 内使用 FDLTimeout 字段增大超时时间。

需注意参数名称为FDLTimeout，用户不能自定义参数名的大小写（参数名大小写敏感）；参数值需要写入正整数，且单位为秒（s）。如下图所示：

注：若数据量较大，JSON 格式数据建议取消勾选「将解析后的JSON数据展开为二维表」，否则会增加加载响应时间。

7.png

2）API 接口取数时，可以在「返回值处理」设置项中对 JSON 数据进行解析，但对比 JSON解析算子 ，功能上有一定限制，如下表所示：

对比项
区别
JSON解析算子

1）JSON解析算子 中可一次性解析多个字段，返回值处理设置项中只能解析一个字段

2）返回值处理设置项中若勾选「将解析后的JSON数据展开为二维表」，将只能解析一层路径；JSON解析算子 可以解析多层路径

接口取数时，返回值处理设置项（本文 4.1 节内容）

所以，若接口返回值为较简单的 JSON 格式，不需要复杂的解析处理，可在返回值处理设置项中进行解析；否则，建议使用 JSON解析算子 进行解析。

3）若 URL 中的参数值包含[]，需要使用 encodeURIComponent 编码后再填入，否则会调用接口失败。

4. 功能概述编辑

API 取数时，设置界面如下图所示：

注1：从 API 接口取出的数据，可输出为参数（使用参数输出算子、参数赋值节点、全局参数-赋值参数）；或输出到数据库、接口、简道云、文件系统等位置中。

注2：API 接口取数时，当 API 使用了 https ，可以取消证书有效性验证；在 Headers 内新增一个参数，参数名为SSL-certificate-verification，值为 false 即可。详情请参见：注意事项

2.png

4.1 各设置项说明

序号内容说明
A

请求方法

FDL 支持 GET 和 POST 两种请求方式。关于 API 接口说明详情参见：API入门

B

接口地址

需要调用接口的 URL
C

请求参数

URL 传参(Query参数)

  • 可手动添加参数，填写参数名、参数值

  • 也可以直接在URL后添加参数。例如：

9.png

DAuthorization 认证类型

  • 无认证（默认）

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

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

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

EHeaders 请求参数

  • 支持 application/x-www-form-urlencoded、application/json、application/xml、multipart/form-data、text/xml、text/plain 请求格式

  • 允许用户在 Headers 内对 Content-Type 进行自定义设置，即 Content-Type 的下拉框支持输入非下拉列表值

10.png

  • Body与Content-Type双向联动

Body一级选项Body二级选项Content-Type默认值说明
form-data
multipart/form-data 允许添加多行、每行均为自定义输入、支持引用参数
x-www-form-urlencoded
application/x-www-form-urlencoded允许添加多行、每行均为自定义输入、支持引用参数
rawJSONapplication/json
XMLapplication/xml 
TEXTtext/plain

  • 如果输入的 Content-Type 不在联动列表内，则 Body 内格式在改变 Content-Type 前不发生变化

  • 如果用户输入不在列表内的 Content-Type 后，再修改Body的格式，则自动覆盖Headers内的Content-Type为联动值

FBody 请求内容

注：选择POST请求方式时展示此选项

Body中支持格式选择，TEXT、JSON、XML

body 内容写法如下：

  • GET 方法：abc=1&def=1

  • POST 方法：JSON 类型参数

格式为：GET:"a=123&b=456" POST:{"a":123,"b"=456}

GTLS/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
其他类型显示为空

以 https://fine-build.oss-cn-shanghai.aliyuncs.com/finedata/doc/book.json 为例。

1721207366451953.png

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 数组下的所有数据，如下图所示：

14.png

例如想要取出 store 对象中的数据，可以在路径中输入：$.store，可以获取到 store 对象下的首层节点的数据：book、bicycle、bicycle.color、bicycle.price，如下图所示：

15.png

更多 JSON 解析表达式详情参见：JSONPath表达式

4.3 与参数功能配合使用说明

4.3.1 说明

API 接口取数时，支持引用参数的设置项为：

14.png

设置项
说明备注
Params(Query参数)参数值支持引用参数FDL 中配置和使用参数说明请参见：如何配置并使用参数
Authorization 认证类型

Bearer Token：Token值支持引用参数

其他认证：Authorization 值支持引用参数

Headers 请求参数支持引用参数
Body 请求内容Body 内容中支持引用参数

接口数据输出为参数说明如下表所示：

3.png

说明
参数赋值 节点、参数输出 算子、全局参数-赋值参数 都支持将 API 数据输出为参数，支持获取API响应的响应头header、响应体body、状态码

参数赋值节点、全局参数-赋值参数适用场景：

1）接口返回值为较简单的 JSON 格式，不需要复杂的解析处理

2）全局参数-赋值参数与参数赋值节点区别：全局参数-赋值参数输出的参数，可供多个定时任务使用；参数赋值节点输出的参数，只能供参数赋值节点的下游节点使用

参数输出算子适用场景：

1）接口取数后，数据需要进行复杂处理后，再输出为参数

2）一般情况下使用流程：

  • 先使用「API 输入」算子将接口数据取出

  • 使用「JSON解析」算子/「XML解析」算子对接口数据进行解析

  • 再使用其他算子对解析后的数据进行处理

  • 最后使用「参数输出」算子输出为参数

示例参考：

API取数-获取企业微信人员信息 文档的第一章到 2.2 节内容

接口取数时引用参数说明：使用参数

4.3.2 注意事项

1）无论是接口取数时引用参数，或者接口数据输出为参数，都建议参数设置默认值，便于引用参数的节点/算子查看效果；若参数值动态变化（例如每个参数值只能生效 2 分钟），调试任务时，想查看参数引用效果需要更新参数默认值。

注：定时任务每次运行都会获取最新参数值来执行。

2）调用接口时使用参数：

  • 若参数存在空值，调用接口将获取不到数据，所有在调用接口前，需要过滤掉空值。

  • 需要的参数可能需要加密，建议使用 SparkSQL编码、加密、解密函数 实现

  • 若需要动态生成签名值，建议使用「Spark SQL」算子，或使用函数将对应的值拼接出来（SQL 脚本、新增计算列等）。

5. API 取数实际应用编辑

API 取数使用说明请参见：API取数使用说明

API 取数功能所有示例参考：API取数概述