docs/docs/cn/integration/workflow-http-request/index.md
通过 HTTP 请求节点,NocoBase 工作流可以主动向任意 HTTP 服务发送请求,实现与外部系统的数据交互和业务集成。
HTTP 请求节点是工作流中的核心集成组件,允许您在工作流执行过程中调用第三方 API、内部服务接口或其他 Web 服务,获取数据或触发外部操作。
HTTP 请求节点是工作流插件的内置功能,确保 工作流 插件已启用。
请求 URL: 目标 API 地址,支持使用变量
https://api.example.com/users/{{$context.userId}}
请求方法: 选择 GET、POST、PUT、DELETE 等
请求头: 配置 HTTP Headers
{
"Content-Type": "application/json",
"Authorization": "Bearer {{$context.apiKey}}"
}
请求参数:
HTTP 请求节点执行后,响应数据可以在后续节点中使用:
{{$node.data.status}}: HTTP 状态码{{$node.data.headers}}: 响应头{{$node.data.data}}: 响应体数据{{$node.data.error}}: 错误信息(如果请求失败)// 配置
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
city: {{$context.city}}
key: your-api-key
// 使用响应
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}
// 配置
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
Content-Type: application/json
Body:
{
"touser": "{{$context.userId}}",
"msgtype": "text",
"agentid": 1000001,
"text": {
"content": "订单 {{$context.orderId}} 已发货"
}
}
// 配置
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
Authorization: Bearer {{$context.apiKey}}
Content-Type: application/json
// 条件判断
如果 {{$node.data.data.status}} 等于 "paid"
- 更新订单状态为"已支付"
- 发送支付成功通知
否则如果 {{$node.data.data.status}} 等于 "pending"
- 保持订单状态为"待支付"
否则
- 记录支付失败日志
- 通知管理员处理异常
// 配置
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
X-API-Key: {{$context.crmApiKey}}
Content-Type: application/json
Body:
{
"name": "{{$context.customerName}}",
"email": "{{$context.email}}",
"phone": "{{$context.phone}}",
"source": "NocoBase",
"created_at": "{{$context.createdAt}}"
}
Headers:
Authorization: Basic base64(username:password)
Headers:
Authorization: Bearer your-access-token
// 在 Header 中
Headers:
X-API-Key: your-api-key
// 或在 Query 中
Query Parameters:
api_key: your-api-key
需要先获取 access_token,然后使用:
Headers:
Authorization: Bearer {{$context.accessToken}}
使用日志节点: 在 HTTP 请求前后添加日志节点,记录请求和响应数据
查看执行日志: 工作流执行日志中包含详细的请求和响应信息
测试工具: 使用 Postman、cURL 等工具先测试 API
错误处理: 添加条件判断处理不同的响应状态
如果 {{$node.data.status}} >= 200 且 {{$node.data.status}} < 300
- 处理成功逻辑
否则
- 处理失败逻辑
- 记录错误: {{$node.data.error}}
对于不需要立即获取结果的请求,考虑使用异步工作流。
根据 API 的实际响应时间设置超时,避免过长等待。
对于不经常变化的数据(如配置、字典),考虑缓存响应结果。
如果需要多次调用同一 API,考虑使用 API 的批量接口(如支持)。
配置合理的重试策略,但避免过度重试导致 API 限流。
// 验证响应状态
if (![200, 201].includes($node.data.status)) {
throw new Error('API request failed');
}
// 验证数据格式
if (!$node.data.data || !$node.data.data.id) {
throw new Error('Invalid response data');
}
遵守第三方 API 的速率限制,避免被封禁。
记录日志时,注意脱敏处理敏感信息(密码、密钥等)。
| 特性 | HTTP 请求节点 | Webhook 触发器 |
|---|---|---|
| 方向 | NocoBase 主动调用外部 | 外部主动调用 NocoBase |
| 时机 | 工作流执行时 | 外部事件发生时 |
| 用途 | 获取数据、触发外部操作 | 接收外部通知、事件 |
| 典型场景 | 调用支付接口、查询天气 | 支付回调、消息通知 |
这两个功能互补,共同构建完整的系统集成方案。