示例

本文以温湿度传感器产品为例，介绍使用 HTTP 协议服务，通过 DTS 进行实体反控的配置与调试流程。

[!IMPORTANT] 生产架构与调试说明 * 在生产环境/实际使用时：DTS 网关中配置的服务地址（URL）应当指向您真实的物理设备、本地边缘网关，或者是您企业内部的实体控制系统服务接口。 * 在本文教程中：为了方便您在没有真实物理硬件的情况下能闭环体验并测试 DTS 的反控配置链路，我们采用 Postman 或 APIFox 搭建本地 Mock 服务来模拟设备端接收控制指令。这仅作为本地联调和报文格式检查的手段，实际生产开发时请替换为您的真实设备接口。

生产环境与调试环境配置对照：

配置项 / 概念	本文调试阶段（以 Postman 为例）	实际生产阶段（以智能插座重启为例）
反控服务承载者	Postman Mock Server (或 APIFox Mock)	物理设备本身（如设备内置 WebServer）或本地边缘网关 / 控制服务
网关服务地址 (URL)	`https://xxxx.mock.pstmn.io/reset` (Mock 服务提供的公网域名/接口)	`http://192.168.1.100:8080/api/reset` (物理设备在局域网/专网的真实IP与接口)
数据通信方向	DTS 平台 $\rightarrow$ 互联网 $\rightarrow$ Postman 云 Mock 接口	DTS 平台 $\rightarrow$ 局域网/专网 $\rightarrow$ 真实物理设备接口

反控配置流程包含以下几个主要步骤：

1. 准备反控接收服务端：生产环境中为您的物理设备或网关反控接口，本文调试时使用 Postman/APIFox 模拟；
1. 网关添加服务地址：在通用网关的服务列表中添加上述反控服务地址；
1. 定义产品Profile：在产品中定义支持的服务（如重启复位服务）；
1. 创建任务：创建自动化任务以触发并执行服务调用动作；
1. 结果验证：手动或自动执行任务，验证反控结果。

null

准备事项

1.注册数字孪生服务DTService（以下简称DTS）账户 2.准备Postman或APIFox，用于模拟接收设备反向控制的指令。 3.已成功创建需要进行反控的产品”温湿度传感器“。请参考实体接入 4.已成功创建需要进行反控的设备。

构建模拟服务端（调试步骤，若已有真实设备接口可跳过）

已有可调用的服务端，可忽略此步骤。使用Postman模拟可以查看到DTS请求服务时，发送的数据内容。如不需要查看，可以使用APIFox模拟。

Postman模拟服务端

使用Postman模拟一个接收实体反向控制的服务端“重启复位服务”。模拟接收某个实体发送的重启复位指令。
在右侧菜单栏中选择“Collections”，点击新建一个集合，命名为“模拟服务端”。
在“模拟服务端”集合下，新建一个Post方式的HTTP接口，命名为“重启复位服务”。
定义接口地址为“/reset”，请求参数有deviceid ,返回内容为code message info 。
定义完成后，保存接口。
在右侧菜单栏中选择“Mock servers”，新建一个Mock server，命名为“MyMockServer”，选择“模拟服务端”集合作为MockServer下的集合。
新建完成后，点击“Copy URL”，复制Mock server的地址。
将复制的mockserver地址，补充到接口“重启复位服务”中，作为接口的请求地址。示例如，“https://3cb98ad9-2243-4c27-b0c1-c5bb0f8af23f.mock.pstmn.io/reset”。
在右侧侧边栏中选择“智能插座”，点击“更多”添加一个示例，命名为“reset”。
回到“Mock servers”下，进入“MyMockServer”，等待DTS的服务请求。

APIfox模拟服务端

使用APIfox模拟一个接收实体反向控制的服务端“重启复位服务”。模拟接收某个实体发送的重启复位指令。

点击新建一个接口，命名为“重启复位服务”。
定义接口地址为“/reset”，请求参数有deviceid ,返回参数为code message info。
将接口采用“本地Mock环境”或“云Mock环境”启动，保证能被DTS所访问。
查找到接口的Mock地址，复制已备用。

示例采用本地Mock环境，实际使用时，将需修改为具体的IP地址。保证目标地址与DTS之间网络通信正常。

null

网关添加服务地址

进入实体管理模块，选择网关。
选择“通用网关”，点击编辑进入通用网关的详情页面->选择服务列表 Tab页面。
在服务列表 Tab页面下，选择添加一个服务地址。
命名为“本地Postman服务”，选择类型为Http方式，服务地址输入已通过Postman创建好的服务“MyMockServer”的Mock地址。若使用APIfox方法一致，输入APIFox提供的Mock地址即可。

这个服务地址需指向接收控制服务请求的目标地址。

null

定义产品Profile

需在产品Profile中定义实体支持的服务。服务执行后，根据使用场景选择结果返回方式：

支持通过属性上报或事件上报的方式，将执行结果反馈到DTS中。采用此方式，需定义对应的属性或事件。
支持通过HTTP或RedisMQ的方式，将执行结果转发给第三方平台；

在产品Profile所有编辑完成后，需点击发布。发布后的产品Profile才能被DTS识别。智能插座的数据格式为“BV JSON”，示例默认都使用BV JSON进行数据交互。无论数据格式是BV JSON或透传/自定义流程类似，BV JSON无需写消息解析脚本。

定义产品Profile（服务）

进入实体管理模块，选择产品。
选择“温湿度传感器”产品，点击编辑进入产品的详情页面->选择产品Profile Tab页面。
点击编辑草稿，选择添加功能，选择功能类型为服务。
输入功能名称为”重启复位“，设置标识符为resetDevice。
服务地址选择已定义的服务地址”本地Postman服务“，输入地址接收请求的接口地址“/reset”。
根据“重启复位服务”服务设置输入参数deviceid 。
根据需要设定选择结果返回方式为属性上报or事件上报。

图1：采用属性上报返回结果

图2：采用事件上报返回结果

同步方式为立即返回结果，异步方式可有延迟。DTS会携带回调参数发送到服务。

方式1：结果返回方式为属性

定义产品Profile（属性）

进入实体管理模块，选择产品。
选择“智能插座”产品，点击编辑进入产品的详情页面->选择产品Profile Tab页面。
点击编辑草稿，选择添加功能，选择功能类型为属性。
输入功能名称为”重启状态“，设置标识符为status。
确定保存属性。

方式2：结果返回方式为事件

定义产品Profile（事件）

进入实体管理模块，选择产品。
选择“智能插座”产品，点击编辑进入产品的详情页面->选择产品Profile Tab页面。
点击编辑草稿，选择添加功能，选择功能类型为事件。
输入功能名称为”获取重启状态“，设置标识符为getResult。
设置输出参数 status 。
确定保存事件。

配置消息解析脚本

仅需为使用透传/自定义协议的产品实体配置。

消息解析脚本示例

/**
 * 将透传/自定义数据格式转换为DTS平台的BV JSON数据格式，实体注册、属性、事件上报到DTS时调用。
 * @param {JSONObject} body - 入参
 * @param {JSONObject} body._bv_callback_message - 服务回调参数（回调时携带）
 * @param {string} body._bv_callback_message.productId - 产品编号
 * @param {string} body._bv_callback_message.deviceId - 实体编号
 * @param {string} body._bv_callback_message.identifier - 事件的唯一标识符（回调方式为事件上报时携带）
 * @param {JSONObject} body._bv_callback_message._bv_service_callback - 服务调用参数
 * @param {string} body._bv_callback_message._bv_service_callback.requestId - 用于标记请求
 * @param {string} body._bv_callback_message._bv_service_callback.identifier - 服务唯一标识符
 * @param {string} body._bv_callback_message._bv_service_callback.version - 消息格式版本
 * @param {number} body._bv_callback_message._bv_service_callback.timestamp - 服务调用时间
 * @param {number} flag - 入参类型标识，0=实体注册，1=属性上报，2=事件上报
 * @returns {JSONObject} 出参，BV JSON数据格式，不能为空
 */
function rawDataToProtocol(body, flag) {
    var inputData = body;
    var jsonObj = {};
    if (flag === 0) {
        /**
         * @returns {string} return.deviceId - 实体编号，需保证全局唯一性，必传
         * @returns {string} return.deviceName - 实体名称（最大长度255），必传
         * @returns {number} return.deviceStatus - 实体状态， 0=禁用，1=启用（默认），非必传
         * @returns {number} return.deviceType - 实体类型，0=动态资源，1=静态资源，必传
         * @returns {string} return.location - 实体位置（默认0 0 0），格式：纬度 经度 高程，非必传
         * @returns {string} return.version - 版本号（默认default），非必传
         * @returns {JSONObject} return.payload - 扩展数据，用于更新实体属性值，数据基于产品 Profile 定义的属性过滤（已定义属性对应的数据保留，未定义属性对应的数据弃用），非必传
         */
        jsonObj['deviceId'] = inputData.guid;
        jsonObj['deviceName'] = inputData.name;
          jsonObj['deviceStatus'] = inputData.status;
          jsonObj['payload'] = inputData;
        return jsonObj;
    }
    if (flag === 1) {
        /**
         * @returns {string} return.deviceId - 实体编号，需保证全局唯一性，必传
         * @returns {string} return.deviceSecret - 实体签名（不传时将系统匹配），非必传
         * @returns {string} return.deviceName - 实体名称（最大长度255），非必传
         * @returns {number} return.deviceStatus - 实体状态， 0=禁用，1=启用（默认），非必传
         * @returns {string} return.location - 实体位置（默认0 0 0），格式：纬度 经度 高程，非必传
         * @returns {number} return.timestamp - 上行数据传输时间戳。格式为数值，值为从UTC 1970-01-01 00:00:00开始到当前时刻的毫秒数，非必传
         * @returns {string} return.version - 版本号（默认default），非必传
         * @returns {JSONObject} return.payload - 扩展数据，用于更新实体属性值，数据基于产品 Profile 定义的属性过滤（已定义属性对应的数据保留，未定义属性对应的数据弃用），非必传
         */

        jsonObj['deviceId'] = inputData.guid;
        jsonObj['deviceStatus'] = inputData.status;
        jsonObj['payload'] = inputData;
        return jsonObj;
    }
    if (flag === 2) {
        /**
         * @returns {string} return.deviceId - 实体编号，需保证全局唯一性，必传
         * @returns {string} return.deviceSecret - 实体签名（不传时将系统匹配），非必传
         * @returns {string} return.deviceName - 实体名称（最大长度255），非必传
         * @returns {number} return.deviceStatus - 实体状态， 0=禁用，1=启用（默认），非必传
         * @returns {string} return.location - 实体位置（默认0 0 0），格式：纬度 经度 高程，非必传
         * @returns {string} return.identifier - 事件的唯一标识符，必传
         * @returns {number} return.timestamp - 上行数据传输时间戳。格式为数值，值为从UTC 1970-01-01 00:00:00开始到当前时刻的毫秒数，非必传
         * @returns {string} return.version - 版本号（默认default），非必传
         * @returns {JSONObject} return.payload - 扩展数据，事件的输出参数，数据基于产品 Profile 定义的事件输出参数过滤（已定义输出参数对应的数据保留，未定义输出参数对应的数据弃用），非必传
         */
        jsonObj['deviceId'] = inputData.guid;
          jsonObj['identifier'] = inputData.notificationType;
        jsonObj['payload'] = inputData.content;
          jsonObj['timestamp'] = inputData.timestamp;
        return jsonObj;
    }

}

创建任务

在任务管理页面，创建一个任务名为“温湿度定时重启“的场景。

任务逻辑

每个工作日晚上18点触发执行任务重启复位服务

创建完成后，进入编辑页面。根据任务逻辑编辑对应的规则。设定触发条件为每个工作日18点，添加执行任务类型为”服务调用“，选择温度传感器产品下的某一实体或全部实体，执行服务”重启复位服务”。

null

设置服务调用的参数

设置服务调用的参数，deviceid使用插入变量的方式，设置其值为温湿度传感器下的当前实体（执行此任务的实体）。

null

保存任务，启动任务。手动执行任务，进行任务的检查。
前往任务-执行日志，查看任务的执行情况。

Postman查看请求

在Postman中查看是否接收到来自DTS的请求。 _bv_callback_message发送的回执参数。从中可获取到结果返回的方式 _bv_callback_method以及结果返回地址 _bv_callback_url。以及执行服务所需的输入参数。详细参数解释可查看回执参数。

结果返回方式为属性上报

图1：BV JSON数据格式

图2：透传/自定义数据格式

结果返回方式为事件上报

图1：BV JSON数据格式

图2：透传/自定义数据格式

若服务端并未收到来自DTS的服务请求，请检查服务定义以及目标服务与DTS之间的网络是否通畅。

APIFox模拟设备端上报

根据HTTP协议的HTTP协议实体接入(BV JSON数据格式)-属性上报接口、HTTP协议实体接入(BV JSON数据格式)-事件上报接口，在APIFox中编写返回结果。
接口地址填写_bv_callback_url的值，请求体中productId identifier deviceId均来自_bv_callback_message。
接口准备完毕，点击发送。

属性上报发送请求体示例

{
    "method": 0,
    "productId": "MNGRcylFFmLxxvJh",
    "deviceId": "407ddc2c-1860-4afe-a26a-cfb06228016c",
    "deviceStatus": 0,
    "payload": {
        "status": true
    }
}

事件上报发送请求体示例

{
    "method": 1,
    "productId": "MNGRcylFFmLxxvJh",
    "deviceId": "407ddc2c-1860-4afe-a26a-cfb06228016c",
    "identifier": "getResult",
    "deviceStatus": 0,
    "payload": {
        "status": true
    }
}

若数据格式为透传/自定义，则需根据HTTP协议实体接入(透传/自定义)-属性上报接口、HTTP协议实体接入(透传/自定义)-事件上报接口，在APIFox中编写返回结果。

返回服务结果时，尽量携带回执参数。在透传/自定义数据格式下，可根据回执参数进行特殊的处理逻辑。

属性上报发送请求体示例

{
        "guid": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "status": 0,
        "resetStatus": true,
        "_bv_callback_message": {
                "_bv_service_callback": {
                        "identifier": "resetDevice",
                        "requestId": "0d6b56b5fafd4510bf1c4339a137e91c",
                        "version": "default",
                        "timestamp": 1752051738967
                },
                "productId": "Re8agKekkXw8Oczi",
                "deviceId": "970bdf41-7818-4718-b00e-eb14a08b6372"
        }
}

事件上报发送请求体示例

{
    "deviceType": "SmartRefrigerator",
    "guid": "970bdf41-7818-4718-b00e-eb14a08b6372",
    "notificationType": "getResult",
    "content": {
        "status": true
    },
    "timestamp": 1752053423202,
    "_bv_callback_message": {
        "identifier": "getResult",
        "_bv_service_callback": {
            "identifier": "resetDevice",
            "requestId": "662f7c9a02084672ad02d3e650776cca",
            "version": "default",
            "timestamp": 1752053377098
        },
        "productId": "Re8agKekkXw8Oczi",
        "deviceId": "970bdf41-7818-4718-b00e-eb14a08b6372"
    }
}

结果验证

属性上报的结果可以在实体状态中直接查看，也可以经过订阅管理将向DTS订阅实体的属性变化和事件发生的数据，订阅端收到数据之后进行可视化处理便能对设备进行实时数据监控。DTS数据孪生架构提供快速接入查看DTS设备数据的平台功能低代码设计器（无需订阅），详细可视化功能可查看《BigView低代码设计器教程》

作者：北京-产品-yantings 创建时间：2025-02-28 14:32
最后编辑：北京-产品-yantings 更新时间：2026-07-16 17:09

上一篇：实体反控
下一篇：基于WebSocket方式进行实体反控

基于HTTP方式进行实体反控

示例

生产环境与调试环境配置对照：

准备事项

构建模拟服务端（调试步骤，若已有真实设备接口可跳过）

Postman模拟服务端

APIfox模拟服务端

网关添加服务地址

定义产品Profile

定义产品Profile（服务）

方式1：结果返回方式为属性

定义产品Profile（属性）

方式2：结果返回方式为事件

定义产品Profile（事件）

配置消息解析脚本

创建任务

设置服务调用的参数

Postman查看请求

APIFox模拟设备端上报

结果验证