华为云用户手册

示例 节点告警 { "alarmName": "测试##test", "alarmId": "73ccbccce05de74f9d3dda42f6ecfe20", "detailedInformation": "测试##test", "url": "", "source": "IEF", "cleared": false, "policyID": "", "perceivedSeverity": 4, "resourceId": { "namespace": "PAAS.NODE", "dimension": { "clusterId": "e277befa37a64ed1aa25b522e686bc28", "nameSpace": "default", "nodeIP": "192.168.0.164" } }, "neType": "Host", "eventType": 23 } 应用告警 { "alarmName": "应用重启test##Application restart", "alarmId": "b09076ff565c59d4da0db0c9223781", "detailedInformation": "应用重启 test##Application restart test", "url": "", "source": "IEF", "cleared": false, "policyID": "", "perceivedSeverity": 3, "resourceId": { "namespace": "PAAS.CONTAINER", "dimension": { "containerName": "container-e991acd3-864c-4038-8a90-e042eebab496", "containerID": "70b385315c8ac507b3de7dfe1258932cea0b53a850b7d030ce7ed0a55c47877c", "podID": "0e9ce4fd-b732-11e9-8a30-fa163e9b3546", "podName": "hxkapp1-7898f5bd4b-2lj8z" } }, "neType": "Application", "eventType": 23 }

Topic $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 参数 类型 说明 project_id String 项目ID。获取方式请参见获取项目ID。 encryptdata_name String 加密数据集名称。 properties_name String 加密数据的“键名”。

Topic $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 参数 类型 说明 project_id String 项目ID。获取方式请参见获取项目ID。 encryptdata_name String 加密数据集名称。 properties_name String 加密数据的“键名”。

Topic $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 参数 类型 说明 project_id String 项目ID。获取方式请参见获取项目ID。 encryptdata_name String 加密数据集名称。 properties_name String 加密数据的“键名”。

Topic $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 参数 类型 说明 project_id String 项目ID。获取方式请参见获取项目ID。 encryptdata_name String 加密数据集名称。 properties_name String 加密数据的“键名”。

加密数据的使用 加密数据绑定到边缘节点后，在边缘节点上使用MQTT客户端就可以获取到加密数据。 请求时必须使用证书进行安全认证，认证方法请参见使用证书进行安全认证。 订阅获取加密数据。 Topic：$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 发布请求加密数据。 Topic：$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 请求发布后，1中就能收到解密后的明文数据。

加密数据的使用 加密数据绑定到边缘节点后，在边缘节点上使用MQTT客户端就可以获取到加密数据。 请求时必须使用证书进行安全认证，认证方法请参见使用证书进行安全认证。 订阅获取加密数据。 Topic：$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 发布请求加密数据。 Topic：$hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 请求发布后，1中就能收到解密后的明文数据。

参数说明 IEF转发自定义Topic内容是透传，可以转发任意内容。 “{custom_topic}”支持通配符“#”和“+”，可以将多条符合通配规则的消息进行统一转发。 “#”是一个匹配主题中任意层次数的通配符，多层通配符可以表示大于等于0的层次。“+”是单层通配符，只匹配主题的一层。 对于符合通配规则的Topic消息进行最小范围匹配后进行路由消息转发。如消息Topic为123/aaa/567和123/bbb/567，可以配置通配转发规则123/+/567进行统一转发。

参数说明 IEF转发自定义Topic内容是透传，可以转发任意内容。 “{custom_topic}”支持通配符“#”和“+”，可以将多条符合通配规则的消息进行统一转发。 “#”是一个匹配主题中任意层次数的通配符，多层通配符可以表示大于等于0的层次。“+”是单层通配符，只匹配主题的一层。 对于符合通配规则的Topic消息进行最小范围匹配后进行路由消息转发。如消息Topic为123/aaa/567和123/bbb/567，可以配置通配转发规则123/+/567进行统一转发。

获取设备孪生 向设备孪生获取发送请求获取设备孪生。 Topic：$hw/events/device/{device_id}/twin/get Payload：{"event_id":"自定义id"} 向设备孪生获取结果订阅设备孪生的返回结果。 Topic：$hw/events/device/{dvice_id}/twin/get/result 获取的结果如下： { "event_id": "", "timestamp": 1554988425592, "twin": { "humidity": { "expected": { "value": "0", "metadata": { "timestamp": 1554988419529 } }, "optional": true, "metadata": { "type": "int" } }, "temperature": { "expected": { "value": "0", "metadata": { "timestamp": 1554988419529 } }, "optional": true, "metadata": { "type": "int" } } } }

获取节点关联的终端设备成员 向设备成员获取发送获取终端设备成员消息的请求。 Topic：$hw/events/node/{node_id}/membership/get Payload：{"event_id":"自定义ID"} 示例如下： $hw/events/node/{node_id}/membership/get {"event_id":""} 向设备成员获取结果订阅终端设备成员的返回结果。 Topic：$hw/events/node/{node_id}/membership/get/result 返回结果示例如下： { "event_id": "", "timestamp": 1554986455386, "devices": [ { "id": "2144773f-13f1-43f5-af07-51991d4fd064", "name": "equipmentA", "state": "unknown", "attributes": { "name": { "value": "a", "optional": true, "metadata": { "type": "string" } } } } ] }

监听设备孪生事件 通过获取节点关联的终端设备成员和获取设备孪生以后，即可获取到节点绑定的终端设备ID，随后即可监听该终端设备的事件。 在云端更新设备孪生属性，设置期望值从而达到控制边侧终端设备的目的。 例如某个设备有两个孪生属性，humidity和temperature。 图1 孪生属性 在“设备孪生”页签中编辑孪生属性，将humidity由9改为10。属性修改完成以后，在端侧可收到两个事件：“设备孪生变更事件”和“设备孪生delta事件”。 设备孪生变更事件：包含变更前和变更后的设备孪生信息详情。 设备孪生delta事件：包含设备孪生的详情信息以及设备孪生属性期望值与实际值不一致的delta部分。 订阅这两个Topic，就可以收到变更设备孪生的消息。 订阅设备孪生变更。 Topic：$hw/events/device/{device_id}/twin/update/document 在边侧收到变更消息如下： { "event_id": "0f921313-4074-46a2-96f6-aac610721059", "timestamp": 1555313685831, "twin": { "humidity": { "last": { "expected": { "value": "9", "metadata": { "timestamp": 1555313665978 } }, "optional": true, "metadata": { "type": "int" } }, "current": { "expected": { "value": "10", "metadata": { "timestamp": 1555313685831 } }, "optional": true, "metadata": { "type": "int" } } }, "temperature": { "last": { "expected": { "value": "0", "metadata": { "timestamp": 1555313665978 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } }, "current": { "expected": { "value": "0", "metadata": { "timestamp": 1555313685831 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } } } } } 订阅设备孪生delta。 Topic：$hw/events/device/{device_id}/twin/update/delta 在边侧收到变更消息如下： { "event_id": "60fb5baf-d4ad-47b0-a21e-8b57b52d0978", "timestamp": 1555313685837, "twin": { "humidity": { "expected": { "value": "10", "metadata": { "timestamp": 1555313685831 } }, "optional": true, "metadata": { "type": "int" } }, "temperature": { "expected": { "value": "0", "metadata": { "timestamp": 1555313685831 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } } }, "delta": { "humidity": "10", "temperature": "0" } }

上报设备属性实际值 发布终端设备孪生更新事件。 Topic：$hw/events/device/{device_id}/twin/update Payload：{"event_id":"", "timestamp":0, "twin":{"属性":{"actual":{"value":"设备实际值"}}}} 示例如下： { "event_id": "", "timestamp": 0, "twin": { "temperature": { "actual": { "value": "2" } } } } 发布后，在云端可以观察到设备孪生的实际值发生了相应的变化，如图2所示。 图2 孪生属性值发生变化 在边缘侧订阅设备孪生更新结果，能收到设备孪生更新事件的结果。 Topic：$hw/events/device/{device_id}/twin/update/result 更新的结果如下所示。 { "event_id": "", "timestamp": 1554992093859, "twin": { "temperature": { "actual": { "value": "2", "metadata": { "timestamp": 1554992093859 } }, "optional": true, "metadata": { "type": "int" } } } }

MQTT broker 终端设备可以通过MQTT协议与IEF云端进行通信，您也可以通过发送/订阅消息控制终端设备。 边缘节点上有一个内置MQTT broker，内置MQTT broker使用8883端口与终端设备通信，与内置MQTT broker通信需要经过安全认证，具体请参见使用证书进行安全认证。 另外，边缘节点还支持与外置MQTT broker通信，即在边缘节点上安装一个MQTT broker（如开源的Mosquitto，默认使用1883端口通信）。 如使用外置MQTT broker，请注意需要保证外置MQTT broker通信的端口能正常使用。

MQTT Topic 终端设备与边缘节点、IEF的通信都是通过给MQTT broker中转消息实现的，在MQTT broker中，默认提供如表1所示的Topic（消息主题），上报状态、控制终端设备状态都是通过发送/订阅消息实现的。 应用程序编写完后，可以通过应用部署功能，将应用从IEF中部署到边缘节点，详情请参见容器应用管理。 表1 IEF提供的默认Topic 名称 使用类型 Topic 说明 设备孪生变更 订阅 $hw/events/device/{device_id}/twin/update/document 设备孪生更新文档，当孪生变化时，反映孪生变化前、变化后的区别。 设备孪生delta 订阅 $hw/events/device/{device_id}/twin/update/delta 设备孪生delta事件，当孪生变化时，反映期望值与真实值不一致的孪生信息。 设备成员变更 订阅 $hw/events/node/{node_id}/membership/updated 绑定终端设备关系变化。 设备属性变更 订阅 $hw/events/device/{device_id}/updated 终端设备属性更新。 设备成员获取 发布 $hw/events/node/{node_id}/membership/get 绑定终端设备关系获取。 设备成员获取结果 订阅 $hw/events/node/{node_id}/membership/get/result 绑定终端设备关系获取结果。 设备孪生获取 发布 $hw/events/device/{device_id}/twin/get 设备孪生获取。 设备孪生获取结果 订阅 $hw/events/device/{device_id}/twin/get/result 设备孪生获取结果。 设备孪生更新 发布 $hw/events/device/{device_id}/twin/update 设备孪生更新。 设备孪生更新结果 订阅 $hw/events/device/{device_id}/twin/update/result 设备孪生更新结果。 请求加密数据 发布 $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 发布获取加密数据请求。 获取加密数据 订阅 $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 订阅获取加密数据。 添加告警 发布 $hw/alarm/{appname}/add 向 AOM 发送告警。 清除告警 发布 $hw/alarm/{appname}/clear 清除AOM中告警。 自定义Topic 发布 {project_id}/nodes/{node_id}/user/{custom_topic} 自定义Topic，Topic根据您的需要自行定义。 您可以将终端设备数据发送到边缘节点MQTT broker的自定义Topic中，IEF会将这些数据转发到DIS通道或APIG后端地址。数据转发到DIS通道或者APIG后端地址后，您可以提取这些数据，并对数据进行处理分析。 接下来将介绍如何在边缘侧获取终端设备信息，接收云上的控制消息，以及如何将终端设备数据上报到云端。MQTT收发消息的示例代码请参见Go语言代码样例和Java语言代码样例。

监听设备孪生事件 通过获取节点关联的终端设备成员和获取设备孪生以后，即可获取到节点绑定的终端设备ID，随后即可监听该终端设备的事件。 在云端更新设备孪生属性，设置期望值从而达到控制边侧终端设备的目的。 例如某个设备有两个孪生属性，humidity和temperature。 图1 孪生属性 在“设备孪生”页签中编辑孪生属性，将humidity由9改为10。属性修改完成以后，在端侧可收到两个事件：“设备孪生变更事件”和“设备孪生delta事件”。 设备孪生变更事件：包含变更前和变更后的设备孪生信息详情。 设备孪生delta事件：包含设备孪生的详情信息以及设备孪生属性期望值与实际值不一致的delta部分。 订阅这两个Topic，就可以收到变更设备孪生的消息。 订阅设备孪生变更。 Topic：$hw/events/device/{device_id}/twin/update/document 在边侧收到变更消息如下： { "event_id": "0f921313-4074-46a2-96f6-aac610721059", "timestamp": 1555313685831, "twin": { "humidity": { "last": { "expected": { "value": "9", "metadata": { "timestamp": 1555313665978 } }, "optional": true, "metadata": { "type": "int" } }, "current": { "expected": { "value": "10", "metadata": { "timestamp": 1555313685831 } }, "optional": true, "metadata": { "type": "int" } } }, "temperature": { "last": { "expected": { "value": "0", "metadata": { "timestamp": 1555313665978 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } }, "current": { "expected": { "value": "0", "metadata": { "timestamp": 1555313685831 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } } } } } 订阅设备孪生delta。 Topic：$hw/events/device/{device_id}/twin/update/delta 在边侧收到变更消息如下： { "event_id": "60fb5baf-d4ad-47b0-a21e-8b57b52d0978", "timestamp": 1555313685837, "twin": { "humidity": { "expected": { "value": "10", "metadata": { "timestamp": 1555313685831 } }, "optional": true, "metadata": { "type": "int" } }, "temperature": { "expected": { "value": "0", "metadata": { "timestamp": 1555313685831 } }, "actual": { "value": "2", "metadata": { "timestamp": 1555299457284 } }, "optional": true, "metadata": { "type": "int" } } }, "delta": { "humidity": "10", "temperature": "0" } }

上报设备属性实际值 发布终端设备孪生更新事件。 Topic：$hw/events/device/{device_id}/twin/update Payload：{"event_id":"", "timestamp":0, "twin":{"属性":{"actual":{"value":"设备实际值"}}}} 示例如下： { "event_id": "", "timestamp": 0, "twin": { "temperature": { "actual": { "value": "2" } } } } 发布后，在云端可以观察到设备孪生的实际值发生了相应的变化，如图2所示。 图2 孪生属性值发生变化 在边缘侧订阅设备孪生更新结果，能收到设备孪生更新事件的结果。 Topic：$hw/events/device/{device_id}/twin/update/result 更新的结果如下所示。 { "event_id": "", "timestamp": 1554992093859, "twin": { "temperature": { "actual": { "value": "2", "metadata": { "timestamp": 1554992093859 } }, "optional": true, "metadata": { "type": "int" } } } }

获取设备孪生 向设备孪生获取发送请求获取设备孪生。 Topic：$hw/events/device/{device_id}/twin/get Payload：{"event_id":"自定义id"} 向设备孪生获取结果订阅设备孪生的返回结果。 Topic：$hw/events/device/{dvice_id}/twin/get/result 获取的结果如下： { "event_id": "", "timestamp": 1554988425592, "twin": { "humidity": { "expected": { "value": "0", "metadata": { "timestamp": 1554988419529 } }, "optional": true, "metadata": { "type": "int" } }, "temperature": { "expected": { "value": "0", "metadata": { "timestamp": 1554988419529 } }, "optional": true, "metadata": { "type": "int" } } } }

MQTT Topic 终端设备与边缘节点、IEF的通信都是通过给MQTT broker中转消息实现的，在MQTT broker中，默认提供如表1所示的Topic（消息主题），上报状态、控制终端设备状态都是通过发送/订阅消息实现的。 应用程序编写完后，可以通过应用部署功能，将应用从IEF中部署到边缘节点，详情请参见容器应用管理。 表1 IEF提供的默认Topic 名称 使用类型 Topic 说明 设备孪生变更 订阅 $hw/events/device/{device_id}/twin/update/document 设备孪生更新文档，当孪生变化时，反映孪生变化前、变化后的区别。 设备孪生delta 订阅 $hw/events/device/{device_id}/twin/update/delta 设备孪生delta事件，当孪生变化时，反映期望值与真实值不一致的孪生信息。 设备成员变更 订阅 $hw/events/node/{node_id}/membership/updated 绑定终端设备关系变化。 设备属性变更 订阅 $hw/events/device/{device_id}/updated 终端设备属性更新。 设备成员获取 发布 $hw/events/node/{node_id}/membership/get 绑定终端设备关系获取。 设备成员获取结果 订阅 $hw/events/node/{node_id}/membership/get/result 绑定终端设备关系获取结果。 设备孪生获取 发布 $hw/events/device/{device_id}/twin/get 设备孪生获取。 设备孪生获取结果 订阅 $hw/events/device/{device_id}/twin/get/result 设备孪生获取结果。 设备孪生更新 发布 $hw/events/device/{device_id}/twin/update 设备孪生更新。 设备孪生更新结果 订阅 $hw/events/device/{device_id}/twin/update/result 设备孪生更新结果。 请求加密数据 发布 $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/decrypt 发布获取加密数据请求。 获取加密数据 订阅 $hw/{project_id}/encryptdatas/{encryptdata_name}/properties/{properties_name}/plaintext 订阅获取加密数据。 添加告警 发布 $hw/alarm/{appname}/add 向AOM发送告警。 清除告警 发布 $hw/alarm/{appname}/clear 清除AOM中告警。 自定义Topic 发布 {project_id}/nodes/{node_id}/user/{custom_topic} 自定义Topic，Topic根据您的需要自行定义。 您可以将终端设备数据发送到边缘节点MQTT broker的自定义Topic中，IEF会将这些数据转发到DIS通道或APIG后端地址。数据转发到DIS通道或者APIG后端地址后，您可以提取这些数据，并对数据进行处理分析。 接下来将介绍如何在边缘侧获取终端设备信息，接收云上的控制消息，以及如何将终端设备数据上报到云端。MQTT收发消息的示例代码请参见Go语言代码样例和Java语言代码样例。

获取节点关联的终端设备成员 向设备成员获取发送获取终端设备成员消息的请求。 Topic：$hw/events/node/{node_id}/membership/get Payload：{"event_id":"自定义ID"} 示例如下： $hw/events/node/{node_id}/membership/get {"event_id":""} 向设备成员获取结果订阅终端设备成员的返回结果。 Topic：$hw/events/node/{node_id}/membership/get/result 返回结果示例如下： { "event_id": "", "timestamp": 1554986455386, "devices": [ { "id": "2144773f-13f1-43f5-af07-51991d4fd064", "name": "equipmentA", "state": "unknown", "attributes": { "name": { "value": "a", "optional": true, "metadata": { "type": "string" } } } } ] }

MQTT broker 终端设备可以通过MQTT协议与IEF云端进行通信，您也可以通过发送/订阅消息控制终端设备。 边缘节点上有一个内置MQTT broker，内置MQTT broker使用8883端口与终端设备通信，与内置MQTT broker通信需要经过安全认证，具体请参见使用证书进行安全认证。 另外，边缘节点还支持与外置MQTT broker通信，即在边缘节点上安装一个MQTT broker（如开源的Mosquitto，默认使用1883端口通信）。 如使用外置MQTT broker，请注意需要保证外置MQTT broker通信的端口能正常使用。

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/update/result { "event_id":"123457", "timestamp":1557317614026, "twin":{ "state":{ "actual":{ "value":"stop", "metadata":{ "timestamp":1557317614026 } }, "optional":true, "metadata":{ "type":"string" } } } }

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/update/result { "event_id":"123457", "timestamp":1557317614026, "twin":{ "state":{ "actual":{ "value":"stop", "metadata":{ "timestamp":1557317614026 } }, "optional":true, "metadata":{ "type":"string" } } } }

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/update { "event_id":"123457", "twin":{ "state":{ "actual":{ "value":"stop" } } } }

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/update { "event_id":"123457", "twin":{ "state":{ "actual":{ "value":"stop" } } } }

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/get/result { "event_id":"123456", "timestamp":1557317510926, "twin":{ "state":{ "expected":{ "value":"stop", "metadata":{ "timestamp":1557316778931 } }, "optional":true, "metadata":{ "type":"string" } } } }

示例 $hw/events/device/ab39361a-6fc0-4c94-b919-72b1e08ca690/twin/get/result { "event_id":"123456", "timestamp":1557317510926, "twin":{ "state":{ "expected":{ "value":"stop", "metadata":{ "timestamp":1557316778931 } }, "optional":true, "metadata":{ "type":"string" } } } }

示例 $hw/events/node/3fbb5b8d-32db-4271-a34f-a013e021b6ce/membership/get/result { "event_id":"bc876bc-345d-4050-86a8-319a5b13cc10", "timestamp":1557317193524, "devices":[ { "id":"ab39361a-6fc0-4c94-b919-72b1e08ca690", "name":"IEF-device", "state":"unknown", "attributes":{ "address":{ "value":"longgang", "optional":true, "metadata":{ "type":"string" } } } } ] }

示例 $hw/events/node/3fbb5b8d-32db-4271-a34f-a013e021b6ce/membership/get/result { "event_id":"bc876bc-345d-4050-86a8-319a5b13cc10", "timestamp":1557317193524, "devices":[ { "id":"ab39361a-6fc0-4c94-b919-72b1e08ca690", "name":"IEF-device", "state":"unknown", "attributes":{ "address":{ "value":"longgang", "optional":true, "metadata":{ "type":"string" } } } } ] }

示例 终端设备绑定到边缘节点时可收到如下消息。 $hw/events/device/{device_id}/updated { "event_id":"", "timestamp":1557314742136, "attributes":{ "address":{ "value":"shenzhen", "optional":true, "metadata":{ "type":"string" } } } }