HTTP Post 分发

将设备数据实时推送到任意 HTTP 接口。适用于对接自有业务系统、触发自动化流程、与第三方平台集成等场景。

工作原理

当设备上报数据时，研几云平台会自动将数据以 HTTP POST 请求的方式发送到您指定的 URL。

快速开始

第一步：创建分发配置

1. 进入「组织 → 数据分发」
2. 点击「新建配置」
3. 选择类型为 HTTP Post
4. 填写您的接收地址
5. 点击「保存」

第二步：使用测试功能验证

在正式使用前，建议先用平台提供的测试功能验证配置是否正确：

1. 在新建配置对话框中，可以看到「测试 URL」
2. 点击旁边的按钮，将测试 URL 填入配置
3. 保存配置后，等待设备上报数据
4. 在配置卡片上点击「查看测试数据」，即可看到接收到的数据

测试功能说明

• 测试 URL 格式：https://dl.yengear.com/api/v2/forwarder-test/{org_slug}/receive/
• 每个组织最多存储 50 条测试数据
• 旧数据会被自动清理
• 测试功能无需认证，仅用于调试

第三步：切换到正式地址

验证数据格式无误后，编辑配置，将 URL 替换为您的正式接收地址。

配置参数

参数	必填	说明
URL	是	接收数据的 HTTP 地址
密钥	否	用于验证请求来源
名称	否	便于识别的配置名称
优先级	否	执行顺序，数值越大越先执行

请求格式

HTTP 请求头

Header	值
Content-Type	application/json
Authorization	Bearer <密钥> （如配置了密钥）

请求体

请求体是一个 JSON 数组，包含一条或多条因子数据：

[
  {
    "agri_id": "d-1000-abc-1-00",
    "t": 1709856000,
    "value": 25.5,
    "the_type": 100,
    "org_id": "your-org-slug"
  },
  {
    "agri_id": "d-1000-abc-1-01",
    "t": 1709856000,
    "value": 65.2,
    "the_type": 101,
    "org_id": "your-org-slug"
  }
]

字段说明

字段	类型	说明
agri_id	string	因子唯一标识
t	integer	Unix 时间戳（秒）
value	number	因子数值
the_type	integer	因子类型编码
org_id	string	组织标识

接收端实现示例

您的接收端需要：

1. 接受 POST 请求
2. 解析 JSON 数组
3. 返回 2xx 状态码表示成功

Node.js (Express) 示例

const express = require('express');
const app = express();

app.use(express.json());

const SECRET_KEY = 'your-secret-key';

app.post('/webhook/iot-data', (req, res) => {
  // 验证密钥（可选）
  const authHeader = req.headers['authorization'];
  if (SECRET_KEY && authHeader !== `Bearer ${SECRET_KEY}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // 处理数据
  const dataPoints = req.body;
  dataPoints.forEach(point => {
    console.log(`因子: ${point.agri_id}, 值: ${point.value}`);
  });
  
  res.json({ success: true });
});

app.listen(3000);

Python (Flask) 示例

from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET_KEY = 'your-secret-key'

@app.route('/webhook/iot-data', methods=['POST'])
def receive_data():
    # 验证密钥（可选）
    auth_header = request.headers.get('Authorization', '')
    if SECRET_KEY and auth_header != f'Bearer {SECRET_KEY}':
        return jsonify({'error': 'Unauthorized'}), 401
    
    # 处理数据
    data_points = request.json
    for point in data_points:
        print(f"因子: {point['agri_id']}, 值: {point['value']}")
    
    return jsonify({'success': True})

if __name__ == '__main__':
    app.run(port=3000)

安全建议

验证请求来源

配置密钥后，每次请求会携带 Authorization 头：

Authorization: Bearer <your-secret-key>

在接收端验证此头信息，确保请求来自研几云平台。

最佳实践

• 使用 HTTPS 地址
• 设置并验证密钥
• 快速处理请求，避免超时
• 返回 2xx 状态码表示成功

常见问题

问题	解决方案
没有收到数据	检查配置是否启用，URL 是否正确
连接失败	确认接收端可公网访问
认证失败	检查密钥是否匹配
请求超时	优化接收端响应速度

应用场景

• 自定义大屏：将数据推送到可视化系统
• 自动化流程：触发 Zapier、Make 等自动化平台
• 告警系统：对接监控系统实现阈值告警
• 数据中台：推送到企业数据处理管道