数字孪生服务 (DTS) 对接开发指南

欢迎使用大视景数字孪生服务 (Digital Twin Service, 简称 DTS) 开放能力对接开发指南。本文档为第三方开发者提供全面的集成对接指导，帮助您高效地完成外部系统与 DTS 平台的双向数据流互通、设备管控及孪生体组织建模。

👥 适用对象

根据开发职责的不同，本指南主要面向以下三类技术人员：

1. 物联网网关与设备端开发人员

   • 关注焦点：如何将物理设备或子系统通过网关接入 DTS、如何设计遥测上报报文、何时使用自定义解析脚本解析非标协议。
   • 相关章节：实体接入 API、内置脚本二次开发参考。

2. 第三方应用与系统集成开发人员

   • 关注焦点：如何向设备下发反控指令、如何动态创建或同步孪生产品与设备信息、如何被动接收 DTS 的实时数据推送、如何检索历史曲线。
   • 相关章节：实体服务调用 API、实体管理 API、组织结构 API、任务管理 API、订阅者接收订阅资源。

3. 孪生大屏与前端展示开发人员

   • 关注焦点：如何为低代码设计器或三维孪生面板拉取最新的网关和设备实时数据缓存。
   • 相关章节：获取订阅资源 API。

4. AI 智能体与大模型集成开发人员

   • 关注焦点：如何使智能体（如 CherryStudio、Claude Desktop）通过工具调用直接访问或反控数字孪生系统。
   • 相关章节：自定义 MCP 工具说明。

🛠️ DTS 能做到的事情 (核心能力)

• 实体与本体模型管理：通过 REST 接口动态定义产品模型（本体定义），并实现物理/虚拟实体的增、删、改、查与状态同步。
• 高并发双向数据通道：提供标准的遥测上行上报通道和毫秒级响应的设备反控（下行服务调用）通道。
• 数字孪生空间与组织树：支持动态构建孪生体组织树，支持将实体绑定到特定的地理空间节点（如：园区 -> 大楼 -> 楼层 -> 设备），为上层业务提供空间层级感知。
• 自动化任务与时序数据：支持管理平台侧的后台联动规则任务，并提供时序数据库的高性能历史数据查询。
• 协议适配与边界脚本二次开发：网关内置 JavaScript 执行沙箱，支持使用自定义脚本对非标准报文进行转换、就地清洗，并支持在图像上进行空间冲突检测与几何标记渲染。

🎯 API 场景选型决策指南 (何种场景选择什么样的 API)

为了方便开发者快速找到符合业务需求的 API 接口，我们整理了以下常用业务场景的 API 选型指南：

🚀 快速上手

环境准备

若您已部署好 DTS 服务（含私有化部署），或可直接访问公网 DTS 服务，无需额外准备环境，可直接进入后续对接流程。

若未部署相关服务，需先完成大视景数字孪生服务 DTS V2.0 及以上版本的部署：

1. 私有化部署流程：请参考配套文档《大视景数字孪生服务 DTService 安装部署指南》，按指南完成部署配置；
2. 版本咨询：关于 DTS 版本的适配要求、获取方式及部署相关疑问，可联系大视景科技官方对接人员咨询。

部署完成后，请确认 DTS 服务正常启动，可通过访问服务端口或测试接口验证服务可用性，确保环境满足对接要求。

📖 核心对接使用场景架构图

场景一：数据层接入交互 (上行上报与下行控制)

适用场景：第三方应用需将自有实体数据接入 DTS 数据层，实现与 DTS 数字孪生数据的双向交互联动（如实体信息同步、遥测上报与反控）。
基于数据层接入交互，选择 实体接入 API 和 实体服务调用 API 了解更多。

场景二：主动获取数字孪生平台资源 (主动拉取模式)

适用场景：第三方应用需主动查询、获取 DTS 数字孪生平台中的各类资源最新状态（如孪生模型、实体最新遥测值等），按需拉取用于自身业务或大屏组件渲染。
获取数字孪生平台资源（主动模式），选择 获取订阅资源 API 了解更多。

场景三：被动订阅数字孪生平台资源 (实时推送模式)

适用场景：第三方应用无需主动查询，需要实时接收 DTS 数字孪生平台推送的数据变化、遥测更新、告警等信息，实现平台端与业务系统状态的实时同步。
订阅数字孪生平台资源（被动模式），选择 订阅者接收订阅资源 了解更多。