研几科技 · 文档中心

Appearance

设备数据 ​

设备数据接口提供两种功能：

  1. GET: 获取设备下所有数据点的实时数据，数据来源于 Cloudflare D1 实时数据库，带有 2 分钟缓存。
  2. POST: 设备端上报数据，数据会同时发送到 SQS 队列和写入 Cloudflare D1。

获取实时数据 ​

GET /api/v2/projects/{project_id}/devices/{device_id}/data/

响应示例 ​

json
[
    {
        "agri_id": "d-1000-abc123-1-00",
        "value": 25.6,
        "the_type": 2001,
        "unit": "℃",
        "t": 1711008140
    },
    {
        "agri_id": "d-1000-abc123-1-01",
        "value": 65.2,
        "the_type": 2002,
        "unit": "%RH",
        "t": 1711008140
    }
]

响应字段 ​

字段类型描述
agri_idstring数据点标识符
valuenumber当前值
the_typeinteger数据点类型
unitstring数据单位
tinteger时间戳（秒）
bash
curl "https://dl.yengear.com/api/v2/projects/proj_abc/devices/123/data/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"
python
response = requests.get(
    f"{API_BASE}/projects/{project_id}/devices/{device_id}/data/",
    headers=headers
)
for item in response.json():
    print(f"{item['agri_id']}: {item['value']} {item.get('unit', '')}")

说明 ​

  • 返回设备下所有启用数据点的最新数据
  • 数据来源：Cloudflare D1 point_data 表
  • 缓存键：device_data_<device.agri_id>，缓存时间约 2 分钟
  • t 字段为 UTC 时间戳（秒）

上报设备数据 ​

POST /api/v2/projects/{project_id}/devices/{device_id}/data/

请求示例 ​

json
[
    {
        "agri_id": "d-1000-abc123-1-00",
        "value": 25.6,
        "t": 1711008140
    },
    {
        "agri_id": "d-1000-abc123-1-01",
        "value": 65.2
    }
]

请求字段 ​

字段类型必填描述
agri_idstring是数据点标识符，必须以设备 agri_id 为前缀
valuenumber是数据值
tinteger否UTC 时间戳（秒），缺省为当前时间

服务端处理 ​

对于每条有效数据：

  1. 根据 agri_id 查找数据点元数据
  2. 自动补全 the_type 字段
  3. 添加 project_id 和 org_id
  4. 如果 t 缺失或无效，填充当前 UTC 时间戳

数据流向 ​

数据会同时发送到两个目标：

  1. AWS SQS 队列: 供 Lambda 异步处理（规则引擎、MongoDB 存储、告警等）
  2. Cloudflare D1: 供 GET 接口实时查询，每个 agri_id 只保留最新值（UPSERT）

如果 SQS 或 D1 操作失败，错误会被记录但不会阻断响应。

响应示例 ​

json
[
    {
        "agri_id": "d-1000-abc123-1-00",
        "value": 25.6,
        "the_type": 2001,
        "t": 1711008140,
        "project_id": "proj_abc",
        "org_id": "your-org-slug"
    }
]
bash
curl -X POST "https://dl.yengear.com/api/v2/projects/proj_abc/devices/123/data/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '[{"agri_id": "d-1000-abc123-1-00", "value": 25.6}]'
python
data = [
    {"agri_id": "d-1000-abc123-1-00", "value": 25.6},
    {"agri_id": "d-1000-abc123-1-01", "value": 65.2}
]
response = requests.post(
    f"{API_BASE}/projects/{project_id}/devices/{device_id}/data/",
    headers=headers,
    json=data
)
print(f"上报成功: {len(response.json())} 条")

错误码 ​

状态码描述
400请求格式错误
401未授权
403无权限访问该项目/设备
404设备不存在或已禁用

注意事项 ​

  1. 前缀校验: agri_id 必须以设备的 agri_id 为前缀，否则数据会被丢弃
  2. 静默丢弃: 无效数据会被跳过，不会中断整个批次处理
  3. 幂等性: 接口不做去重处理，建议包含 t 字段帮助下游服务识别重复数据
  4. 频率限制: 建议批量上报，避免频繁调用

相关文档 ​