HTTP请求

约束限制

• 当前仅支持POST、GET两种请求方法。
• 鉴权方式仅支持API Key认证，暂不支持OAuth等其他鉴权协议。
• 不支持流式接口。
• 域名参数需填写为固定值，不支持动态引用变量。
• HTTP请求节点调用的API响应时间不能超过50秒。

添加节点

在工作流编辑页面，单击下方“添加节点”，选择“HTTP请求”节点。

图1 添加HTTP请求节点

配置HTTP请求节点

API：

用于指定请求的目标地址和方法，决定“向哪里发送什么类型的请求”。API配置包含请求方式、域名和路径：

• 请求方式：选择HTTP请求的方法。GET：从外部服务获取数据，适用于查询类操作。POST：向外部服务提交数据，适用于创建、更新类操作。
• 域名：请求目标服务器的域名地址（如 https://api.example.com）。此参数为固定值，不支持动态引用变量。
• 路径：请求的具体接口路径（如 /v1/chat/completions）。支持动态引用变量——通过 {{变量名}} 的方式嵌入输入参数，在运行时自动替换为实际值。

输入参数：

输入参数用于定义可在路径或请求体中动态引用的变量，实现请求内容随上游数据变化而变化。

输入参数支持引用和输入两种传参方式。引用：选择工作流中前置节点的输出值或全局配置中的记忆变量。适用于参数值需要随工作流运行动态变化的场景。输入：自定义填写固定值。适用于参数值确定不变、但希望集中管理便于后续修改的场景。

请求参数：

请求参数是附加在URL末尾的键值对（如 ?keyword=手机&page=1），用于向服务器传递查询条件或筛选信息。

请求参数支持引用和输入两种传参方式。引用：选择前置节点的输出值或全局记忆变量。适用于参数值由上游节点动态生成的场景。输入：自定义填写固定值。适用于参数值固定不变的场景。

请求头：

请求头用于携带请求的附加元信息，例如指定数据格式（Content-Type）、标识客户端类型（User-Agent）等。大多数 API 都要求在请求头中传递特定的字段。

请求参数支持引用和输入两种传参方式。引用：选择前置节点的输出值或全局记忆变量。输入：自定义填写固定值。

请求体：

请求体是HTTP请求中携带的数据内容，通常在API请求中用于向服务器提交结构化数据。支持none和json两种配置模式：

• none：不携带请求体。通常用于GET请求，或不需要提交数据的场景。
• json：以json格式编写请求体。可通过{{变量名}}引用输入参数实现动态拼装。引用字符串类型的变量时，无需在变量外额外添加引号，系统会自动处理类型信息。

鉴权：

鉴权方式用于配置调用外部 API 时的身份认证信息，确保请求能够通过目标服务的安全验证。

• 无需鉴权：目标API不要求身份认证时选择此项，无需配置额外信息。
• API Key：通过API密钥进行身份认证。发起请求时，系统会自动将密钥附加到请求头或URL参数中。选择API Key鉴权时，需要配置以下参数：
  • 传入方式：指定密钥附加的位置。Header：将密钥放入请求头中传递。Query：将密钥作为URL传递。
  • 参数名称：API Key对应的字段名称（如Authorization、api-key等），由目标API指定。
  • 参数值：API Key的具体密钥值。

关于密钥加密：鼠标移动至“参数值”右侧的上，可参看密钥的加密方式。平台默认使用KMS加密 + 默认密钥方式对认证密钥进行加密存储，防止信息泄露。

• 加密机制：使用用户选择的密钥派生DEK进行加密，默认密钥为kms-agentarts/default。
• 费用说明：实例不收费，每月提供20,000次免费调用次数。解密时支持缓存，但敏感数据较多时可能超出免费次数。如需更换加密方式，具体请参考更换密钥的加密方式。

输出方式：

HTTP请求执行完成后，系统会自动生成以下输出参数，供下游节点引用：

• body：HTTP响应的主体内容，即接口返回的实际数据。
• status_code：HTTP响应状态码，表示请求的执行结果。常见值：200表示成功，400表示请求格式错误，401表示认证失败，404表示接口地址不存在，500表示服务器内部错误。
• headers：HTTP响应的头信息，包含响应的元数据（如内容类型、编码方式等）。
• error_message：请求失败时返回的错误描述信息，帮助定位失败原因。请求成功时此字段为空。

异常配置：

在实际使用中，外部API可能因网络波动、服务不可用等原因偶尔请求失败。如果你不希望单个请求的失败导致整条工作流中断，可以开启异常忽略功能。

开启后，当该节点执行失败时，工作流不会中断，而是跳过此节点继续运行后续下游节点。如果下游节点引用了此节点的输出，则使用预先配置的默认输出内容代替实际返回值。

开启异常忽略时，建议同时为输出参数配置合理的默认值，避免下游节点因接收到空值而产生二次异常。

常见问题

• 域名可以动态设置吗

  不可以。域名参数仅支持固定值输入，不支持引用变量。如果你的业务需要根据不同条件调用不同域名的服务，建议通过条件分支节点拆分为多个HTTP请求节点，每个节点配置不同的固定域名。

• 请求路径中如何使用动态参数

  在路径字段中使用 {{变量名}} 语法引用输入参数。例如，需要根据用户ID查询详情：

  1. 添加输入参数user_id，引用上游节点输出的用户ID。
  2. 路径设置为 /api/v1/users/{{user_id}}/profile。

  运行时，{{user_id}} 会被替换为实际的用户ID值。

• 如何判断请求是否成功

  通过输出参数status_code判断。您可以在HTTP请求节点的下游添加条件分支节点，判断status_code是否等于200：

  • 等于200：走正常处理分支，引用body中的返回数据。
  • 不等于200：走异常处理分支，引用error_message查看具体错误原因。
• 接口要求的鉴权方式不是API Key怎么办

  当前HTTP请求节点仅支持API Key认证。如果目标接口要求OAuth、Bearer Token等其他鉴权方式，可以尝试以下变通方案：

  • 手动添加请求头：部分鉴权方式（如Bearer Token）本质上是在请求头中传递固定格式的令牌。您可以在请求头配置中手动添加对应字段，例如参数名称设为Authorization，值设为具体的鉴权信息。
  • 使用插件或者MCP，如果目标API已经封装为插件或者MCP服务，可在工作流中添加插件、MCP。