# 平台下发升级通知 #### 功能介绍 物联网平台向设备侧下发升级通知。 #### Topic 下行: $oc/devices/{device_id}/sys/events/down #### 参数说明 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | object_device_id | 可选 | String | **参数解释：** - 平台下发时，若为网关子设备，该参数为Topic中设备的子设备Id。 - 平台下发时，若为直连设备，该参数会与Topic中的device_id一致。 | | services | 可选 | List\ | **参数解释：** 事件服务列表。 | ServiceEvent定义表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | service_id | 必选 | String | **参数解释：** 系统字段，固定为："$ota"。 | | event_type | 必选 | String | **参数解释：** 软固件保存在IoT平台，event_type的值如下： -固件升级："firmware_upgrade"。 -软件升级："software_upgrade"。 软固件保存在OBS，event_type的值如下： -固件升级："firmware_upgrade_v2"。 -软件升级："software_upgrade_v2"。 | | event_time | 可选 | String | **参数解释：** 事件时间。UTC时间，格式：yyyyMMdd'T'HHmmss'Z'。 | | paras | 必选 | Object | **参数解释：** 事件参数JSON对象。 | event_type为firmware_upgrade、software_upgrade时paras参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | version | 必选 | String | **参数解释：** 软固件包版本号。 | | url | 必选 | String | **参数解释：** 软固件包下载地址。 | | file_size | 必选 | Integer | **参数解释：** 软固件包文件大小。 | | file_name | 必选 | String | **参数解释：** 升级包文件名 | | access_token | 可选 | String | **参数解释：** 软固件包url下载地址的临时token。 | | expires | 可选 | Integer | **参数解释：** access_token的超期时间。 | | sign | 必选 | String | **参数解释：** 软固件包SHA-256值。 | | custom_info | 可选 | String | **参数解释：** 推送给设备的自定义信息。 | | task_id | 可选 | String | **参数解释：** 网关模式下，创建软固件升级批量任务的任务ID。 | | sub_device_count | 可选 | Integer | **参数解释：** 网关模式下，同一个软固件升级批量任务中网关设备包含的升级子设备数量。 | | task_ext_info | 可选 | Object | **参数解释：** 创建软固件升级任务中添加的额外扩展信息。 | event_type为firmware_upgrade_v2、software_upgrade_v2时paras参数列表 | 字段名 | 必选/可选 | 类型 | 参数描述 | |:---|:---|:---|:---| | version | 必选 | String | **参数解释：** 软固件包版本号。 | | url | 必选 | String | **参数解释：** 软固件包下载地址(OBS地址)。 | | file_size | 必选 | Integer | **参数解释：** 软固件包文件大小。 | | file_name | 必选 | String | **参数解释：** 升级包文件名。 | | expires | 可选 | Integer | **参数解释：** url的超期时间。 | | sign | 可选 | String | **参数解释：** 上传OBS升级包时输入的SHA256算法计算出的升级包签名值。 | | custom_info | 可选 | String | **参数解释：** 推送给设备的自定义信息。 | | task_id | 可选 | String | **参数解释：** 网关模式下，创建软固件升级批量任务的任务ID。 | | sub_device_count | 可选 | Integer | **参数解释：** 网关模式下，同一个软固件升级批量任务中网关设备包含的升级子设备数量。 | | task_ext_info | 可选 | Object | **参数解释：** 创建软固件升级任务中添加的额外扩展信息。 | #### 示例一 ``` 软固件保存在IoT平台,升级时设备会收到如下信息： Topic: $oc/devices/{device_id}/sys/events/down 数据格式： { "object_device_id": "{object_device_id}", "services": [ { "service_id": "$ota", "event_type": "firmware_upgrade", "event_time": "20151212T121212Z", "paras": { "version": "v1.2", "url": "https://100.93.28.202:8943/iodm/dev/v2.0/upgradefile/applications/******/devices/******/packages/******", "file_size": 81362928, "file_name": "upgrade.bin", "access_token": "595124473f866b033dfa1f", "expires": 86400, "sign": "595124473f866b033dfa1f7e831c8c99a12f6143f392dfa996a819010842c99d", "custom_info": "This upgrade package adds some new features.", "task_id": "65d31bf2581ed33a42a58d76", "sub_device_count": 2, "task_ext_info": { "device_type": "DDC" } } } ] } ``` #### 示例二 ``` 软固件保存在OBS中,升级时设备会收到如下信息： Topic: $oc/devices/{device_id}/sys/events/down 数据格式： { "object_device_id": "{object_device_id}", "services": [ { "service_id": "$ota", "event_type": "firmware_upgrade_v2", "event_time": "20151212T121212Z", "paras": { "version": "v1.2", "url": "https://******:443/test.bin?AccessKeyId=DX5G7W*********", "file_size": 81362928, "file_name": "upgrade.bin", "expires": 3600, "sign": "595124473f866b033dfa1f7e831c8c99a12f6143f392dfa996a819010842c99d", "custom_info": "This upgrade package adds some new features.", "task_id": "65d31bf2581ed33a42a58d76", "sub_device_count": 2, "task_ext_info": { "device_type": "DDC" } } } ] } ``` #### 设备侧升级包下载指导 设备收到升级通知之后，通过HTTPS协议根据升级通知里面的URL下载升级包。基础版和标准版目前建议客户不校验证书可规避不能下载固件的问题。专享版如果需要校验证书，请提工单，后端帮忙配置域名。 #### 请求方法 下载升级包的请求方法为：GET #### 请求消息头 附加请求消息头（header）字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头"Content-Type"，请求鉴权信息等。 | 参数 | 说明 | |:---|:---| | Content-Type | **参数解释：** 消息体的媒体类型，默认取值为"application/json"。 | | Authorization | **参数解释：** 访问物联网平台的认证信息，值为"Bearer {access_token}"，其中{access_token}为收到的升级通知中的access_token。 | 示例 ``` GET https://100.93.28.202:8943/iodm/dev/v2.0/upgradefile/applications/******/devices/******/packages/****** Content-Type: application/json Authorization: Bearer ****** ``` ![](https://support.huaweicloud.com/api-iothub/public_sys-resources/caution_3.0-zh-cn.png) 如果event_type为firmware_upgrade_v2、software_upgrade_v2，则在请求下载软固件包时不需要携带请求头。请求示例如下： GET https://\*\*\*\*\*\*.obs.\*\*\*\*\*.com:443/test.bin?AccessKeyId=DX5G7W\*\*\*\*\*\*\*\*\*