实体接入 API 选型与决策指南
面向物联网设备与第三方应用的数据上报。为了确保数据能够正确地进入 DTS服务（大视景数字孪生服务）数据层，开发者需要根据设备端的技术特点和业务场景，选择最合适的接入方式。
实体接入方式对比
DTS服务通用网关提供了五种主要的数据上报接口，其对比与选型原则如下表所示：
| 接入方式 | 适用场景 | 报文格式要求 | 平台端配置要求 | 选型建议 |
|---|---|---|---|---|
| HTTP 协议接入 (标准 BV JSON 格式) |
1. 设备或采集端具备灵活的报文组装能力。 2. 愿意在发送端直接适配大视景标准数据格式。 |
必须严格符合大视景标准的 BV JSON 格式规范。 | 极简。只需在平台注册产品并选择“标准数据格式（BV JSON）”，无需开发消息解析脚本。 | 首选推荐。性能最优，无额外开发及维护成本。 |
| HTTP 协议接入 (透传 / 自定义格式) |
1. 硬件或采集端格式已固化，无法为 DTS服务修改数据结构。 2. 设备只能上报原始二进制、十六进制或第三方 JSON 报文。 |
任意格式（二进制 / 十六进制字节流 / 自定义 JSON 结构）。 | 需在 DTS服务产品配置中编写 JavaScript 消息解析脚本，将原始报文双向转换为标准 BV JSON。 | 适用于既有设备改造、老旧硬件接入或不支持 JSON 处理的受限设备。 |
| 自定义 Topic 通信 (自定义 Topic 上报) |
1. 复杂的多租户、多产品统一物理网关路由场景。 2. 需要模拟 MQTT 的 Topic 路由机制，依据上报的 Topic 参数（如 /{productId}/{deviceId}/user/test）动态分发和匹配脚本。 |
自定义格式，但在请求体中必须携带 topic 字段以及业务载荷 payload。 |
需要在平台编写匹配该自定义 Topic 的网关脚本。 | 适用于设备实例数量多、协议类型复杂，且需要通过 Topic 路径进行多维度路由和权限隔离的场景。 |
| MQTT 协议接入 | 1. 采用标准的 MQTT 发布/订阅模式接入。 2. 第三方网关或设备作为 MQTT 客户端向 Broker发布数据。 |
建议为 JSON 格式。字段需与产品 Profile 或解析脚本一致。必须携带 timestamp 时间戳。 |
需在平台配置网关关联的 MQTT Broker 连接凭证、QoS 级别及 Topic 消费路由。多实例下支持 $share 共享订阅模式。 |
适用于物理网关下设备多、需动态自动注册，以及自带 MQTT 客户端功能的系统或传感器接入。 |
| CoAP 协议接入 | 1. 受限设备（CPU/内存受限）采用 CoAP 轻量化协议上报。 2. 支持双向接入：设备上报（CoAP Server）与平台下行服务调用（CoAP Client）。 |
标准 JSON 格式。区分 0=属性、1=事件、2=设备 三种上报 URL 资源路径。 |
上行需设备调用平台网关服务。下行需在网关配置 CoAP 客户端的目标服务地址（暂不支持 DTLS）。 | 适用于低功耗、低带宽且不适用 TCP/HTTP 的受限单片机设备或传感器对接。 |
快速决策流程
graph TD
A[设备/应用数据接入] --> B{选择传输协议?}
B -->|HTTP 协议| C{能修改数据报文?}
C -->|可以| D{愿意适配大视景<br>BV JSON 格式?}
D -->|是| E[选择: HTTP协议接入 - 标准格式]
D -->|否| F{需要类似 MQTT 的<br>Topic 路径路由?}
C -->|无法修改| F
F -->|是| G[选择: 自定义 Topic 通信]
F -->|否| H[选择: HTTP协议接入 - 透传/自定义格式]
B -->|MQTT 协议| I[选择: MQTT 协议接入]
B -->|CoAP 协议| J[选择: CoAP 协议接入]
style E fill:#d4edda,stroke:#28a745,stroke-width:2px
style H fill:#fff3cd,stroke:#ffc107,stroke-width:2px
style G fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
style I fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
style J fill:#f8d7da,stroke:#dc3545,stroke-width:2px
接入方式详解及文档导航
HTTP 协议接入（标准 BV JSON 数据格式）
如果您的系统可以通过代码或配置，直接组装成 DTS服务要求的字段，请直接调用此组 API。 * 开发参考： * 设备注册/上报接口 —— 用于将实体注册到 DTS服务并上报基础状态。 * 属性与事件上报接口 —— 用于设备遥测指标、属性及告警等事件的高频上报。 * 数据规范：请先参阅 BV JSON 格式说明。
HTTP 协议接入（透传 / 自定义格式）
如果您希望在 DTS服务侧做数据适配，设备端只做最简数据透传，请直接调用此组 API。 * 开发参考： * 设备透传上报接口 —— 设备直接发送原始报文。 * 属性与事件透传接口 —— 设备透传告警和遥测数据。 * 脚本二次开发：由于需要编写转换逻辑，请参考 内置脚本二次开发参考 以及 CoreApi 类库 进行消息解析编写。
自定义 Topic 通信
如果您的应用类似于物联网网关转发器，并希望能通过特定 Topic 结构来动态查找设备和路由消息逻辑，请调用此接口。 * 开发参考： * 自定义 Topic 上报接口 —— 携带 Topic 标识的轻量化上报网关接口。
MQTT 协议接入
对于支持 MQTT 客户端的设备或第三方网关，可以通过发布/订阅消息的方式将数据同步到平台。 * 开发参考： * MQTT 协议接入指南 —— 包含 Topic 规划、设备 ID 提取、设备注册、属性与事件上报说明及验收标准。
CoAP 协议接入
对于超低功耗或受限的物联网设备，可以使用轻量级 CoAP 协议（UDP）进行数据的上行上报及下行反控调用。 * 开发参考： * CoAP 协议接入指南 —— 包含上/下行接入地址规范、属性/事件/设备上报协议规范及配置。
接入前置注意事项
- 必须配置网关关联：无论您选择哪种接入方式，创建的产品本体模型都必须在 DTS服务管理界面中关联到通用网关或您的自定义网关下，否则网关服务将无法接收对应
productId的数据并会返回404或权限错误。 - 凭证认证安全：所有 HTTP 上行接入请求都需在请求头中携带
bv-api-key: YOUR_API_KEY以进行安全鉴权，具体密钥可在用户系统的授权模块获取。详见 身份认证概述。
最后编辑：北京-产品-yantings 更新时间：2026-07-07 18:14
