设备接入 IOTDA-华为云

设备接入 IOTDA-设备消息状态变更通知:请求示例

请求示例设备消息状态变更通知示例：设备消息状态变更通知 { "resource" : "device.message.status", "event" : "update", "event_time" : "20151212T121212Z", "event_time_ms" : "2015-12-12T12:12:12.000Z", "request_id" : "3fe58d5e-8697-4849-a165-7db128f7e776", "notify_data" : { "header" : { "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "product_id" : "ABC123456789", "app_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "node_id" : "ABC123456789", "tags" : [ { "tag_value" : "testTagValue", "tag_key" : "testTagName" } ] } }, "body" : { "error_info" : { "error_msg" : "Send to device failed, device not subscribe topic.", "error_code" : "IOTDA.014112" }, "name" : "name", "topic" : "topic", "message_id" : "1235", "status" : "DELIVERED", "timestamp" : "20151212T121212Z" } }

设备接入 IOTDA

设备接入 IOTDA-设备消息状态变更通知:请求参数

请求参数表1 请求Body参数参数是否必选参数类型描述 resource 是 String 参数说明：订阅的资源名称，取值为device.message.status。 event 是 String 参数说明：订阅的资源事件，取值为update。 event_time 是 String 参数说明：资源事件生成时间,格式：yyyyMMdd'T'HHmmss'Z' UTC字符串，如：20151212T121212Z。若需要显示本地时区，您需要自己进行时间转换。 event_time_ms 否 String 参数说明：资源事件生成时间,格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' UTC字符串，如：2015-12-12T12:12:12.000Z。若需要显示本地时区，您需要自己进行时间转换。 request_id 否 String 参数说明：消息ID，由设备侧指定或平台生成，用于跟踪业务流程。 notify_data 是 DeviceMessageStatusUpdateNotifyDataV5 object 参数说明：推送消息。表2 DeviceMessageStatusUpdateNotifyDataV5 参数是否必选参数类型描述 header 是 NotifyDataHeader object 参数说明：推送消息header。 body 是 DeviceMessageStatusUpdate object 参数说明：推送消息body。表3 NotifyDataHeader 参数是否必选参数类型描述 app_id 否 String 参数说明：应用ID。最大长度：256 device_id 否 String 参数说明：设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。最大长度：256 node_id 否 String 参数说明：设备标识码，通常使用IMEI、MAC地址或Serial No作为nodeId。最大长度：256 product_id 否 String 参数说明：产品ID，用于唯一标识一个产品，在注册产品时由物联网平台分配获得。最大长度：256 gateway_id 否 String 参数说明：网关ID，用于标识一个网关设备。当设备是直连设备时，gatewayId与设备的deviceId一致。当设备是非直连设备时，gatewayId为设备所关联的直连设备（即网关）的deviceId。最大长度：256 tags 否 Array of TagV5DTO objects 参数说明：要绑定到指定资源的标签列表，标签列表中各项标签键值之间不允许重复，一个资源最多可以绑定10个标签。表4 TagV5DTO 参数是否必选参数类型描述 tag_key 是 String 参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 tag_value 否 String 参数说明：标签值。表5 DeviceMessageStatusUpdate 参数是否必选参数类型描述 topic 否 String 参数说明：消息上报使用的mqtt topic。 message_id 是 String 参数说明：消息的序列号，唯一标识一条消息。 name 否 String 参数说明：消息名称。 status 否 String 参数说明：设备消息状态，包含：PENDING,DELIVERED,TIMEOUT,FAILED。 error_info 否 ErrorInfoDTO object 参数说明：消息下发失败信息。 timestamp 否 String 参数说明：消息更新时间,格式：yyyyMMdd'T'HHmmss'Z' UTC字符串，如：20151212T121212Z。表6 ErrorInfoDTO 参数是否必选参数类型描述 error_code 否 String 参数说明：异常信息错误码，包含IOTDA.014016和IOTDA.014112。IOTDA.014016表示设备不在线；IOTDA.014112表示设备没有订阅topic。 error_msg 否 String 参数说明：异常信息说明，包含设备不在线和设备没有订阅topic说明。

设备接入 IOTDA

设备接入 IOTDA-查询规则动作:请求参数

请求参数表2 请求Header参数参数是否必选参数类型描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，一般华为云租户无需携带该参数，仅在物理多租场景下从管理面访问API时需要携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID。

设备接入 IOTDA

设备接入 IOTDA-查询规则动作:URI

URI GET /v5/iot/{project_id}/routing-rule/actions/{action_id} 表1 路径参数参数是否必选参数类型描述 project_id 是 String 参数说明：项目ID。获取方法请参见获取项目ID 。 action_id 是 String 参数说明：规则动作ID。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

设备接入 IOTDA

设备接入 IOTDA-查询规则动作:响应示例

响应示例状态码： 200 OK { "action_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce0", "rule_id" : "1a7ffc5c-d89c-44dd-8265-b1653d951ce1", "app_id" : "1a7ffc5cd89c44dd8265b1653d951ce0", "channel" : "HTTP_FORWARDING", "channel_detail" : { "http_forwarding" : { "url" : "http://host:port/callbackurltest" } } }

设备接入 IOTDA

设备接入 IOTDA-获取项目ID:调用API获取项目ID

调用API获取项目ID 项目ID还可以通过调用查询指定条件下的项目信息API获取。获取项目ID的接口为“GET https://{Endpoint}/v3/projects”，其中{Endpoint}为IAM的终端节点，可以从地区和终端节点获取。接口的认证鉴权请参见认证鉴权。响应示例如下，其中projects下的“id”即为项目ID。 { "projects": [ { "domain_id": "65382450e8f64ac0870cd180d...", "is_domain": false, "parent_id": "65382450e8f64ac0870cd180d1...", "name": "cn-north-4", "description": "", "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd0..." }, "id": "a4a5d4098fb4474fa22cd05f897xxxx", "enabled": true } ], "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects" } }

设备接入 IOTDA

设备接入 IOTDA-创建OTA升级包:请求参数

请求参数表2 请求Header参数参数是否必选参数类型描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情。表3 请求Body参数参数是否必选参数类型描述 app_id 是 String 参数说明：资源空间ID。存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的升级包归属到哪个资源空间下。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 package_type 是 String 参数说明：升级包类型。取值范围：软件包必须设置为：softwarePackage，固件包必须设置为：firmwarePackage。 product_id 是 String 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，创建产品后获得。方法请参见创建产品。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 version 是 String 参数说明：升级包版本号。取值范围：长度不超过256，只允许字母、数字、下划线（_）、连接符（-）、英文点（.）的组合。 support_source_versions 否 Array of strings 参数说明：支持用于升级此版本包的设备源版本号列表。最多支持20个源版本号。取值范围：源版本号列表，源版本号只允许字母、数字、下划线（_）、连接符（-）、英文点（.）的组合。 description 否 String 参数说明：用于描述升级包的功能等信息。取值范围：长度不超过1024。最大长度：1024 custom_info 否 String 参数说明：推送给设备的自定义信息。添加该升级包完成，并创建升级任务后，物联网平台向设备下发升级通知时，会下发该自定义信息给设备。取值范围：长度不超过4096。最大长度：4096 file_location 是 FileLocation object 升级包的位置表4 FileLocation 参数是否必选参数类型描述 obs_location 否 ObsLocation object 升级包关联OBS对象位置表5 ObsLocation 参数是否必选参数类型描述 region_name 是 String 参数说明：OBS所在区域。您可以从地区和终端节点中查询服务的终端节点。取值范围：长度不超过256，只允许字母、数字、连接符（-）的组合。 bucket_name 是 String 参数说明：OBS桶名称。取值范围：长度最小为3，最大为63，只允许小写字母、数字、连接符（-）、英文点（.）的组合。 object_key 是 String 参数说明：OBS对象名称(包含文件夹路径)，对象大小最大为1G，且只支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack、.exe、.bat、.img格式的文件。取值范围：长度不超过1024。最小长度：1 最大长度：1024 sign 否 String 参数说明：SHA256算法计算出的升级包签名值。添加该升级包完成，并创建升级任务后，物联网平台向设备下发升级通知时，会下发该签名给设备。取值范围：长度为64，只允许大小写字母a到f、数字的组合。

设备接入 IOTDA OTA升级包管理

设备接入 IOTDA-创建OTA升级包:请求示例

请求示例创建OTA升级包，上传固件包。 POST https://{endpoint}/v5/iot/{project_id}/ota-upgrades/packages { "app_id" : "61f7e74d036aca5be29e1ed4", "package_type" : "firmwarePackage", "product_id" : "5ba24f5ebbe8f56f5a14f605", "version" : "V2.0", "description" : "package v2.0", "custom_info" : "更新了XX功能，修复了XXXX问题", "file_location" : { "obs_location" : { "region_name" : "cn-north-4", "bucket_name" : "abc", "object_key" : "bbb/upgrade.bin" } } } 创建OTA升级包，上传固件包，差分包场景，支持从V1.0和V1.1版本升级。 POST https://{endpoint}/v5/iot/{project_id}/ota-upgrades/packages { "app_id" : "61f7e74d036aca5be29e1ed4", "package_type" : "firmwarePackage", "product_id" : "5ba24f5ebbe8f56f5a14f605", "version" : "V2.0", "support_source_versions" : [ "V1.0", "V1.1" ], "description" : "package for version V1.0 and V1.1", "custom_info" : "更新了XX功能，修复了XXXX问题", "file_location" : { "obs_location" : { "region_name" : "cn-north-4", "bucket_name" : "abc", "object_key" : "bbb/upgrade.bin" } } }

设备接入 IOTDA OTA升级包管理

设备接入 IOTDA-创建OTA升级包:响应示例

响应示例状态码： 201 Created { "package_id" : "28f61af50fc9452aa0ed5ea25c3cc3d3", "app_id" : "61f7e74d036aca5be29e1ed4", "package_type" : "firmwarePackage", "product_id" : "5ba24f5ebbe8f56f5a14f605", "version" : "V2.0", "support_source_versions" : [ "V1.0", "V1.1" ], "description" : "package for version V1.0 and V1.1", "custom_info" : "更新了XX功能，修复了XXXX问题", "create_time" : "20230211T121212Z", "file_location" : { "obs_location" : { "region_name" : "cn-north-4", "bucket_name" : "abc", "object_key" : "bbb/upgrade.bin" } } }

设备接入 IOTDA OTA升级包管理

设备接入 IOTDA-创建OTA升级包:响应参数

响应参数状态码： 201 表6 响应Body参数参数参数类型描述 package_id String 参数说明：升级包ID，用于唯一标识一个升级包。由物联网平台分配获得。取值范围：长度不超过36，只允许字母、数字、连接符（-）的组合。 app_id String 参数说明：资源空间ID。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 package_type String 参数说明：升级包类型。取值范围：软件包必须设置为：softwarePackage，固件包必须设置为：firmwarePackage。 product_id String 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，创建产品后获得。方法请参见创建产品。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 version String 参数说明：升级包版本号。取值范围：长度不超过256，只允许字母、数字、下划线（_）、连接符（-）、英文点（.）的组合。 support_source_versions Array of strings 参数说明：支持用于升级此版本包的设备源版本号列表。最多支持20个源版本号。取值范围：源版本号列表，源版本号只允许字母、数字、下划线（_）、连接符（-）、英文点（.）的组合。 description String 参数说明：用于描述升级包的功能等信息。取值范围：长度不超过1024。 custom_info String 参数说明：推送给设备的自定义信息。添加该升级包完成，并创建升级任务后，物联网平台向设备下发升级通知时，会下发该自定义信息给设备。取值范围：长度不超过4096。 create_time String 软固件包上传到物联网平台的时间，格式："yyyyMMdd'T'HHmmss'Z'"。 file_location FileLocation object 升级包的位置表7 FileLocation 参数参数类型描述 obs_location ObsLocation object 升级包关联OBS对象位置表8 ObsLocation 参数参数类型描述 region_name String 参数说明：OBS所在区域。您可以从地区和终端节点中查询服务的终端节点。取值范围：长度不超过256，只允许字母、数字、连接符（-）的组合。 bucket_name String 参数说明：OBS桶名称。取值范围：长度最小为3，最大为63，只允许小写字母、数字、连接符（-）、英文点（.）的组合。 object_key String 参数说明：OBS对象名称(包含文件夹路径)，对象大小最大为1G，且只支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack、.exe、.bat、.img格式的文件。取值范围：长度不超过1024。最小长度：1 最大长度：1024 sign String 参数说明：SHA256算法计算出的升级包签名值。添加该升级包完成，并创建升级任务后，物联网平台向设备下发升级通知时，会下发该签名给设备。取值范围：长度为64，只允许大小写字母a到f、数字的组合。

设备接入 IOTDA OTA升级包管理

设备接入 IOTDA-删除设备组:请求参数

请求参数表2 请求Header参数参数是否必选参数类型描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情。

设备接入 IOTDA 设备组管理

设备接入 IOTDA-删除设备组:URI

URI DELETE /v5/iot/{project_id}/device-group/{group_id} 表1 路径参数参数是否必选参数类型描述 project_id 是 String 参数说明：项目ID。获取方法请参见获取项目ID 。 group_id 是 String 参数说明：设备组ID，用于唯一标识一个设备组，在创建设备组时由物联网平台分配。取值范围：长度不超过36，十六进制字符串和连接符（-）的组合。

设备接入 IOTDA 设备组管理

设备接入 IOTDA-设备添加通知:请求示例

请求示例设备添加通知示例：设备添加通知 { "resource" : "device", "event" : "create", "event_time" : "20151212T121212Z", "event_time_ms" : "2015-12-12T12:12:12.000Z", "request_id" : "3fe58d5e-8697-4849-a165-7db128f7e776", "notify_data" : { "body" : { "device_sdk_version" : "C_v0.5.0", "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "create_time" : "20190303T081011Z", "description" : "watermeter device", "auth_info" : { "auth_type" : "SECRET", "secure_access" : true, "timeout" : 300 }, "product_name" : "Thermometer", "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "sw_version" : "1.1.0", "tags" : [ { "tag_value" : "testTagValue", "tag_key" : "testTagName" } ], "extension_info" : { "aaa" : "xxx", "bbb" : 0 }, "app_name" : "testAPP01", "device_name" : "dianadevice", "node_type" : "ENDPOINT", "product_id" : "b640f4c203b7910fc3cbd446ed437cbd", "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "fw_version" : "1.1.0", "node_id" : "ABC123456789", "status" : "INACTIVE" } } }

设备接入 IOTDA

设备接入 IOTDA-设备添加通知:请求参数

请求参数表1 请求Body参数参数是否必选参数类型描述 resource 是 String 参数说明：订阅的资源名称，取值为device。 event 是 String 参数说明：订阅的资源事件，取值为create。 event_time 是 String 参数说明：资源事件生成时间,格式：yyyyMMdd'T'HHmmss'Z' UTC字符串，如：20151212T121212Z。若需要显示本地时区，您需要自己进行时间转换。 event_time_ms 否 String 参数说明：资源事件生成时间,格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' UTC字符串，如：2015-12-12T12:12:12.000Z。若需要显示本地时区，您需要自己进行时间转换。 request_id 否 String 参数说明：消息ID，由设备侧指定或平台生成，用于跟踪业务流程。 notify_data 是 DeviceCreateOrUpdateNotifyData object 参数说明：推送消息。表2 DeviceCreateOrUpdateNotifyData 参数是否必选参数类型描述 body 是 QueryDeviceBase object 参数说明：推送消息内容。表3 QueryDeviceBase 参数是否必选参数类型描述 app_id 否 String 参数说明：资源空间ID。最大长度：36 app_name 否 String 参数说明：资源空间名称。 device_id 否 String 参数说明：设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。由物联网平台分配时，生成规则为"product_id" + "_" + "node_id"拼接而成。最大长度：256 node_id 否 String 参数说明：设备标识码，通常使用IMEI、MAC地址或Serial No作为nodeId。最大长度：64 gateway_id 否 String 参数说明：网关ID，用于标识设备所属的父设备，即父设备的设备ID。当设备是直连设备时，gateway_id与设备的device_id一致。当设备是非直连设备时，gateway_id为设备所关联的父设备的device_id。最大长度：256 device_name 否 String 参数说明：设备名称。最大长度：256 node_type 否 String 参数说明：设备节点类型。 ENDPOINT：非直连设备。 GATEWAY：直连设备或网关。 UNKNOWN：未知。 description 否 String 参数说明：设备的描述信息。最大长度：2048 fw_version 否 String 参数说明：设备的固件版本。最大长度：256 sw_version 否 String 参数说明：设备的软件版本。最大长度：256 device_sdk_version 否 String 参数说明：设备的SDK版本。最大长度：256 auth_info 否 AuthInfo object 参数说明：设备的接入认证信息。 product_id 否 String 参数说明：设备关联的产品ID，用于唯一标识一个产品模型。 product_name 否 String 参数说明：设备关联的产品名称。 status 否 String 参数说明：设备的状态。 ONLINE：设备在线。 OFFLINE：设备离线。 ABNORMAL：设备异常。 INACTIVE：设备未激活。 FREEZED：设备冻结。 create_time 否 String 参数说明：在物联网平台注册设备的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 tags 否 Array of TagV5DTO objects 参数说明：设备的标签列表。 extension_info 否 Object 参数说明：设备扩展信息。用户可以自定义任何想要的扩展信息，如果在创建设备时为子设备指定该字段，将会通过MQTT接口“平台通知网关子设备新增“将该信息通知给网关。表4 AuthInfo 参数是否必选参数类型描述 auth_type 否 String 参数说明：鉴权类型。支持密钥认证接入(SECRET)和证书认证接入(CERTIFICATES)两种方式。使用密钥认证接入方式(SECRET)填写secret字段，使用证书认证接入方式(CERTIFICATES)填写fingerprint字段，不填写auth_type默认为密钥认证接入方式(SECRET) secure_access 否 Boolean 参数说明：指设备是否通过安全协议方式接入，默认值为true。 true：通过安全协议方式接入。 false：通过非安全协议方式接入。缺省值：true timeout 否 Integer 参数说明：设备验证码的有效时间，单位：秒，默认值：0。若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为“0”，则表示设备验证码不会失效（建议填写为“0”）。注意：只有注册设备接口或者修改设备接口修改timeout时返回该参数。最小值：0 最大值：2147483647 缺省值：0 表5 TagV5DTO 参数是否必选参数类型描述 tag_key 是 String 参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 tag_value 否 String 参数说明：标签值。

设备接入 IOTDA

设备接入 IOTDA-修改设备代理:请求参数

请求参数表2 请求Header参数参数是否必选参数类型描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情。表3 请求Body参数参数是否必选参数类型描述 proxy_name 否 String 参数说明：设备代理名称最小长度：1 最大长度：64 proxy_devices 否 Array of strings 参数说明：代理设备列表，列表内所有设备共享网关权限，即列表内任意一个网关下的子设备可以通过组里任意一个网关上线然后进行数据上报。取值范围：列表内填写设备id，列表内最少有2个设备id，最多有10个设备id，设备id取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合，建议不少于4个字符。 effective_time_range 否 EffectiveTimeRange object 参数说明：规则有效期。表4 EffectiveTimeRange 参数是否必选参数类型描述 start_time 否 String 设备代理开始生效的时间，使用UTC时区，格式：yyyyMMdd'T'HHmmss'Z' end_time 否 String 设备代理失效的时间，必须大于start_time，使用UTC时区，格式：yyyyMMdd'T'HHmmss'Z'

设备接入 IOTDA

云服务器内容精选

设备接入 IOTDA

7*24

备案

专业服务

退订

建议反馈

售前咨询热线