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

目录:

1. 概述编辑

1.1 版本说明

FineDataLink 版本功能变动
1.5数据来源中的数据源类型支持 API
4.1.3支持分页取数,详情参见:API输入-分页取数
4.1.7.3「高级配置」中支持指定响应数据字符编码方式,详情参见:数据同步-API


历史版本更新
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 调用频率

1.2 应用场景

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

1.3 功能说明

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

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

4.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数据展开为二维表」,否则会增加加载响应时间。

8.png

2)API 接口取数时,可以在「返回值处理」设置项中对 JSON 数据进行解析,但对比 JSON解析算子 ,功能上有一定限制,详情可参见本文 5.2.2 节内容。

4. 功能概述编辑

API 取数时,设置界面如下图所示:

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

注2:接口取数取出后,可先使用「JSON解析」算子/「XML解析」算子对接口数据进行解析,再使用其他算子对数据进行处理,最后再进行保存。

9.png

4.1 各设置项说明

序号内容说明
A

请求方法

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

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

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

详情请参见本文第五章

I

调用频率控制

当用户设置当前API调用的频率限制时,可在一次执行实例中控制该API的调用频率

控制频率:秒/分钟/小时/天

例如控制调用频率为 1 分钟一次,则任务执行后可以看到日志,API 一分钟调用一次:

J
分页取数详情请参见:API输入-分页取数
k响应字符编码

指定响应数据字符编码方式

支持 UTF-8、UTF-16、GBK 三种方式

将按照字符编码方式解析 API 响应数据

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

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

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

Bearer Token:Token值支持引用参

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

序号E:Headers 请求参数支持引用参数
序号F:Body 请求内容Body 内容中支持引用参数

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

说明
参数赋值 节点、参数输出 算子、全局参数-赋值参数 都支持将 API 数据输出为参数

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

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

2)全局参数-赋值参数参数赋值节点区别:全局参数-赋值参数输出的参数,可供多个定时任务使用;参数赋值节点输出的参数,只能供参数赋值节点的下游节点使用

参数输出算子适用场景:

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

2)一般情况下使用流程:

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

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

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

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

示例参考:

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

接口取数时引用参数说明:使用参数说明请参见:使用参数

5. 返回值处理说明编辑

接口数据返回值如果是 JSON 格式,想要取出指定的 JSON 数组,可以使用「返回值处理」直接解析 JSON 数据。

数据类型转换列表:

类型分类字段类型
整数类long,int
字符串类string
浮点类double,float
布尔类boolean
日期时间类date
其他类型显示为空

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

1721113554871504.png

5.1 默认返回值

API 取数默认返回的结果将包括所有对象,同时解析首层的节点

即返回 store、store.book、store.bicycle、store.bicycle.color、store.bicycle.price 数据。

5.2 指定返回值

5.2.1 功能说明

可以填写自定义的 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表达式

5.2.2 与JSON解析算子对比


对比项
区别
JSON解析算子

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

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

接口取数时,返回值处理设置项(本文 5.2.1 节内容)

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


6. 最佳实践编辑

参见文档:API取数概述