HTTP 请求节点

什么是 HTTP 请求节点？

HTTP 请求节点是 Magic Flow 工作流中用于与外部 API 和网络服务进行交互的重要节点。它就像是您的工作流与外部世界沟通的桥梁，允许您发送各种网络请求（如 GET、POST 等），获取外部数据或向外部系统提交信息。通过这个节点，您可以轻松地将外部服务和数据源集成到您的智能应用中。

图片说明：

HTTP 请求节点界面包括请求 URL、请求方法、请求头和请求体等配置区域，以及响应解析和输出设置部分。通过这些配置，用户可以定义如何与外部 API 交互。

为什么需要 HTTP 请求节点？

在构建智能应用时，往往需要获取外部数据或与其他系统交互，HTTP 请求节点正是为此设计：

• 获取实时数据：从外部 API 获取最新信息，如天气预报、汇率、股票行情等
• 系统集成：与企业内部或第三方系统对接，实现跨系统数据交换
• 触发外部服务：调用外部服务完成特定功能，如发送短信、推送通知等
• 数据提交：向外部系统提交表单数据或其他信息
• 身份验证：对接第三方身份验证服务，如 OAuth 认证

适用场景

1. 数据聚合应用

创建一个汇总多个数据源信息的应用，如将不同平台的销售数据整合到一个报表中，为决策提供全面视图。

2. 集成企业内部系统

将 Magic Flow 工作流与企业内部系统（如 CRM、ERP、OA 等）进行集成，实现数据流转和业务协同。

3. 智能助手增强

通过调用专业 API（如天气 API、翻译 API 等），增强智能助手的能力边界，提供更丰富的服务。

4. 触发器和通知系统

构建能够监控特定事件并触发通知的系统，如库存预警、价格波动提醒等。

节点参数说明

基本参数

参数名称	说明	是否必填	默认值
请求 URL	指定请求的目标地址	是	无
请求方法	选择 HTTP 请求方法(GET/POST/PUT/DELETE 等)	是	GET
请求头	设置 HTTP 请求头信息，如 Content-Type、Authorization 等	否	无
请求体	当使用 POST/PUT 等方法时，设置要发送的数据	否	无

查询参数 (Query)

查询参数会以键值对的形式附加在 URL 后面，格式为?key1=value1&key2=value2

配置项	说明
参数名	查询参数的名称
参数类型	参数的数据类型，如字符串、数字等
参数值	参数的具体值，支持变量引用

路径参数 (Path)

路径参数是 URL 路径中的动态部分，通常在 API 中使用，如/user/{id}

配置项	说明
参数名	路径参数的名称
显示名称	在界面上显示的参数名称
参数类型	参数的数据类型
参数值	参数的具体值，支持变量引用

请求体 (Body)

请求体用于在 POST、PUT 等请求中发送数据

配置项	说明
内容类型	请求体的格式，如 JSON、Form 表单等
请求体内容	请求体的具体内容，根据内容类型有不同的编辑方式

请求头 (Headers)

请求头用于发送 HTTP 请求的元数据

配置项	说明
参数名	请求头的名称
显示名称	在界面上显示的参数名称
参数类型	参数的数据类型
参数值	参数的具体值，支持变量引用

输出设置

配置项	说明
系统输出	HTTP 请求的响应结果会自动存储在系统输出中
自定义输出	可以将响应结果的特定部分提取为自定义变量

使用说明

基本配置步骤

1. 设置请求 URL：
   1. 输入完整的 API 地址，包含协议（http://或 https://）
   2. 可使用变量引用动态 URL，如https://api.example.com/users/
2. 选择请求方法：
   1. GET：用于获取数据，如查询信息
   2. POST：用于提交数据，如创建记录
   3. PUT：用于更新数据，如更新用户信息
   4. DELETE：用于删除数据
3. 配置请求头：
   1. 设置 Content-Type（如 application/json、multipart/form-data 等）
   2. 添加认证信息，如 Authorization: Bearer token
   3. 其他必要的头信息如 Accept、User-Agent 等
4. 编写请求体（适用于 POST/PUT 等方法）：
   1. 对于 JSON 格式，可使用 JSON 编辑器
   2. 可引用变量，如{"name": "", "age": }
5. 配置响应解析：
   1. 选择适当的响应格式（JSON、XML、Text 等）
   2. 设置响应数据的提取路径（如需要）

进阶技巧

JSON 数据处理

处理 JSON 格式的 API 是最常见的场景：

1. 发送 JSON 数据：
   1. 设置 Content-Type 为 application/json
   2. 在请求体中使用正确的 JSON 格式
2. 处理 JSON 响应：
   1. 选择 JSON 响应解析方式
   2. 可通过 JSON 路径提取特定字段，如response.data.items
3. 处理嵌套数据：
   1. 对于复杂的嵌套 JSON，可以在后续节点（如代码执行节点）中进一步处理

认证与安全

与外部 API 交互通常需要认证：

1. 基本认证：
   1. 使用 Authorization 头: Basic base64(username:password)
   2. 可以在请求头中直接配置
2. OAuth 认证：
   1. 获取访问令牌（可能需要单独的 HTTP 请求节点）
   2. 在 Authorization 头中使用: Bearer your_access_token
3. API 密钥认证：
   1. 根据 API 要求，可能在 URL 查询参数、请求头或请求体中添加密钥
   2. 示例：https://api.example.com/data?api_key=your_api_key

注意事项

超时与性能

外部 API 调用可能导致工作流执行延迟：

• 对重要或可能慢的 API 调用设置合理的超时时间
• 对不稳定的 API 配置适当的重试次数
• 考虑使用异步模式处理长时间运行的请求

错误处理

网络请求可能因多种原因失败：

• 配置正确的错误处理机制，如条件分支判断响应状态
• 检查错误输出字段以获取详细的错误信息
• 对关键流程添加回退机制，如 API 不可用时的替代方案

数据安全

处理敏感数据时的注意事项：

• 避免在 URL 中包含敏感信息（如密码），应使用请求头或请求体
• 使用 HTTPS 协议确保数据传输加密
• 考虑使用环境变量或密钥管理系统存储 API 密钥等敏感信息

常见问题

问题 1：如何处理 API 限流问题？

解决方案：许多 API 有调用频率限制，可以：

• 实现请求速率控制，避免短时间内发送过多请求
• 正确处理 429（Too Many Requests）状态码，添加等待逻辑
• 在条件允许的情况下，考虑数据缓存减少 API 调用次数

问题 2：请求返回的数据格式不正确怎么办？

解决方案：数据格式不符合预期时：

• 检查响应解析方式是否正确（JSON/XML/Text）
• 使用代码执行节点对数据进行转换处理
• 确认 API 文档，验证请求参数是否正确

问题 3：如何传递文件或二进制数据？

解决方案：传递文件需要特殊处理：

• 设置 Content-Type 为 multipart/form-data
• 使用正确的请求体格式封装文件数据
• 对于大文件，需要注意请求超时设置

常见搭配节点

节点类型	搭配原因
代码执行节点	处理响应数据，转换格式或提取关键信息
条件分支节点	根据 API 响应状态或内容决定下一步操作
大模型调用节点	将 API 获取的数据作为上下文提供给大模型
变量保存节点	保存 API 返回的关键数据供后续流程使用
循环节点	处理分页 API 或批量请求多个资源