REST 请求步骤
REST 请求步骤将 REST API 调用作为工作流中的一个步骤。它是一个类似 Postman 的单一步骤,涵盖完整的“构建 → 发送 → 检查”循环:选择端点(手动输入,或从 Postman 集合、OpenAPI/Swagger 规范或 HAR 捕获中导入),设置标头、查询参数和正文,发送测试请求查看实时响应,然后保存步骤。
由您选择响应的去向。默认情况下,它会被解析到表中。或者,该步骤也可以将响应捕获到工作流变量中,以便后续步骤根据状态码进行分支,或从正文中读取某个值。
如果在保存之前关闭或重新加载浏览器,编辑器会在该浏览器中保留本地草稿。重新打开同一个步骤,并在出现提示时选择还原,即可恢复未保存的请求设置。
通常需要一个 REST 类型的连接,其中保存了服务的基础 URL 和身份验证信息。该步骤也可以不使用连接,直接调用完整限定的 URL。请参阅 REST 连接。
添加 REST 请求步骤
Section titled “添加 REST 请求步骤”- 打开工作流,并在所需位置添加一个步骤。
- 选择 REST 请求(统一) 作为步骤类型(位于 REST 步骤下)。编辑器将打开,其中包含请求选项卡、响应选项卡和表数据选择选项卡。
在请求选项卡中:
选择提供端点的方式,然后 PlaidCloud 会为您填写请求:
- 手动:自行输入方法和 URL。
- 来自连接的 API 定义:使用保存在所选连接上的 OpenAPI/Swagger 定义,这样无需在每个步骤上重复说明。请参阅下面的重用连接的 API 定义。
- Postman 集合(文件) / Postman 集合(URL):从 Postman 集合导入。
- OpenAPI / Swagger(URL) / OpenAPI / Swagger(文件):从 API 规范导入。
- HAR 存档(文件):导入从浏览器网络日志中捕获的请求。
对于导入的来源,选择加载目录可列出可用的端点,然后在端点下选取一个。该步骤会填入其方法、URL、标头、查询参数和正文,并使用每个参数的示例值或默认值;既无示例值也无默认值的可选参数则默认关闭。如果请求中已有您输入的内容,步骤会在替换前询问。不在字段中输入时,按 Ctrl+Z(Mac 上为 Cmd+Z),或选择撤消替换,即可恢复之前的请求。
大型目录很容易缩小范围:在按方法、路径或名称筛选… 中输入内容,即可只列出匹配的端点。目录会显示它包含的端点数量(筛选时显示 12 of 340)及其加载时间,当非常大的定义在预览上限处被截断时,步骤也会给出提示。
粘贴集合或规范,而不是选择文件
Section titled “粘贴集合或规范,而不是选择文件”三种基于文件的来源(Postman 集合、OpenAPI/Swagger 和 HAR 存档)在文件选择器旁边都提供粘贴… 按钮。如果您手头有内容但尚未将其保存到文档,请使用它:粘贴 JSON,然后选择使用此内容。目录会立即加载,因此之后无需再单击加载目录。
粘贴的内容会代替文件选择器使用,并在步骤保持打开期间有效。它不会随步骤一起保存,因此如果重新打开步骤并想据此重新加载目录,需要再次粘贴。如果您为同一来源选取了文件,则以文件为准,粘贴的内容会被丢弃,发生这种情况时步骤会告知您。
您也可以将 .json 文件拖放到来源选择器上。步骤会根据您选择的来源检查内容,并告诉您哪里有问题,例如在需要 OpenAPI 规范的位置粘贴了 Postman 集合,或者文件不是 JSON;每个来源还有一个 How do I get a …? 链接,说明如何导出 Postman 集合、OpenAPI 规范或 HAR 文件。
重用连接的 API 定义
Section titled “重用连接的 API 定义”为特定服务构建的连接器已经知道自己的端点。通用 REST 和 MuleSoft 连接则不然,它们可以指向任何 API,因此允许您把 API 的定义附加到连接本身。
在连接上设置一次(请参阅通用 REST 连接),然后在使用该连接的任何步骤中:
- 在连接下选取连接。
- 将端点来源设置为来自连接的 API 定义。
- 选择加载目录并选取您的端点。
共用该连接的每个步骤都会提供相同的端点列表,在连接上更新定义会同时更新所有这些步骤。
连接摘要和环境
Section titled “连接摘要和环境”在连接选择器下方,摘要行会显示步骤将使用的内容:身份验证类型、主机,以及连接随每个请求发送的默认标头数量。更改连接后,选择选择器旁边的刷新按钮,即可在不重新打开步骤的情况下重新加载其身份验证、主机和默认标头。当连接定义了环境时,环境选择器用于选择步骤针对哪个环境运行。
连接、方法和端点
Section titled “连接、方法和端点”- 连接:用于身份验证的 REST 连接。不设置则直接调用完整限定的 URL。使用选择器旁边的编辑快捷方式,可以在不离开请求编辑器的情况下查看或编辑所选连接。
- 方法:
GET、POST、PUT、PATCH、DELETE、HEAD或OPTIONS。 - 端点:路径(设置了连接时)或完整的 URL。
标头、查询参数和正文
Section titled “标头、查询参数和正文”- 标头和查询参数是由名称/值行组成的可编辑表,每行都有开启开关和说明。使用添加添加行,使用移除删除行。
- 正文在代码编辑器中保存请求有效负载(JSON、表单或原始内容)。
格式化 JSON会缩进正文,验证 JSON会检查正文并报告任何错误的行号和列号。两者都将每个 {{…}} 变量视为一个值,因此您的变量保持原样。变量参考… 列出请求中可以使用的所有变量,插入 {{…}} 会在光标处放入一个变量。
编辑时,步骤会在请求下方标记问题:
- 出现两次的标头或查询参数名称,其中一个值会丢失。
- 看起来拼写错误的标头名称,并附带 Did you mean… 建议,例如用
Authorisation代替Authorization。 - 以明文输入的机密信息,例如
Authorization或X-API-Key的值。请将其保存在项目变量中,并写成{{project_var.NAME}},这样机密信息就不会存储在步骤中。 - 没有
Content-Type: application/json标头的 JSON 正文,某些服务器会以 HTTP 415 拒绝它。 - 方案拼写错误、路径中有双斜杠、末尾有斜杠或带有多余空格的 URL。
在端点、标头、查询值或正文的任何位置,都可以通过将变量名放入双大括号 {{name}} 中,在运行时注入变量。您也可以对工作流运行变量写作 {{var.name}},对项目变量写作 {{project_var.name}},前缀是可选的,两者解析的是同一个名称。
编辑器会在端点、标头和查询表以及正文编辑器中高亮显示检测到的 {{...}} 标记,因此在测试或保存之前,很容易发现替换项。
只有双大括号会被替换,所以 JSON 正文中的单个 { 或 } 会保持原样,您可以在 JSON 中自由混用变量,例如 {"id": "{{var.order_id}}", "qty": 1}。未知的变量名会使步骤失败,因此拼写错误会立即暴露出来。
当工作流由传感器或 Webhook 启动时,还有四个触发变量可用:{{trigger_sensor_id}}、{{trigger_sensor_type}}、{{trigger_fired_at}} 和 {{trigger_payload_json}}(入站有效负载,为 JSON 字符串,可在后续步骤中解析以访问嵌套字段)。在手动或计划运行时,这些变量解析为空字符串。
- 发送测试请求会使用当前设置发出请求,并在行内显示实时响应,以便您在保存之前确认调用有效。在表单的任何位置按 Ctrl+Enter(Mac 上为 Cmd+Enter)即可发送。状态行显示 HTTP 状态和响应时间,请求进行期间计时器会持续递增。(这只会发送单个请求;分页仅在步骤执行时运行。)
- 测试分页会按配置的分页方式依次请求,并报告跨页返回的记录数(最多到预览上限),以便您在完整运行之前确认分页模式及其参数/路径链接正确。只会发出足以达到上限的页数。
- 复制为 curl会将等效的 curl 命令复制到剪贴板,以便共享或调试(机密信息已被遮蔽)。
- 从 curl 导入则相反:粘贴一条 curl 命令(例如浏览器的“Copy as cURL”),其方法、URL、标头和正文会替换当前请求。基本身份验证(
-u)会变成 Authorization 标头;不受支持的选项会被报告,而不是被悄悄丢弃。使用撤消替换可还原之前的值。
响应会在查看器中打开,提供美化和紧凑两种视图。步骤保持打开期间会保留最近五次测试结果,您可以选取其中一个再次查看或重新运行。当响应包含记录列表时,建议会将项路径设置为找到的第一个列表。
请求预览组会显示运行时将发送的请求(变量已解析,机密信息已遮蔽),而不会实际发送任何内容。编辑后请选择刷新预览。
如果您更改了出站请求字段,并在成功发送测试请求之前保存,PlaidCloud 会询问未成功测试就保存吗?,您可以选择仍然保存,也可以返回。在扇出模式下,可在保存之前使用测试第 1 行来测试第一个驱动行。
在响应选项卡中,设置响应目标位置:
响应会被解析到目标表中,此模式下该项为必填。可以选取现有表,也可以从选择器中创建;视图不在可选范围内。分页与解析组控制解析方式:
-
行格式:当每条记录都是 JSON 对象时为对象(默认),当每条记录都是值的列表时为数组。数组不适用于每个表行一次请求。项路径指明记录在响应中的位置。
-
分页模式:不分页(默认)、偏移量分页、页码分页、下一页 URL 分页、游标分页或 Link 标头分页(RFC 5988)。模式参数和模式路径指明由哪些参数和响应字段驱动分页,仅在选择了分页模式时可用。选择一种模式会用其默认值填充两者,您可以编辑。
模式 模式参数默认值 模式路径默认值 分页方式 偏移量 {"offset": "offset", "limit": "limit"}{"has_more": ["has_more"]}发送偏移量和限制查询参数,并在响应的 has_more为 true 时继续读取。页码 {"offset": "page"}{"has_more": ["has_more"]}在 page参数中发送页码,不发送限制。下一页 URL {}{"next": ["next"]}请求在每个响应的 next路径中找到的 URL。相对 URL 相对于其来源页面解析。游标 {"cursor": "after"}{"has_more": ["has_more"], "cursor": ["next_cursor"]}在 after参数中发送上一个响应的游标。向模式参数添加"send_as": "header"或"send_as": "body_field",可改为将其作为请求标头或正文字段发送。要从响应标头中读取游标(例如 Azure Cosmos DB 发送的x-ms-continuation标头),请在模式路径中放入"token_header": "x-ms-continuation",以替换has_more和cursor;最后一页是没有该标头的那一页。Link 标头 {"rel": "next"}{}跟随 Link响应标头中由rel指定的关系。偏移量和页码在模式参数中接受更多键:
start是第一个偏移量或页码(默认 0),stop_on_empty在项路径处没有记录的第一页停止,因此响应不需要has_more字段,send_limit指明是否发送limit参数(偏移量默认为 true,页码默认为 false)。 -
转储原始 JSON,而不解析为行:存储原始有效负载,而不将其解析为列。
-
重试次数(0 到 100)和超时(秒)(1 到 600):请求在失败时的行为以及可运行的时长。运行最多等待您设置的超时时间;发送测试请求、测试第 1 行和测试分页最多等待 300 秒。重试涵盖连接失败、服务器错误(5xx)以及对幂等方法(GET、HEAD、OPTIONS、DELETE)的速率限制(HTTP 429)。POST、PUT 或 PATCH 仅在收到速率限制(HTTP 429)响应后才会重试,这表示服务器未对其做任何处理;服务器错误之后绝不会重试,因此非幂等的请求正文在服务器可能已执行操作后绝不会被发送两次;当 API 返回
Retry-After标头时,步骤会等待其要求的时间间隔(上限为 2 分钟)后再重试。
表数据选择选项卡将响应的字段映射到目标表的列。检查源 → Populate 会根据实时响应填充映射:它通过步骤的连接发送步骤的请求,与运行时相同。它需要一个连接,并且当方法不是 GET、HEAD 或 OPTIONS 时会先询问。此处不提供汇总和非重复,因为步骤会将解析后的响应直接写入目标表。
将目标位置设置为工作流变量,并给出变量前缀(普通名称,例如 my_call)。步骤会发出一个请求,并写入四个工作流变量:
| 变量 | 内容 |
|---|---|
{prefix}_status |
HTTP 状态码(例如 200)。 |
{prefix}_body |
字符串形式的响应正文(JSON 响应以 JSON 文本存储)。 |
{prefix}_headers |
JSON 文本形式的响应标头。 |
{prefix}_elapsed_ms |
请求耗时,以毫秒为单位。 |
像引用任何工作流变量一样在下游引用它们,例如 {my_call_status}。这是“发出一个请求,然后根据结果分支”模式的构建基础。
每个表行发送一次请求
Section titled “每个表行发送一次请求”默认情况下,步骤发送一个请求。要对表的每一行调用一次 API(例如查找表中的每个客户 ID,或将每一行作为记录 POST),请将发送(在请求选项卡中)设置为每个表行一次请求。这会显示驱动因素表字段:
- 驱动因素表:选取其行驱动请求的表。可以使用选择器从工作流的表中选取,也可以输入表名称。每一行的列都可用作
{{row.column}}标记。 - 驱动因素筛选器 (可选):限制所用行的 SQL
WHERE子句。 - 关键列 (可选):以逗号分隔的驱动列,会带入每个输出行,使结果可以联接回驱动表。
- 行数限制和并发数:要处理的最大行数,以及同时运行的请求数。
- 最大请求数/秒 (可选):限制所有工作线程启动请求的速度,使突发流量不会触发 API 的速率限制(0 = 无限制)。该值可以是小数:0.5 表示每两秒启动一个请求。超过 1000 的值按 1000 运行并给出警告。这与并发数无关:并发数限制同时运行的数量,而最大请求数/秒控制新请求启动的频率。
- Add Idempotency-Key header (可选):对于每行单个(不分页)POST、PUT 或 PATCH 请求,会发送一个由每行派生的稳定
Idempotency-Key标头,使重新运行步骤时不会在支持幂等的 API 上重复创建记录(同一行始终发送相同的键,因此 API 会对重复请求去重)。对于 GET/HEAD/DELETE,或者启用了分页模式时,它会被忽略并给出警告。已自行设置Idempotency-Key的请求会保留它。 - 响应:每个响应如何变成行。解析记录(默认)将每条响应记录写为一行。文本(每个请求一行) 为每个请求写一行,带有
DownloadData和DownloadHeaders列;失败的请求会被丢弃。原始文本,错误作为行同样为每个请求写一行,但会保持正文与服务器发送的完全一致,添加DownloadStatus列,并将 HTTP 或传输错误连同其错误正文和状态保留为一行。每个原始行的正文、标头和错误文本中的凭据都会被遮蔽,对于携带凭据的请求,不会跟随重定向到不同来源。分页不适用于文本模式。在文本(每个请求一行) 中,Keep error response(keep_error_response)会像成功响应一样,将 HTTP 400 或更高响应的正文写入该行,而不是使该行失败;向输出添加 DownloadStatus、DownloadReason 和 DownloadUrl(response_meta)会添加DownloadStatus、DownloadReason和DownloadUrl列,保存响应的状态、原因和最终 URL。两者默认都关闭。步骤表单中有向输出添加 DownloadStatus、DownloadReason 和 DownloadUrl选项;keep_error_response需要通过 AI 助手或 REST API 设置。 - Continue on error:开启时,失败的行会被记录,步骤以警告结束,而不是在第一次失败时中止。运行日志会列出最先失败的几行(按其关键列)以及各自遇到的错误,因此您可以知道哪些行失败了以及原因。
在端点、查询、标头或正文的任何位置使用 {{row.column}} 标记来替换该行的值,例如 GET /customers/{{row.customer_id}}。查询参数中的值会被 URL 编码一次,因此服务器收到的 A 1 和 a/b 与输入的一致。早期版本会编码两次,服务器收到的是 A%201 和 a%2Fb。如果 POST、PUT 或 PATCH 步骤开启了 Add Idempotency-Key header,并且某行的值在查询中需要编码,那么由于请求发生了变化,其键在升级后会变化一次。跨越升级的重新运行可能会对每个这样的行多发送一次重复请求。仅由字母、数字和 -._~ 组成的值不受影响。每行的响应记录会被解析到目标表中(前面加上所有关键列);开启转储原始 JSON,而不解析为行时,则改为每个请求一行。
插入 {{row.column}} 菜单会列出所选驱动因素表的列,因此您可以将 {{row.customer_id}} 这样的标记放入端点或正文(以您最后编辑的字段为准),而无需手动输入列名。编辑时,表单还会列出您用过的 {{row.column}} 标记,并将不属于驱动因素表的列的标记以红色高亮显示,因此在运行步骤之前就能发现拼写错误。
测试第 1 行会读取第一个驱动行(遵循驱动因素筛选器),将其值代入端点、查询、标头和正文,并发出这一个请求,因此您可以在对每一行运行之前确认扇出配置正确。响应与发送测试请求一样在行内显示,同时显示所用的驱动行的值。Preview Row 1 同样会解析第一个驱动行的 {{row.column}} 值,并显示解析后的请求,但不发出请求。
REST 请求步骤与其他步骤一样运行:作为完整运行的一部分,或单独运行(请参阅在工作流中运行单个步骤)。在表模式下,它将解析后的(或原始的)响应写入目标表;在变量模式下,它设置四个变量供后续步骤读取。
- REST 请求步骤参考:简明的字段列表
- 管理工作流变量:跨步骤读取和设置变量
- REST 连接:设置带身份验证的 API 连接