API 集成

开放 API 用于让外部系统主动查询数据、管理资源或创建任务。

本文不重复列出完整接口参数。完整接口规范、请求示例和字段说明请阅读 开放 API 文档。

【配图占位：外部系统通过 API 访问 IoT 云平台的架构图】

什么时候使用 API

适合使用 API 的场景：

• 外部系统定期读取设备数据
• 后台服务查询项目、设备和点位
• 业务系统创建数据下载任务
• 自有网关或设备上报数据
• 自动化运维脚本管理平台资源

如果你希望平台在收到设备数据后立即推送到外部系统，应优先阅读 数据转发。

API 与数据转发

能力	触发方式	适合场景
API	外部系统主动请求	查询、管理、下载、上报
数据转发	平台收到数据后主动推送	实时同步、外部数据库归档

调用 API 前需要准备

信息	说明
API Base URL	见 开放 API 概述
Access Token	在平台组织设置中创建
组织标识	请求头 X-Organization-Slug
项目 ID	访问项目、设备、点位和数据接口时使用
设备或点位 ID	以平台页面或 API 返回值为准

文档映射

你想做的事	阅读
了解认证、请求头、响应格式	开放 API 概述
理解字段含义	字段参考
管理组织令牌	组织令牌
查询组织信息	组织管理
查询或管理项目	项目
查询、绑定或编辑设备	设备
查询或配置点位	数据点
查询实时数据或上报数据	设备数据
创建数据下载任务	数据下载任务

最小请求示例

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

更完整示例请查看 开放 API 文档。

集成建议

• 使用专用访问令牌，不要复用个人登录账号。
• 按系统用途限制 Token 权限和项目范围。
• 对 API 错误码进行处理，尤其是 401、403、404。
• 不要依赖页面 URL 推导内部 ID，应使用 API 返回值。
• 外部系统应能兼容新增字段。