实体接入是将虚拟或物理实体无缝集成至DTS，实现对实体的管控。无论是物联网设备（如传感器、智能终端）还是虚拟实体（如软件模拟器），均可通过HTTP协议或定制快速接入，完成数据通信、状态监测及远程控制。实体接入是跨数字世界和物理世界将流式处理数据链接到一起，为构建数字孪生世界提供实时数据来源。

**准备事项

1.注册数字孪生服务DTService（以下简称DTS）账户
2.准备APIfox，用于模拟设备（或其他可以发送Http请求的软件，如postman、vs等）
3.了解 BV JSON数据格式
3.了解HTTP协议接入：BV JSON数据格式、HTTP协议接入：透传/自定义数据格式

示例

创建产品

1. 进入实体管理模块，选择产品。
2. 创建一个名为温湿度传感器的产品，选择所属品类为“自定义品类”接入网关协议选择为HTTP协议，数据格式为BV JSON 。
   • 自定义品类：选择自定义产品，本示例将完全自定义产品 Profile。
   • 接入网关协议：选择通过何种协议方式将数据传输到 DTS 中（本示例使用 HTTP协议）。
   • 数据格式：选择传输到 DTS 中的数据格式（本示例使用平台标准的 BV JSON）。
3. 根据需要设定产品的坐标系和产品描述；
4. 点击“立即创建”，完成产品的创建。

[!NOTE]
关于品类（标准/自定义）、接入协议（HTTP/定制）以及数据格式（BV JSON/透传）的详细概念定义，请参考概念定义 - 实体管理。

定义产品Profile

1. 在产品列表中，选择“温湿度传感器”产品，点击编辑进入产品信息详情页面->选择产品Profile Tab页面。
2. 点击编辑草稿，根据温湿度传感器能提供的属性、事件、服务信息进行产品Profile的定义。
3. 完成后点击退出编辑。
4. 在产品Profile所有编辑完成后，需点击发布。发布后的产品Profile才能被网关识别。

   下载示例温湿度传感器产品Profile，修改后缀名为“.json”后导入到产品Profile中，可快速完成产品Profile定义。
   事件定义时，勾选持久化存储，接收到的事件将会存储到DTS数据库中。不勾选，暂存在服务器内存中会定时清除。
   注意：事件没有订阅者时，DTS不会存储缓存。

编写消息解析脚本（透传/自定义格式）

消息解析脚本是将设备上报数据，转换为BV JSON数据格式；将下发的BV JSON格式数据，转换为设备支持的格式。在实体接入过程中，只有数据格式为透传/自定义数据的产品需要编写实体映射（上行）脚本，数据格式为BV JSON 的产品可跳过此步骤。

1. 在产品列表中，选择“温湿度传感器”产品，点击编辑进入产品信息详情页面->选择消息解析 Tab页面。
2. 在实体映射（上行）脚本中，写入将设备产生的数据转化为DTS 可识别的BV JSON数据。
3. 脚本编写完成后，可通过模拟输入检查脚本是否正确，格式转换是否成功，能否正确进行赋值。

调试技巧：使用console.log()将内容输出到日志查看区。运行测试，查看控制台输出；

消息解析脚本示例

/**
 * 将透传/自定义数据格式转换为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;
    }

}

模拟输入示例（设备上报）

{
        "guid": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "name": "温湿度传感器1751939165",
        "status": 1,
        "humidity": 34.54,
        "temperature": 9.38,
        "batteryLevel": 81
    }

运行结果示例

{
    "code": 0,
    "message": "success",
    "info": {
        "productId": "Re8agKekkXw8Oczi",
        "payload": {
            "temperature": 9.38,
            "humidity": 34.54,
            "batteryLevel": 81
        },
        "deviceId": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "deviceName": "温湿度传感器1751939165",
        "deviceStatus": 1
    }
}

模拟输入示例（属性上报）

{
       "guid": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "status": 1,
        "humidity": 44.97,
        "temperature": 19.05,
        "batteryLevel": 62
}

运行结果示例

{
    "code": 0,
    "message": "success",
    "info": {
        "payload": {
            "temperature": 19.05,
            "humidity": 44.97,
            "batteryLevel": 62
        },
        "deviceId": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "deviceStatus": 1
    }
}

模拟输入示例（低温事件上报）

{
    "deviceType": "SmartRefrigerator",
    "guid": "970bdf41-7818-4718-b00e-eb14a08b6372",
    "notificationType": "lowTemperatureAlarm",
    "content": {
        "temperature":-1.41
    },
    "timestamp":1751943449804
}

运行结果示例

{
    "code": 0,
    "message": "success",
    "info": {
        "identifier": "lowTemperatureAlarm",
        "payload": {
            "temperature": -1.41
        },
        "deviceId": "970bdf41-7818-4718-b00e-eb14a08b6372",
        "timestamp": 1751943449804
    }
}