一、描述

物模型服务的行为调用是指应用程序或云平台通过物模型通讯协议向物联网设备发送指令或请求执行某些操作。例如清洁计划设置等。

二、数据交互图

异步调用

同步调用

3.1 通讯方式

3.2 Topic定义

3.3 method 枚举

四、场景示例

示例以扫地机为例，行为为扫地机的清洁行为，定义事件名为clean，输入属性名为 type , 值有 sweeping、mopping, 输出属性名为finishTime，值为时间戳类型。

4.1 异步调用流程

1.发送行为调用

应用程序可以通过调用 触发调用设备行为 接口进行单个设备的指定行为触发。
或者通过MQTT消息进行请求触发,发送消息到topic: /${productId}/${deviceId}/thing/action/request ，发送的JSON格式如下：

{
  "method":"invoke",
  "messageId":"157889065985",
  "actionIdentifier":"clean",
  "module":"default",
  "retained":false,
  "input":{
      "type":"sweeping"
  }
}

字段说明：

2.校验TSL

物模型服务在接收到调用之后，进行对行为的输入参数进行TSL校验。

3.下发行为调用指令

物模型服务在接收到 行为调用 信息之后，下发消息到Topic：/${productId}/${deviceId}/thing/action/invoke ，发送的JSON格式如下：

{
  "method":"invoke",
  "messageId":"157889065985",
  "actionIdentifier":"clean",
  "module":"default",
  "input":{
      "type":"sweeping"
  }
}

字段说明：

4.返回行为调用结果

HTTP触发行为调用：若对应行为的调用方法定义为 异步 时，在下发调用指令后服务端将不等待设备返回行为调用结果，直接响应接口请求。
MQTT触发行为调用：无论行为调用方法定义是异步还是同步，都会回复一条触发调用的结果到 /${productId}/${deviceId}/thing/action/request/reply中，发送的JSON格式如下：
1）成功返回示例：

{
    "messageId":"157889065984",
    "method":"invoke",
    "code":0
}

2）若调用失败，发送到该Topic的消息为：

{
    "messageId":"157889065984",
    "method":"invoke",
    "code": ${errorcode},
    "msg": "${errormessage}"
}

字段说明：

5.校验行为调用并执行逻辑

设备在接收到行为调用消息之后，进行TSL校验，通过之后按照行为调用指令进行逻辑执行。

6.返回行为调用结果

设备在执行行为调用逻辑完成之后，发送结果到 /${productId}/${deviceId}/thing/action/invoke/reply Topic中，发送的JSON格式如下：

1）成功返回示例：

{
  "method":"invoke",
  "messageId":"157889065985",
  "code":0,
  "output":{
      "finishTime":1686313154595
  }
}

2）失败返回示例：

{
  "method":"invoke",
  "messageId":"157889065985",
  "code":${errorCode},
  "msg":"${errorMessage}"
}

字段说明：

7.保存行为调用记录

设备返回行为调用结果后，物模型服务保存当前行为的调用记录。

4.2 同步调用流程

1.发送行为调用

应用程序通过调用 触发调用设备行为 接口进行单个设备的指定行为触发。

2.校验TSL

物模型服务在接收到调用之后，进行对行为的输入参数进行TSL校验。

3.下发行为调用指令

物模型服务在接收到 行为调用 信息之后，下发消息到Topic：/${productId}/${deviceId}/thing/action/invoke ，发送的JSON格式如下：

{
  "method":"invoke",
  "messageId":"157889065985",
  "actionIdentifier":"clean",
  "module":"default",
  "input":{
      "type":"sweeping"
  }
}

字段说明：

4.校验行为调用并执行逻辑

设备在接收到行为调用消息之后，进行TSL校验，通过之后按照行为调用指令进行逻辑执行。

5.设备返回行为调用结果

设备在执行行为调用逻辑完成之后，发送结果到 /${productId}/${deviceId}/thing/action/invoke/reply Topic中，发送的JSON格式如下：

1）成功返回示例：

{
  "method":"invoke",
  "messageId":"157889065985",
  "code":0,
  "output":{
      "finishTime":1686313154595
  }
}

2）失败返回示例：

{
  "method":"invoke",
  "messageId":"157889065985",
  "code":${errorCode},
  "msg":"${errorMessage}"
}

无需在output中重复定义 errorCode 和 errorMessage 等类似含义的输出字段

字段说明：

6.保存行为调用记录

设备返回行为调用结果后，物模型服务保存当前行为的调用记录。

7. 物模型服务返回行为调用结果

若对应行为的调用方法定义为 同步 时，在下发调用指令后服务端将等待设备返回行为调用结果后，再响应HTTP接口请求。

重要： 如5秒钟未收到设备的行为调用结果，该行为调用结果为超时

五、错误码