回执参数格式说明

在数字孪生服务 (DTS) 中，服务调用与执行结果的流转遵循指令下发-异步回传-脚本解析的闭环控制逻辑。通用网关在下发服务调用时会携带回执相关参数，服务执行方在处理完毕后，需根据回执参数将结果上报回对应的回调地址（如 DTS 接收端），DTS 通过消息解析脚本识别对应的服务或事件标识符进行处理，从而形成完整的业务闭环。

核心工作流与应用场景

1. 业务流转过程

  1. 服务调用与指令下发：用户或任务系统在 DTS 发起实体服务调用（例如：触发一次 AI 抓拍分析服务 aiAnalysisOnce）。DTS 在向服务执行方发送请求时，会随请求体下发回执参数 _bv_callback_message、回调方式 _bv_callback_method 和回调 URL _bv_callback_url。
  2. 任务处理与结果回调：服务执行方根据入参进行业务处理。处理完成后，识别回执参数中的回调方式和地址：
  3. 如果回调方式是 http 或 redis 等，则将处理结果发送给 _bv_callback_url 中指定的地址（如果要回传给 DTS，该地址即为 DTS 接收地址）。
  4. 关键要求：在回调请求的数据体中，服务执行方必须原样携带下发时的 _bv_callback_message 回执对象。
  5. 数据上报与脚本解析：DTS 网关接收到带有 _bv_callback_message 的回调数据后，利用产品的消息解析脚本进行解析。
  6. 解析识别与闭环：解析脚本通过读取 _bv_callback_message 中携带的服务标识符（如 aiAnalysisOnce）或事件标识符（如 aiEvent），识别出这笔数据属于哪项服务或哪个事件的执行结果，完成报文清洗和模型字段填充，最终形成 DTS 指令发出与结果接收的闭环控制。

回执参数定义

1. 服务下行携带的控制回执字段（顶级字段）

字段名称 字段类型 说明 是否必传
_bv_callback_message Object 回执核心元数据容器（定义见下表） 是
_bv_callback_method String 回调方式，例如 http、redis 是
_bv_callback_url String 回调接收地址（DTS通用网关的数据接收端点） 是

2. _bv_callback_message 结构详情

字段名称 字段类型 说明 是否必传
productId String 产品唯一识别码 是
deviceId String 实体设备唯一标识符 是
identifier String 目标事件唯一标识符（例如回调需要触发事件上报时存在） 否
_bv_service_callback Object 服务调用元数据（服务异步调用时存在，定义见下表） 否

3. _bv_service_callback 结构详情

字段名称 字段类型 说明 是否必传
identifier String 服务的唯一标识符（例如：aiAnalysisOnce） 是
requestId String 用于标记和匹配单次请求的唯一追踪 ID 是
version String 产品模型版本，默认为 default 否
timestamp Number 指令下发的时间戳（毫秒） 否

完整报文示例

以下是服务执行方（如 AI 算法分析服务器）在完成分析任务后，准备向 DTS 回调地址（_bv_callback_url）发送的 POST 请求报文：

{
  "_bv_callback_message": {
    "identifier": "aiEvent",
    "productId": "uhyVXMcYsdrNfucV",
    "deviceId": "D05A4AD9-0B97-0F4C-B6A9-96F84ABC7B3A",
    "_bv_service_callback": {
      "identifier": "aiAnalysisOnce",
      "requestId": "55c6ac78f8234bb18d23ffccfc5c0234",
      "version": "default",
      "timestamp": 1782112805338
    }
  },
  "includeImage": true,
  "image_data": "<base64 image: 165 chars>",
  "_bv_callback_method": "http",
  "analysisTypes": "person_vehicle",
  "_bv_callback_url": "http://192.168.100.38:48083/bv-universal-gateway/api/accessGateway/rawDataToProtocol/uhyVXMcYsdrNfucV/1"
}

消息解析脚本（JavaScript）处理示例

当 DTS 接收到上述回调报文后，会将数据投入消息解析脚本（如 rawDataToProtocol）进行转换。在脚本中，开发者可以通过以下逻辑识别对应的服务与事件进行解析：

/**
 * DTS 消息解析脚本示例 (数据上行解析)
 * @param {string} rawData - 接收到的原始回调 JSON 字符串
 * @returns {string} - 解析清洗后的标准 BV JSON 字符串
 */
function rawDataToProtocol(rawData) {
    var payload = JSON.parse(rawData);
    var callbackMsg = payload._bv_callback_message;

    var result = {};

    // 1. 判断是否存在回执参数
    if (callbackMsg && callbackMsg._bv_service_callback) {
        var serviceId = callbackMsg._bv_service_callback.identifier; // 获取发起调用的服务标识符: "aiAnalysisOnce"
        var eventId = callbackMsg.identifier;                       // 获取目标事件标识符: "aiEvent"

        // 2. 根据服务标识符进行针对性的解析闭环
        if (serviceId === "aiAnalysisOnce") {
            result.productId = callbackMsg.productId;
            result.deviceId = callbackMsg.deviceId;
            result.method = 1;                     // 1 表示事件上报 (上报 AI 识别事件)
            result.identifier = eventId || "aiEvent";

            // 3. 将原始业务数据解析并组装到 payload 字段下
            result.payload = {
                analysisTypes: payload.analysisTypes,
                hasPersonOrVehicle: true,          // 业务逻辑判断
                snapshotImage: payload.image_data  // AI 人脸车牌图片数据
            };
        }
    }

    return JSON.stringify(result);
}
作者：北京-产品-yantings  创建时间：2025-12-29 15:41
最后编辑：北京-产品-yantings  更新时间：2026-07-07 18:14
上一篇：
下一篇：