REST 请求步骤

说明

REST 请求步骤在工作流中以一个步骤的形式调用 REST API。它是一个 Postman 风格的单一步骤，涵盖整个“构建 → 发送 → 检查”循环：选择端点（手动输入，或从 Postman 集合、OpenAPI/Swagger 规范或 HAR 捕获中导入），设置标头、查询参数和正文，发送测试请求查看实时响应，然后保存步骤。

响应的去向由您选择。默认情况下，响应会被解析为表。此外，步骤也可以将响应捕获到工作流变量中，以便后续步骤根据状态码进行分支，或从正文中读取某个值。

如果在保存之前关闭或重新加载浏览器，编辑器会在该浏览器中保留一份本地草稿。重新打开同一步骤，并在出现提示时选择还原，即可恢复未保存的请求设置。

开始之前

通常需要一个 REST 类型的连接，其中保存服务的基础 URL 和身份验证信息。步骤也可以不使用连接，直接调用完整限定的 URL。参见 REST 连接。

添加 REST 请求步骤

打开工作流，并在需要的位置添加一个步骤。
选择 REST Request (unified) 作为步骤类型（位于 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）和加载时间，当极大的定义在预览上限处被截断时，步骤也会给出说明。

粘贴集合或规范，而不是选取文件

三种基于文件的来源（Postman 集合、OpenAPI/Swagger 和 HAR 存档）都在文件选取器旁提供一个粘贴… 按钮。当手头有内容但尚未保存到 Document 时可使用它：粘贴 JSON 并选择使用此内容。目录会立即加载，因此之后无需再单击加载目录。

粘贴的内容会取代文件选取器，并在步骤保持打开期间有效。它不会随步骤一起保存，因此如果重新打开步骤并希望据此重新加载目录，请再次粘贴。如果为同一来源选取了文件，则以文件为准，粘贴的内容会被丢弃，发生这种情况时步骤会提示您。

也可以把 .json 文件拖放到来源选取器上。步骤会根据您选择的来源检查内容，并指出问题所在，例如在应为 OpenAPI 规范的位置粘贴了 Postman 集合，或文件不是 JSON；每个来源还有一个 How do I get a …? 链接，说明如何导出 Postman 集合、OpenAPI 规范或 HAR 文件。

复用连接的 API 定义

为特定服务构建的连接器已经知道它们的端点。通用 REST 连接和 MuleSoft 连接则不然，它们可以指向任意 API，因此允许您把 API 的定义附加到连接本身。

在连接上设置一次（参见通用 REST 连接），之后在任何使用该连接的步骤中：

在连接下选取该连接。
将端点来源设置为来自连接的 API 定义。
选择加载目录并选取端点。

共用该连接的每个步骤都会提供同一份端点列表，在连接上更新定义会同步更新所有这些步骤。

连接摘要和环境

在连接选取器下方，摘要行会显示步骤将使用的内容：身份验证类型、主机，以及连接随每个请求发送的默认标头数量。更改连接后，请选择选取器旁的刷新按钮，无需重新打开步骤即可重新加载其身份验证、主机和默认标头。当连接定义了环境时，环境选取器用于选择步骤针对哪个环境运行。

连接、方法和端点

连接：用于身份验证的 REST 连接。不设置则直接调用完整限定的 URL。使用选取器旁的编辑快捷方式，可在不离开请求编辑器的情况下查看或编辑所选连接。
方法：GET、POST、PUT、PATCH、DELETE、HEAD 或 OPTIONS。
端点：路径（设置了连接时）或完整 URL。

标头、查询参数和正文

标头和查询参数是可编辑的名称/值行表格，每行带有开启开关和说明。使用添加添加行，使用移除删除行。
正文在代码编辑器中保存请求负载（JSON、表单或原始内容）。

格式化 JSON 会缩进正文，验证 JSON 会检查正文并报告任何错误所在的行和列。两者都会把每个 {{…}} 变量当作一个值读取，因此变量会保持原样。变量参考… 会列出请求中可使用的所有变量，插入 {{…}} 会在光标处放入一个变量。

编辑时，步骤会在请求下方标出问题：

标头或查询参数名称出现两次，其中一个值会丢失。
看起来拼写有误的标头名称，会附带 Did you mean… 建议，例如用 Authorisation 代替 Authorization。
以明文输入了密钥，例如 Authorization 或 X-API-Key 的值。请把它保存在项目变量中，并写成 {{project_var.NAME}}，这样密钥就不会存储在步骤里。
JSON 正文没有 Content-Type: application/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 秒。重试涵盖幂等方法（GET、HEAD、OPTIONS、DELETE）的连接失败、服务器错误（5xx）和速率限制（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}。这是“发出一次请求，然后根据结果分支”这类模式的基础构件。

为每个表行发送一次请求

默认情况下，步骤只发送一次请求。要针对表的每一行各调用一次 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，且查询中有需要编码的行值，则由于请求发生了变化，其键在升级后会改变一次。跨越升级的重新运行，可能会为每个这样的行多发送一次重复请求。仅由字母、数字和 -._~ 组成的值不受影响。每行响应的记录都会被解析到目标表中（并在前面加上所有关键列）；开启 Dump raw JSON 后，则改为每个请求一行。

插入 {{row.column}} 菜单会列出所选驱动因素表的列，这样就可以把类似 {{row.customer_id}} 的标记放入端点或正文（取决于您最后编辑的字段），而不必手动输入列名。编辑时，表单还会列出您用过的 {{row.column}} 标记，并以红色高亮显示不属于驱动因素表的列，因此在运行步骤之前就能发现拼写错误。

测试第 1 行会读取第一个驱动因素行（遵循驱动因素筛选器），将其值代入端点、查询、标头和正文，并发出那一个请求，以便在对每一行运行之前确认扇出配置正确。响应会像发送测试请求一样内联显示，同时显示所用的驱动因素行的值。Preview Row 1 同样会解析第一个驱动因素行的 {{row.column}} 值，并在不发出请求的情况下显示解析后的请求。

运行步骤

REST 请求步骤与其他步骤一样运行，可作为完整运行的一部分，也可单独运行（参见在工作流中运行单个步骤）。在表模式下，它会把解析后（或原始）的响应写入目标表；在变量模式下，它会设置四个变量供后续步骤读取。

后续步骤

REST 请求步骤参考：简明的字段列表
管理工作流变量：跨步骤读取和设置变量
REST 连接：设置带身份验证的 API 连接