API 概述

通过开放 API，你可以管理设备、数据点和数据，快速构建物联网应用。

基本信息

项目	值
Base URL	https://dl.yengear.com/api/v2
协议	HTTPS
格式	JSON

---

数据模型

调用任何接口之前，先了解平台的四级层级结构：

组织（Organization）
  └── 项目（Project）        — project_id，如 proj_xxxx
        └── 设备（Device）   — serial_number / agri_id，如 d-1000-abcd
              └── 数据点（Point）  — agri_id，如 d-1000-abcd-1-000

概念	说明	关键标识符
组织	租户工作空间，所有用户、令牌和项目都属于某个组织。	slug（如 yengear）
项目	同一站点或业务场景下设备的逻辑分组。	project_id（如 proj_xxxx）
设备	与云端通信的物理网关或控制器，通过序列号 + 安全码绑定到项目。	serial_number、agri_id
数据点	设备上的单个采集通道（一个 Modbus 寄存器 = 一个数据点），定义缩放规则、类型和告警阈值，遥测数据通过 agri_id 路由。	agri_id（如 d-1000-abcd-1-000）

数据点的 agri_id 始终以其父设备的 agri_id 为前缀，平台据此无需额外查询即可将上报数据路由到正确的设备和数据点。

面向非技术用户的入门说明，参见 数据模型基础。

---

请求规范

请求头

所有请求必须包含以下 Header：

Header	必填	说明
Authorization	是	认证令牌，格式：Bearer <ACCESS_TOKEN>
X-Organization-Slug	是	组织标识符，如 my-org
Content-Type	POST/PUT	请求体格式，固定为 application/json

请求示例

curl https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"

路径参数

API 路径中的参数使用 {param} 表示，调用时需替换为实际值：

参数	说明	示例
{project_id}	项目 ID	proj_hBonHEAQhm
{device_id}	设备主键 ID	17644
{id}	资源 ID	5855

查询参数

GET 请求的查询参数通过 URL 传递：

GET /api/v2/projects/{project_id}/devices/?page=1&page_size=20

请求体

POST/PUT 请求的数据通过 JSON 格式传递：

curl -X POST https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '{"name": "新项目"}'

---

认证

所有请求需在 Header 中携带 Access Token：

Authorization: Bearer <ACCESS_TOKEN>

Token 可在设备管理平台的「组织设置」页面创建和管理，详见 Access Token。

快速开始

cURL

curl https://dl.yengear.com/api/v2/projects/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-Slug: your-org-slug"

Python

import requests

API_BASE = "https://dl.yengear.com/api/v2"
TOKEN = "YOUR_TOKEN"
ORG_SLUG = "your-org-slug"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-Organization-Slug": ORG_SLUG
}

response = requests.get(f"{API_BASE}/projects/", headers=headers)
print(response.json())

响应格式

成功响应

单个对象直接返回数据，列表返回数组。HTTP 状态码为 200、201 或 204。

{
    "project_id": "proj_abc123",
    "name": "我的项目",
    "device_count": 10
}

错误响应

{
    "error": {
        "code": "NOT_FOUND",
        "message": "项目不存在"
    }
}

HTTP 状态码

状态码	说明
200	请求成功
201	创建成功
204	删除成功（无响应体）
400	请求参数错误
401	未认证或 Token 无效
403	无权限
404	资源不存在
429	请求过于频繁
500	服务器错误

分页

列表接口支持分页：

参数	类型	默认值	说明
page	integer	1	页码
page_size	integer	20	每页数量

限制

• 请求频率：100 次/分钟
• 请求体大小：10 MB

相关文档

• Access Token - 如何创建和管理访问令牌

文档结构

每个资源组包括概述、端点矩阵、详细请求/响应规范、错误情况和可运行示例：

1. 组织管理
2. 组织令牌
3. 项目
4. 设备
5. 数据点
6. 设备数据
7. 数据下载任务

使用 字段参考 了解共享术语，例如 agri_id、project_id 和设备类型代码。