华为云用户手册

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 device_id String 设备ID，用于唯一标识一个设备，在注册设备时由 物联网平台 分配获得。 messages Array of DeviceMessage objects 设备消息列表。 表4 DeviceMessage 参数 参数类型 描述 message_id String 设备消息ID，用于唯一标识一条消息，在下发设备消息时由物联网平台分配获得。 name String 消息名称,在下发消息时由用户指定。 message Object 消息内容。 encoding String 消息内容编码格式，取值范围none|base64,默认值none, base64格式仅支持透传。 payload_format String 有效负载格式，在消息内容编码格式为none时有效，取值范围standard|raw，默认值standard（平台封装的标准格式），取值为raw时直接将消息内容作为有效负载下发。 topic String 消息topic properties PropertiesDTO object 消息下行到设备的属性参数。 status String 消息状态，包含PENDING，DELIVERED，FAILED和TIMEOUT，PENDING指设备不在线，消息被缓存起来，等设备上线之后下发； DELIVERED指消息发送成功；FAILED消息发送失败；TIMEOUT指消息在平台默认时间内（1天）还没有下发送给设备，则平台会将消息设置为超时，状态为TIMEOUT。 error_info ErrorInfoDTO object 消息下发失败信息。 created_time String 消息的创建时间，"yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串。 finished_time String 消息结束时间, "yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串，包含消息转换到DELIVERED和TIMEOUT两个状态的时间。 表5 PropertiesDTO 参数 参数类型 描述 correlation_data String 参数说明：MQTT 5.0版本请求和响应模式中的相关数据，可选。用户可以通过该参数配置MQTT协议请求和响应模式中的相关数据。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 response_topic String 参数说明：MQTT 5.0版本请求和响应模式中的响应主题，可选。用户可以通过该参数配置MQTT协议请求和响应模式中的响应主题。 取值范围：长度不超过128, 只允许字母、数字、以及_-?=$#+/等字符的组合。 最大长度：128 user_properties Array of UserPropDTO objects 参数说明：用户自定义属性，可选。用户可以通过该参数配置用户自定义属性。可以配置的最大自定义属性数量为20。 表6 UserPropDTO 参数 参数类型 描述 prop_key String 参数说明：用户自定义属性键。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 prop_value String 参数说明：用户自定义属性值。 取值范围：长度不超过128，只允许中文、字母、数字、以及_? '#().,&%@!-等字符的组合。 表7 ErrorInfoDTO 参数 参数类型 描述 error_code String 参数说明：异常信息错误码，包含IOTDA.014016和IOTDA.014112。IOTDA.014016表示设备不在线；IOTDA.014112表示设备没有订阅topic。 error_msg String 参数说明：异常信息说明，包含设备不在线和设备没有订阅topic说明。

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

URI GET /v5/iot/{project_id}/devices/{device_id}/messages 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 device_id 是 String 参数说明：下发消息的设备ID，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

请求示例 创建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" } } }

响应示例 状态码： 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" } } }

响应参数 状态码： 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、数字的组合。

请求参数 表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、数字的组合。

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

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

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

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 queues Array of QueryQueueBase objects 队列信息列表。 page Page object 查询结果的分页信息。 表5 QueryQueueBase 参数 参数类型 描述 queue_id String 队列ID，用于唯一标识一个队列。 queue_name String 队列名称，同一租户不允许重复。 最小长度：8 最大长度：128 create_time String 在物联网平台创建队列的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 last_modify_time String 在物联网平台最后修改队列的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 表6 Page 参数 参数类型 描述 count Long 满足查询条件的记录总数。 marker String 本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。

响应示例 状态码： 200 OK { "queues" : [ { "queue_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "queue_name" : "myQueue0", "create_time" : "20190303T081011Z", "last_modify_time" : "20190303T081011Z" } ], "page" : { "count" : 10, "marker" : "5c90fa7d3c4e4405e8525079" } }

URI GET /v5/iot/{project_id}/amqp-queues 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 表2 Query参数 参数 是否必选 参数类型 描述 queue_name 否 String 参数说明：amqp队列名称，支持模糊查询，为空查询所有的队列（当前规格单个用户最大100个队列）。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）、间隔号（.）、冒号（:）的组合。 最大长度：128 limit 否 Integer 参数说明：分页查询时每页显示的记录数。 取值范围：1-50的整数，默认值为10。 最小值：1 最大值：50 缺省值：10 marker 否 String 参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker值。 取值范围：长度为24的十六进制字符串，默认值为ffffffffffffffffffffffff。 缺省值：ffffffffffffffffffffffff offset 否 Integer 参数说明：表示从marker后偏移offset条记录开始查询。默认为0，取值范围为0-500的整数。当offset为0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。 取值范围：0-500的整数，默认为0。 最小值：0 最大值：500 缺省值：0

错误码 HTTP状态码 HTTP状态码描述 错误码 错误码描述 错误码中文描述 400 Bad Request IOTDA.000006 Invalid input data. 请求参数不合法 IOTDA.021104 Subdevices in the request does not exist or does not belong to the gateway. 请求中有部分子设备不存在或不属于该网关. 403 Forbidden IOTDA.000004 Invalid access token. 非法token IOTDA.021101 Request reached the maximum rate limit. 请求已经达到限制速率 IOTDA.021102 The request rate has reached the upper limit of the tenant, limit %s. 请求已经达到租户的限制速率 IOTDA.021103 The request batch properties number has reached the upper limit, limit %s. 请求中子设备数量达到上限 IOTDA.021105 The content reported in a single request cannot exceed 1 MB. 单次请求上报的内容不能超过1MB

请求示例 POST https://{endpoint}/v5/devices/{device_id}/sys/gateway/sub-devices/properties/report Content-Type: application/json access_token: ****** { "devices" : [ { "device_id" : "deviceId_0001", "services" : [ { "service_id" : "serviceId", "properties" : { "Height" : 124, "Speed" : 23.24 }, "event_time" : "2021-08-13T10:10:10.555Z" } ] }, { "device_id" : "deviceId_0002", "services" : [ { "service_id" : "serviceId", "properties" : { "Height" : 124, "Speed" : 23.24 }, "event_time" : "2021-08-13T10:10:10.555Z" } ] } ] }

示例 Topic: $oc/devices/{device_id}/sys/events/down 数据格式： { "object_device_id":"{object_device_id}", "services":[ { "service_id":"$device_config", "event_type":"config_update", "event_time":"20151212T121212Z", "paras":{ "config_content":{ "config_key1":"device config1", "config_key2":"device config2" } } } ] }

响应示例 状态码： 200 OK { "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "app_name" : "testAPP01", "device_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "node_id" : "ABC123456789", "gateway_id" : "d4922d8a-6c8e-4396-852c-164aefa6638f", "device_name" : "dianadevice", "node_type" : "ENDPOINT", "description" : "watermeter device", "fw_version" : "1.1.0", "sw_version" : "1.1.0", "auth_info" : { "auth_type" : "SECRET", "secret" : "3b935a250c50dc2c6d481d048cefdc3c", "fingerprint" : "dc0f1016f495157344ac5f1296335cff725ef22f", "secure_access" : true, "timeout" : 0 }, "product_id" : "b640f4c203b7910fc3cbd446ed437cbd", "product_name" : "Thermometer", "status" : "ONLINE", "create_time" : "20190303T081011Z", "connection_status_update_time" : "2019-03-03T08:10:111Z", "active_time" : "2019-03-03T08:10:111Z", "tags" : [ { "tag_key" : "testTagName", "tag_value" : "testTagValue" } ], "extension_info" : { "aaa" : "xxx", "bbb" : 0 } }

响应参数 状态码： 200 表5 响应Body参数 参数 参数类型 描述 app_id String 资源空间ID。 最大长度：36 app_name String 资源空间名称。 device_id String 设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。由物联网平台分配时，生成规则为"product_id" + "_" + "node_id"拼接而成。 node_id String 设备标识码，通常使用IMEI、MAC地址或Serial No作为node_id。 gateway_id String 网关ID，用于标识设备所属的父设备，即父设备的设备ID。当设备是直连设备时，gateway_id与设备的device_id一致。当设备是非直连设备时，gateway_id为设备所关联的父设备的device_id。 device_name String 设备名称。 node_type String 设备节点类型。 ENDPOINT：非直连设备。 GATEWAY：直连设备或网关。 UNKNOWN：未知。 description String 设备的描述信息。 fw_version String 设备的固件版本。 sw_version String 设备的软件版本。 device_sdk_version String 设备的sdk信息。 auth_info AuthInfoRes object 设备的接入认证信息。 product_id String 设备关联的产品ID，用于唯一标识一个产品模型。 product_name String 设备关联的产品名称。 status String 设备的状态。 ONLINE：设备在线。 OFFLINE：设备离线。 ABNORMAL：设备异常。 INACTIVE：设备未激活。 FROZEN：设备冻结。 create_time String 在物联网平台注册设备的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 connection_status_update_time String 设备最近一次连接状态(ONLINE:在线，OFFLINE：离线，ABNORMAL：异常)变化时间。格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' ，如2015-12-12T12:12:122Z。 active_time String 设备激活时间。格式：yyyy-MM-dd'T'HH:mm:ss.SSS'Z' ，如2015-12-12T12:12:122Z。 tags Array of TagV5DTO objects 设备的标签列表。 extension_info Object 设备扩展信息。用户可以自定义任何想要的扩展信息，如果在创建设备时为子设备指定该字段，将会通过MQTT接口“平台通知网关子设备新增“将该信息通知给网关。 表6 AuthInfoRes 参数 参数类型 描述 auth_type String 参数说明：鉴权类型。注意：不填写auth_type默认为密钥认证接入方式(SECRET)。 取值范围： SECRET:使用密钥认证接入方式。 CERTIFICATES:使用证书认证接入方式。 secret String 参数说明：设备密钥，认证类型使用密钥认证接入(SECRET)可填写该字段。注意：NB设备密钥由于协议特殊性，只支持十六进制密钥接入；查询设备列表接口不返回该参数。 取值范围：长度不低于8不超过32，只允许字母、数字、下划线（_）、连接符（-）的组合。 最小长度：8 最大长度：32 secondary_secret String 参数说明：设备备用密钥，认证类型使用密钥认证接入(SECRET)该字段有效，当主密钥校验不通过时，会启用辅密钥校验，辅密钥与主密钥有相同的效力；辅密钥对coap协议接入的设备不生效。注意：NB设备密钥由于协议特殊性，只支持十六进制密钥接入；查询设备列表接口不返回该参数。 取值范围：长度不低于8不超过32，只允许字母、数字、下划线（_）、连接符（-）的组合。 最小长度：8 最大长度：32 fingerprint String 参数说明：证书指纹，认证类型使用证书认证接入(CERTIFICATES)该字段有效，注册设备时不填写该字段则取第一次设备接入时的证书指纹。 取值范围：长度为40的十六进制字符串或者长度为64的十六进制字符串。 secondary_fingerprint String 参数说明：证书备用指纹，认证类型使用证书认证接入(CERTIFICATES)该字段有效，当主指纹校验不通过时，会启用辅指纹校验，辅指纹与主指纹有相同的效力。 取值范围：长度为40的十六进制字符串或者长度为64的十六进制字符串。 secure_access Boolean 参数说明：指设备是否通过安全协议方式接入。 取值范围： true：通过安全协议方式接入。 false：通过非安全协议方式接入。非安全接入的设备存在被仿冒等安全风险，请谨慎使用。 缺省值：true timeout Integer 参数说明：设备接入的有效时间，单位：秒，默认值：0 若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为“0”，则表示平台不会删除该设备的注册信息（建议填写为“0”）。 注意：该参数只对直连设备生效。 最小值：0 最大值：2147483647 缺省值：0 表7 TagV5DTO 参数 参数类型 描述 tag_key String 参数说明：标签键，在同一资源下标签键唯一。绑定资源时，如果设置的键已存在，则将覆盖之前的标签值。如果设置的键值不存在，则新增标签。 取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合。 tag_value String 参数说明：标签值。 取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。

请求示例 修改设备，修改设备的名为device，接入类型为安全接入。 PUT https://{endpoint}/v5/iot/{project_id}/devices/{device_id} { "device_name" : "device", "description" : "watermeter device", "extension_info" : { "aaa" : "xxx", "bbb" : 0 }, "auth_info" : { "secure_access" : true } }

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 device_name 否 String 参数说明：设备名称，资源空间下唯一，用于资源空间下唯一标识一个设备。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合，建议不少于4个字符。 最小长度：1 最大长度：256 description 否 String 参数说明：设备的描述信息。 取值范围：长度不超过2048，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合 最大长度：2048 extension_info 否 Object 参数说明：设备扩展信息。用户可以自定义任何想要的扩展信息，修改子设备信息时不会下发给网关。 auth_info 否 AuthInfoWithoutSecret object 参数说明：设备的接入认证信息。 表4 AuthInfoWithoutSecret 参数 是否必选 参数类型 描述 secure_access 否 Boolean 参数说明：指设备是否通过安全协议方式接入。 取值范围： true：通过安全协议方式接入。 false：通过非安全协议方式接入。非安全接入的设备存在被仿冒等安全风险，请谨慎使用。 缺省值：true timeout 否 Integer 参数说明：设备接入的有效时间，单位：秒，默认值：0。若设备在有效时间内未接入物联网平台并激活，则平台会删除该设备的注册信息。若设置为“0”，则表示平台不会删除该设备的注册信息（建议填写为“0”）。 注意：该参数只对直连设备生效 最小值：0 最大值：2147483647 缺省值：0

URI PUT /v5/iot/{project_id}/devices/{device_id} 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 device_id 是 String 参数说明：设备ID，用于唯一标识一个设备。在注册设备时直接指定，或者由物联网平台分配获得。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。

响应示例 状态码： 200 Ok { "flowcontrol_policies" : [ { "policy_id" : "adadd5cb-6383-4b5b-a65c-f8c92fdf3c34", "policy_name" : "policyName", "description" : "description", "scope" : "CHANNEL", "scope_value" : "HTTP_FORWARDING", "limit" : 10 } ], "count" : 10, "marker" : "5c90fa7d3c4e4405e8525079" }

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 flowcontrol_policies Array of FlowControlPolicyInfo objects 数据流转流控策略列表。 数组长度：0 - 50 count Integer 满足查询条件的记录总数。 marker String 本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。 表5 FlowControlPolicyInfo 参数 参数类型 描述 policy_id String 参数说明：数据流转流控策略id，用于唯一标识一个数据流转流控策略，在创建数据流转流控策略时由物联网平台分配获得。 policy_name String 参数说明：数据流转流控策略名称。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最小长度：1 最大长度：256 description String 参数说明：用户自定义的数据流转流控策略描述。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最小长度：1 最大长度：256 scope String 参数说明：流控策略作用域. 取值范围： USER：租户级流控策略。 CHANNEL：转发通道级流控策略。 RULE：转发规则级流控策略。 ACTION：转发动作级流控策略。 scope_value String 参数说明：流控策略作用域附加值。 scope取值为USER时，可不携带该字段，表示租户级流控。 scope取值为CHANNEL时，取值范围：HTTP_FORWARDING、DIS_FORWARDING、OBS_FORWARDING、AMQP_FORWARDING、DMS_KAFKA_FORWARDING。 scope取值为RULE时，该字段为对应的ruleId。 scope取值为ACTION时，该字段为对应的actionId。 limit Integer 参数说明：数据转发流控大小。单位为tps，取值范围为1~1000的整数，默认为1000. 最小值：1 最大值：1000 缺省值：1000

URI GET /v5/iot/{project_id}/routing-rule/flowcontrol-policy 表1 路径参数 参数 是否必选 参数类型 描述 project_id 是 String 参数说明：项目ID。获取方法请参见 获取项目ID 。 表2 Query参数 参数 是否必选 参数类型 描述 scope 否 String 参数说明：流控策略作用域。不携带该参数时，查询所有作用域流控策略；取值USER时，查询租户级流控策略；取值为CHANNEL时，查询转发通道级流控策略；取值为RULE时，查询转发规则级流控策略；取值为ACTION时，查询转发动作级流控策略。 scope_value 否 String 参数说明：流控策略作用域附加值。 不携带scope参数或scope参数取值为USER时，可不携带该字段，查询租户级流控策略。 scope参数取值为CHANNEL时，不携带该字段表示查询所有转发通道级流控策略，携带该字段表示查询该字段取值对应转发通道的流控策略。取值范围：HTTP_FORWARDING、DIS_FORWARDING、OBS_FORWARDING、AMQP_FORWARDING、DMS_KAFKA_FORWARDING。 scope参数为RULE时，不携带该字段表示查询所有转发规则级流控策略，携带该字段表示查询该字段取值对应转发规则的流控策略。 scope参数为ACTION时，不携带该字段表示查询所有转发动作级流控策略，携带该字段表示查询该字段取值对应转发动作的流控策略。 policy_name 否 String 参数说明：数据流转流控策略名称。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最小长度：1 最大长度：256 limit 否 Integer 参数说明：分页查询时每页显示的记录数。默认每页10条记录，最大设定每页50条记录。 取值范围：1-50的整数，默认值为10。 最小值：1 最大值：50 缺省值：10 marker 否 String 参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker值。 取值范围：长度为24的十六进制字符串，默认值为ffffffffffffffffffffffff。 缺省值：ffffffffffffffffffffffff offset 否 Integer 参数说明：表示从marker后偏移offset条记录开始查询。默认为0，取值范围为0-500的整数。当offset为0时，表示从marker后第一条记录开始输出。 - 限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。 取值范围：0-500的整数，默认为0。 最小值：0 最大值：500 缺省值：0

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

下行请求示例 Topic: $oc/devices/{device_id}/sys/commands/request_id={request_id} 数据格式： { "object_device_id": "{object_device_id}", "command_name": "ON_OFF", "service_id": "WaterMeter", "paras": { "value": "1" } }

下行请求参数说明 字段名 必选/可选 类型 参数描述 object_device_id 可选 String 平台下发时，若为网关子设备，该参数为Topic中设备的子设备Id。 平台下发时，若为直连设备，该参数会与Topic中的device_id一致。 service_id 可选 String 设备的服务ID，在设备关联的产品模型中定义。 command_name 可选 String 设备命令名称，在设备关联的产品模型中定义。 paras 必选 Object 设备命令的执行参数，具体字段在设备关联的产品模型中定义。

上行响应示例 Topic：$oc/devices/{device_id}/sys/commands/response/request_id={request_id} 数据格式： { "result_code": 0, "response_name": "COMMAND_RESPONSE", "paras": { "result": "success" } }

Topic 下行： $oc/devices/{device_id}/sys/commands/request_id={request_id} 上行：$oc/devices/{device_id}/sys/commands/response/request_id={request_id} {request_id}用于唯一标识这次请求。设备侧收到下行请求的topic带该参数时，上行响应的topic需要将该参数值返回给平台。 应用通过平台下发设备命令时，平台会生成唯一ID（command_id）用于标识该命令，并返回给应用。同时该唯一标识会通过设备命令下行Topic中的requst_id携带给设备。 设备无法提前感知该request_id，在订阅该Topic时请使用通配符“#”来替代“request_id={request_id}”即为：$oc/devices/{device_id}/sys/commands/#。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。。 Instance-Id 否 String 实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 content 是 String 证书内容信息。 最小长度：1 最大长度：65535 app_id 否 String 资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的证书归属到哪个资源空间下，否则创建的证书将会归属到默认资源空间下。