MindStudio HTTP 请求模块技能

用于在任意 MindStudio 工作流中正确、可靠且安全地配置 HTTP 请求模块的生产级参考。

第一步：识别场景并询问用户

在编写任何配置之前，先确定用户的目标。将他们的意图匹配到以下五个场景之一，然后仅提出该场景对应的提问。不要询问其他场景的问题。不要猜测变量名称——使用用户提供的完全一致的名称。

如果用户意图已从上下文中明确（例如他们说“将我的 AI 输出 POST 到 Make 的 webhook”），可直接跳过场景确认，进入对应场景的提问环节。

场景 A：获取数据（GET）

触发条件： 用户希望从 API 获取数据——天气信息、股票价格、用户记录、CRM 联系人等。

请向用户提问：

1. API 的端点 URL 是什么？（包含完整路径的完整 URL）
2. 该端点是否需要 API 密钥或令牌？如果有，请提供请求头名称（如 Authorization、X-Api-Key）？
3. 是否需要查询参数来过滤或指定数据？（如 symbol=AAPL、user_id={{userId}}）
4. 您需要从响应中获取哪些数据？（以便下游处理能正确配置）

方法： GET

正文： 无

内容类型： none

场景 B：发送数据（POST）

触发条件： 用户希望向外部系统提交数据——表单提交、JSON 数据包、潜在客户捕获、AI 输出交付等。

请向用户提问：

1. 您要发送数据的目标端点 URL 是什么？
2. 该端点是否需要 API 密钥或令牌？如果有，请提供请求头名称？
3. 您希望从工作流中发送哪些变量？请列出确切的变量名称（如 {{customer_name}}、{{ai_output}}、{{email}}）。
4. 该端点期望接收 JSON、表单数据还是纯文本？
5. 您期望从响应中获得什么？（如确认 ID、状态字段、无返回）

方法： POST

内容类型： application/json（默认值，除非用户另有说明）

场景 C：更新或修改（PATCH / PUT）

触发条件： 用户希望更新外部系统中的现有记录——CRM 联系人、数据库行、项目记录等。

请向用户提问：

1. 基础端点 URL 是什么？（如 https://api.example.com/contacts）
2. 您工作流中的记录 ID 变量名称是什么？（如 {{contact_id}}、{{record_id}}）——该变量将附加到 URL 后
3. 您是仅更新特定字段（PATCH）还是替换整个记录（PUT）？
4. 哪些字段将被更新？请列出确切的变量名称及其含义。
5. 该端点是否需要 API 密钥或令牌？如果有，请提供请求头名称？
6. 您期望从响应中获得什么？

方法： PATCH（部分更新）或 PUT（完整替换）

内容类型： application/json

场景 D：删除资源（DELETE）

触发条件： 用户希望从外部系统中移除一条记录或资源。

请向用户提问：

1. 基础端点 URL 是什么？
2. 您工作流中的记录 ID 变量名称是什么？（将附加到 URL 后）
3. 该端点是否需要 API 密钥或令牌？如果有，请提供请求头名称？
4. 确认：此操作不可逆。这是您的预期吗？
5. 您期望从响应中获得什么？（许多 DELETE 端点返回 204 且无响应体）

方法： DELETE

正文： 无

内容类型： none

安全规则： 在未获得用户明确确认删除操作为预期行为前，不得生成 DELETE 配置。

场景 E：触发外部系统

触发条件： 用户希望在工作流中某个事件发生时，向外部系统发送信号——Webhook、Make/Zapier 触发器、通知、流程启动、跨工作流调用等。

请向用户提问：

1. Webhook 或触发器的 URL 是什么？
2. 是否需要认证请求头？（许多 Webhook 不需要）
3. 您希望在触发载荷中包含哪些数据？请列出确切的变量名称。
4. 外部系统在成功时返回什么？（如 Make 返回 {"accepted": true}，有些返回 200 但无内容）
5. 触发执行后，工作流中是否有其他操作？（如按成功/失败分支、记录结果）

方法： POST

内容类型： application/json

第二步：生成模块配置

在用户回答完其场景的所有问题后，输出一个完整的、可直接复制粘贴的模块配置，结构如下：

URL          : [完整 URL，包含所需变量]
Method       : [GET / POST / PATCH / PUT / DELETE]
Content-Type : [application/json / none / 其他]

Headers:
  [Key]  : [Value]
  [Key]  : [Value]

Parameters (仅 GET):
  [key]  : [value]

Body:
[使用确切变量名称的 JSON 或表单结构]

Output Variable: [描述性名称]

随后立即接上下游处理模块：

On success (ok = true):
  - [对响应的处理方式]
  - [如何访问特定字段]

On failure (ok = false):
  - 检查 {{outputVar.status}} 获取错误码
  - [推荐的分支或备用方案]

模块输出字段

每个 HTTP 请求模块无论方法或端点如何，都会返回四个字段：

在下游使用时通过以下方式访问：

{{outputVar.ok}}
{{outputVar.status}}
{{outputVar.statusText}}
{{outputVar.response}}

如果响应体为 JSON 格式，应将 {{outputVar.response}} 传递给下游的“生成文本”或“运行函数”模块以进行解析和字段提取。切勿直接从原始响应字符串中访问嵌套字段。

配置字段参考

URL

• 必须为完整且有效的 URL，包含 https://
• 支持变量：https://api.example.com/users/{{userId}}
• 严禁在 URL 中硬编码 API 密钥或令牌 —— 应使用请求头传递

方法

请求头

Content-Type    : application/json
Authorization   : Bearer {{apiKey}}
Accept          : application/json
X-Api-Key       : {{serviceKey}}

• 发送请求体时，必须包含 Content-Type
• 若接口需要认证，必须包含 Authorization
• 所有值均支持 {{variable}} 语法

参数

查询字符串中的键值对，通常用于 GET 请求。

symbol    : {{ticker}}
token     : {{apiKey}}
from      : {{startDate}}

内容类型

请求体

**当内容类型为 application/json 时：**

{
  "customer_name": "{{customer_name}}",
  "email": "{{email}}",
  "ai_output": "{{generatedText}}",
  "submitted_at": "{{timestamp}}"
}

**当内容类型为 application/x-www-form-urlencoded 时：**

customer_name={{customer_name}}&email={{email}}

对于 GET / DELETE 请求： 请留空请求体，并将内容类型设为 none。

输出变量

始终设置。使用能反映数据来源的描述性名称。

makeResponse
crmResult
stockData
userRecord
patchResult

请求构建规则

1. 方法选择 —— POST 用于创建/触发，PATCH 用于部分更新，PUT 用于完全替换，GET 用于只读，DELETE 用于删除
2. 请求头 —— 发送请求体时必须包含 Content-Type；需要认证时必须包含鉴权头；不得省略必需的请求头
3. 请求体 —— 每个字段必须来自实际的工作流变量或硬编码字面量；不得虚构字段值
4. 变量使用 —— 全局使用 {{variableName}} 语法；使用点号表示法访问上游块中的嵌套数据
5. 输出变量 —— 必须命名；使用 response 前务必检查 ok 状态

输出处理

成功（ok = true，状态码 2xx）

1. 在继续执行前，先检查 {{outputVar.ok}} 是否为 true
2. 通过 {{outputVar.response}} 访问原始响应体
3. 若响应体为 JSON，应在下游块中解析后才能使用其中的字段
4. 将相关字段存储或记录，供后续工作流使用

失败（ok = false，状态码 4xx 或 5xx）

响应格式错误

• 不得将非 JSON 响应解析为 JSON
• 路由至错误分支并记录 {{outputVar.response}} 以供调试
• 绝不将未经处理的异常内容传递给下游 AI 块

可靠性规则

关键数据缺失：

• 在 HTTP 请求块执行前，使用条件判断块验证必要变量是否为空
• 若关键字段缺失，应路由至错误提示块 —— 不得发送不完整的请求

API 调用失败：

• 在请求块后立即检查 {{outputVar.ok}}
• 出现失败时需进行分支处理 —— 不得假设调用成功

重试逻辑：

• 对不稳定端点（如限流、503 错误），在重试之间添加等待块
• 最多尝试 2–3 次，之后路由至永久失败状态
• 不得对 4xx 错误进行重试 —— 这类错误是逻辑或配置问题，非临时故障

响应验证：

• 在收到 2xx 响应后，确认 {{outputVar.response}} 非空
• 在传递给下游块前，确认预期字段存在

安全规则

绝对禁止。无例外。

1. 不得在请求体中发送未定义或空值的变量 —— 必须在上游进行验证
2. 不得虚构字段名 —— 仅使用用户或 API 文档中确认的字段
3. 不得在 URL 或请求体中硬编码 API 密钥、令牌或密码 —— 必须通过工作流变量注入
4. 不得向 GET、HEAD 或 DELETE 请求发送请求体
5. 发送请求体时不得省略 Content-Type —— 类型不匹配会导致静默失败
6. 不得将原始响应字符串直接传递给下游 AI 块，除非明确标注格式
7. 不得对 4xx 错误进行重试 —— 重试无法修复错误请求
8. 未获得用户明确确认前，不得配置 DELETE 操作

示例配置

示例 1：GET —— 从 Finnhub 获取股票报价

URL          : https://finnhub.io/api/v1/quote?symbol={{ticker}}&token={{finnhubApiKey}}
Method       : GET
Content-Type : none
Headers      :
  Accept : application/json
Body         : (空)
Output Variable: stockData

成功时：解析 {{stockData.response}} —— 字段 "c" 为当前价格
失败时：记录 {{stockData.status}} —— 检查 API 密钥和股票代码

示例 2：POST —— 将 AI 输出发送至 Make Webhook

URL          : https://hook.us1.make.com/{{webhookId}}
Method       : POST
Content-Type : application/json
Headers      :
  Content-Type : application/json
Body:
{
  "customer_name": "{{customer_name}}",
  "email": "{{email}}",
  "ai_output": "{{generatedText}}",
  "submitted_at": "{{timestamp}}"
}
输出变量: makeResponse

成功时：Make 返回 {"accepted": true} — 记录日志并继续执行
失败时：记录 {{makeResponse.status}} — 确认 webhook 地址是否有效

示例 3：PATCH — 更新 CRM 联系人

URL          : https://api.hubspot.com/crm/v3/objects/contacts/{{contact_id}}
Method       : PATCH
Content-Type : application/json
Headers      :
  Content-Type  : application/json
  Authorization : Bearer {{hubspotApiKey}}
Body:
{
  "properties": {
    "lead_score": "{{lead_score}}",
    "last_contacted": "{{timestamp}}",
    "notes": "{{ai_summary}}"
  }
}
输出变量: crmResult

成功时：{{crmResult.ok}} = true — 记录已更新
404 错误时：contact_id 不正确 — 检查变量源块的值
422 错误时：字段名称不匹配 — 验证 HubSpot 的属性名称是否正确

示例 4：DELETE — 删除资源

URL          : https://api.example.com/records/{{record_id}}
Method       : DELETE
Content-Type : 无
Headers      :
  Authorization : Bearer {{apiKey}}
Body         : (空)
输出变量: deleteResult

成功时：状态码为 204 — 无返回内容，删除成功
404 错误时：record_id 不存在或已被删除
403 错误时：API 密钥无删除权限

示例 5：POST — 触发 Zapier Webhook

URL          : https://hooks.zapier.com/hooks/catch/{{zapId}}/{{hookId}}/
Method       : POST
Content-Type : application/json
Headers      :
  Content-Type : application/json
Body:
{
  "event": "workflow_completed",
  "user_email": "{{email}}",
  "result": "{{ai_output}}",
  "timestamp": "{{timestamp}}"
}
输出变量: zapierResponse

成功时：Zapier 返回 {"status": "success"} — 触发确认
失败时：记录 {{zapierResponse.status}} — 确认 Zap 是否启用且 URL 正确

预飞行检查清单

URL 和方法：

• [ ] URL 完整且以 https:// 开头
• [ ] 方法与预期操作一致
• [ ] URL 中的动态值使用 {{variableName}} 语法

请求头：

• [ ] Content-Type 已设置，并与请求体格式匹配
• [ ] 若接口需要认证，已包含认证头
• [ ] API 密钥从变量注入 — 未硬编码

请求体：

• [ ] 块设置中的内容类型与 Content-Type 头一致
• [ ] 每个字段均使用真实的工作流变量或字面量值
• [ ] 无字段使用未定义或空值的变量
• [ ] GET 和 DELETE 请求的请求体为空

输出：

• [ ] 输出变量已命名且具有描述性
• [ ] 后续块在使用 {{outputVar.response}} 前检查 {{outputVar.ok}}
• [ ] 存在 ok = false 的错误处理分支