华为云用户手册

响应参数 状态码： 201 表4 响应Body参数 参数 参数类型 描述 policy_id String 参数说明：数据流转积压策略id，用于唯一标识一个数据流转积压策略，在创建数据流转积压策略时由 物联网平台 分配获得。 policy_name String 参数说明：数据流转积压策略名称。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最小长度：1 最大长度：256 description String 参数说明：用户自定义的数据流转积压策略描述。 取值范围：长度不超过256，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最小长度：1 最大长度：256 backlog_size Integer 参数说明：数据积压大小。单位为B（字节），取值范围为0~1073741823的整数，默认为1073741823（即1GB）。当backlog_size为0时，表示不积压。若同时配置了backlog_size和backlog_time两个维度，则以最先达到阈值的维度为准。 最小值：0 最大值：1073741823 缺省值：1073741823 backlog_time Integer 参数说明：数据积压时间。单位为s（秒），取值范围为0~86399的整数，默认为86399（即1天）。当backlog_time为0时，表示不积压。若同时配置了backlog_size和backlog_time两个维度，则以最先达到阈值的维度为准。 最小值：0 最大值：86399 缺省值：86399

响应示例 状态码： 201 Created { "policy_id" : "adadd5cb-6383-4b5b-a65c-f8c92fdf3c34", "policy_name" : "policyName", "description" : "description", "backlog_size" : 1073741823, "backlog_time" : 86399 }

响应参数 状态码： 201 表6 响应Body参数 参数 参数类型 描述 message_id String 消息id，由用户生成（推荐使用UUID），同一个设备下唯一， 如果用户不填写，则由物联网平台生成。 result MessageResult object 消息下发结果。Json格式。 表7 MessageResult 参数 参数类型 描述 status String 消息状态, PENDING，DELIVERED，FAILED和TIMEOUT。如果设备不在线，则平台缓存消息，并且返回PENDING，等设备数据上报之后再下发；如果设备在线，则消息直接进行下发，下发成功后接口返回DELIVERED，失败返回FAILED；如果消息在平台默认时间内（1天）还没有下发给设备，则平台会将消息设置为超时，状态为TIMEOUT。另外应用可以订阅消息的执行结果，平台会将消息结果推送给订阅的应用。 created_time String 消息的创建时间，"yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串。 finished_time String 消息结束时间, "yyyyMMdd'T'HHmmss'Z'"格式的UTC字符串，包含消息转换到DELIVERED，FAILED和TIMEOUT状态的时间。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用 IAM 服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 message_id 否 String 参数说明：消息id，由用户生成（推荐使用UUID），同一个设备下唯一， 如果用户填写的id在设备下不唯一， 则接口返回错误。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 最大长度：128 name 否 String 参数说明：消息名称。 取值范围：长度不超过128，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。 最大长度：128 message 是 Object 参数说明：消息内容，支持string和json格式。 properties 否 PropertiesDTO object 参数说明：消息下行到设备的属性参数。 encoding 否 String 参数说明：消息内容编码格式。默认值none。 取值范围： none base64 缺省值：none payload_format 否 String 参数说明：有效负载格式，在消息内容编码格式为none时有效。默认值standard（平台封装的标准格式）。 取值范围： standard raw：直接将消息内容作为有效负载下发。 缺省值：standard topic 否 String 参数说明：消息下行到设备的自定义topic后缀, 可选， 仅适用于MQTT协议接入的设备。 用户只能填写在租户产品界面配置的topic, 否则会校验不通过。 平台给消息topic添加的前缀为$oc/devices/{device_id}/user/， 用户可以在前缀的基础上增加自定义部分， 如增加messageDown，则平台拼接前缀后完整的topic为 $oc/devices/{device_id}/user/messageDown，其中device_id以实际设备的网关id替代。 如果用户指定该topic，消息会通过该topic下行到设备，如果用户不指定， 则消息通过系统默认的topic下行到设备,系统默认的topic格式为： $oc/devices/{device_id}/sys/messages/down。此字段与topic_full_name字段只可填写一个。 最大长度：128 topic_full_name 否 String 参数说明：消息下行到设备的完整topic名称, 可选。用户需要下发用户自定义的topic给设备时，可以使用该参数指定完整的topic名称，物联网平台不校验该topic是否在平台定义，直接透传给设备。设备需要提前订阅该topic。此字段与topic字段只可填写一个。 最大长度：128 ttl 否 Integer 参数说明：下发消息在平台缓存的老化时间，时间单位是分钟，默认值1440；ttl参数数值必须是5的倍数，即以5分钟为粒度；指定为0时表示不缓存消息，默认最大缓存时间为1440分钟，缓存时间超过1440分钟需申请，否则下发失败。 最小值：0 最大值：10080 缺省值：1440 表4 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。 表5 UserPropDTO 参数 是否必选 参数类型 描述 prop_key 否 String 参数说明：用户自定义属性键。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 prop_value 否 String 参数说明：用户自定义属性值。 取值范围：长度不超过128，只允许中文、字母、数字、以及_? '#().,&%@!-等字符的组合。

响应示例 状态码： 201 Created { "message_id" : "b1224afb-e9f0-4916-8220-b6bab568e888", "result" : { "status" : "PENDING", "created_time" : "20151212T121212Z", "finished_time" : "20151212T121213Z" } }

请求示例 创建消息，通过平台默认topic下发。 POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/messages { "message_id" : "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name" : "messageName", "message" : "HelloWorld" } 创建消息，通过平台自定义topic下发。 POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/messages { "message_id" : "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name" : "messageName", "message" : "HelloWorld", "topic" : "testTopic" } 创建消息，通过自定义topic下发。 POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/messages { "message_id" : "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name" : "messageName", "message" : "HelloWorld", "topic_full_name" : "/test/customTopic/testTopic" }

功能介绍 物联网平台可向设备下发消息，应用服务器可调用此接口向指定设备下发消息，以实现对设备的控制。应用将消息下发给平台后，平台返回应用响应结果，平台再将消息发送给设备。平台返回应用响应结果不一定是设备接收结果，建议用户应用通过订阅设备消息状态变更通知，订阅后平台会将设备接收结果推送给订阅的应用。 注意： 此接口适用于MQTT设备消息下发，暂不支持其他协议接入的设备消息下发。 此接口仅支持单个设备消息下发，如需多个设备消息下发，请参见 创建批量任务。

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

响应示例 状态码： 200 OK { "authorizer_id" : "5c90fa7d3c4e4405e8525079", "authorizer_name" : "myTest", "func_name" : "mqtt_auth", "func_urn" : "urn:fss:cn-north-5:d92d9c5eb8e347b5bb31ecfe5bc0c4e1:function:default:mqtt_auth:latest", "signing_enable" : true, "signing_token" : "string", "signing_public_key" : "string", "default_authorizer" : false, "status" : "ACTIVE", "cache_enable" : false, "create_time" : "20231031T070547Z", "update_time" : "20231031T070547Z" }

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

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 authorizer_id String 参数说明：自定义鉴权ID。 authorizer_name String 参数说明：自定义鉴权器名称，同一租户下的自定义鉴权器名称不能重复。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 func_name String 参数说明：函数名称。 最小长度：0 最大长度：65535 func_urn String 参数说明：函数的URN（Uniform Resource Name），唯一标识函数，即自定义鉴权器对应的处理函数地址。 最小长度：0 最大长度：65535 signing_enable Boolean 参数说明：是否启动签名校验，启动签名校验后不满足签名要求的鉴权信息将被拒绝，以减少无效的函数调用。推荐用户进行安全的签名校验，默认开启。 缺省值：true signing_token String 参数说明：签名校验的Key值，开启签名校验时使用。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 signing_public_key String 参数说明：签名校验的公钥，开启签名校验时使用。用于认证设备携带的签名信息是否正确。 最小长度：0 最大长度：65535 default_authorizer Boolean 参数说明：是否为默认的鉴权方式，默认为false。 缺省值：false status String 参数说明：是否激活该鉴权方式 ACTIVE：该鉴权为激活状态。 INACTIVE：该鉴权为停用状态。 缺省值：INACTIVE cache_enable Boolean 参数说明：是否开启缓存，默认为false，设备为true时，当设备入参（username，clientId，password，以及证书信息，函数urn）不变时，当缓存结果存在时，将直接使用缓存结果，建议在调试时设置为false，生产时设置为true，避免频繁调用函数。 缺省值：false create_time String 在物联网平台进行自定义鉴权相关操作的时间。格式：yyyyMMdd'T'HHmmss'Z'，如：20151212T121212Z。 update_time String 在物联网平台更新自定义鉴权相关操作的时间。格式：yyyyMMdd'T'HHmmss'Z'，如：20151212T121212Z。

响应示例 状态码： 200 OK { "targets" : [ { "target_type" : "device", "target_id" : "64a7ba7ef9cb063d27e16b97_123456" } ], "page" : { "marker" : "5c90fa7d3c4e4405e8525079", "count" : 1 } }

响应参数 状态码： 200 表4 响应Body参数 参数 参数类型 描述 targets Array of PolicyTargetBase objects 策略绑定信息列表。 page Page object 查询结果的分页信息。 表5 PolicyTargetBase 参数 参数类型 描述 target_type String 参数说明：策略绑定的目标类型。 取值范围：device|product|app，device表示设备，product表示产品，app表示整个资源空间。 target_id String 策略绑定的目标ID 表6 Page 参数 参数类型 描述 count Long 满足查询条件的记录总数。 marker String 本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 target_type 否 String 参数说明：策略绑定的目标类型。 取值范围：device|product|app，device表示设备，product表示产品，app表示整个资源空间。 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

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

响应参数 状态码： 201 表4 响应Body参数 参数 参数类型 描述 authorizer_id String 参数说明：自定义鉴权ID。 authorizer_name String 参数说明：自定义鉴权器名称，同一租户下的自定义鉴权器名称不能重复。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 func_name String 参数说明：函数名称。 最小长度：0 最大长度：65535 func_urn String 参数说明：函数的URN（Uniform Resource Name），唯一标识函数，即自定义鉴权器对应的处理函数地址。 最小长度：0 最大长度：65535 signing_enable Boolean 参数说明：是否启动签名校验，启动签名校验后不满足签名要求的鉴权信息将被拒绝，以减少无效的函数调用。推荐用户进行安全的签名校验，默认开启。 缺省值：true signing_token String 参数说明：签名校验的Key值，开启签名校验时使用。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 signing_public_key String 参数说明：签名校验的公钥，开启签名校验时使用。用于认证设备携带的签名信息是否正确。 最小长度：0 最大长度：65535 default_authorizer Boolean 参数说明：是否为默认的鉴权方式，默认为false。 缺省值：false status String 参数说明：是否激活该鉴权方式 ACTIVE：该鉴权为激活状态。 INACTIVE：该鉴权为停用状态。 缺省值：INACTIVE cache_enable Boolean 参数说明：是否开启缓存，默认为false，设备为true时，当设备入参（username，clientId，password，以及证书信息，函数urn）不变时，当缓存结果存在时，将直接使用缓存结果，建议在调试时设置为false，生产时设置为true，避免频繁调用函数。 缺省值：false create_time String 在物联网平台进行自定义鉴权相关操作的时间。格式：yyyyMMdd'T'HHmmss'Z'，如：20151212T121212Z。 update_time String 在物联网平台更新自定义鉴权相关操作的时间。格式：yyyyMMdd'T'HHmmss'Z'，如：20151212T121212Z。

请求示例 创建自定义鉴权 POST https://{endpoint}/v5/iot/{project_id}/device-authorizers { "authorizer_name" : "myTest", "func_urn" : "urn:fss:cn-north-5:d92d9c5eb8e347b5bb31ecfe5bc0c4e1:function:default:mqtt_auth:latest", "signing_enable" : true, "signing_token" : "string", "signing_public_key" : "string", "default_authorizer" : false, "status" : "ACTIVE", "cache_enable" : true }

响应示例 状态码： 201 Created { "authorizer_id" : "5c90fa7d3c4e4405e8525079", "authorizer_name" : "myTest", "func_name" : "mqtt_auth", "func_urn" : "urn:fss:cn-north-5:d92d9c5eb8e347b5bb31ecfe5bc0c4e1:function:default:mqtt_auth:latest", "signing_enable" : true, "signing_token" : "string", "signing_public_key" : "string", "default_authorizer" : false, "status" : "ACTIVE", "cache_enable" : false, "create_time" : "20231031T070547Z", "update_time" : "20231031T070547Z" }

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 authorizer_name 是 String 参数说明：自定义鉴权器名称，同一租户下的自定义鉴权器名称不能重复。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 func_urn 是 String 参数说明：函数的URN（Uniform Resource Name），唯一标识函数，即自定义鉴权器对应的处理函数地址。 signing_enable 否 Boolean 参数说明：是否启动签名校验，启动签名校验后不满足签名要求的鉴权信息将被拒绝，以减少无效的函数调用。推荐用户进行安全的签名校验，默认开启， 开启时signing_token与signing_public_key必填。 缺省值：true signing_token 否 String 参数说明：签名校验的Key值，开启签名校验时使用。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 signing_public_key 否 String 参数说明：签名校验的公钥，开启签名校验时使用。用于认证设备携带的签名信息是否正确。 default_authorizer 否 Boolean 参数说明：当前自定义鉴权是否为默认的鉴权方式，默认为false，当设置为true时，用户所有支持SNI的设备，如果在鉴权时不指定使用特定的设备鉴权，将统一使用当前鉴权器策略进行鉴权。 缺省值：false status 否 String 参数说明：是否激活该鉴权方式 ACTIVE：该鉴权为激活状态。 INACTIVE：该鉴权为停用状态。 缺省值：INACTIVE cache_enable 否 Boolean 参数说明：是否开启缓存，默认为false，设备为true时，当设备入参（username，clientId，password，以及证书信息，函数urn）不变时，当缓存结果存在时，将直接使用缓存结果，建议在调试时设置为false，生产时设置为true，避免频繁调用函数。 缺省值：false

响应示例 状态码： 200 OK { "template_id" : "5c90fa7d3c4e4405e8525079", "template_name" : "myTemplate", "description" : "myTemplate", "template_body" : { "parameters" : { "iotda::certificate::country" : { "type" : "String" }, "iotda::certificate::organization" : { "type" : "String" }, "iotda::certificate::organizational_unit" : { "type" : "String" }, "iotda::certificate::distinguished_name_qualifier" : { "type" : "String" }, "iotda::certificate::state_name" : { "type" : "String" }, "iotda::certificate::common_name" : { "type" : "String" }, "iotda::certificate::serial_number" : { "type" : "String" } }, "resources" : { "device" : { "device_name" : { "ref" : "iotda::certificate::organization" }, "node_id" : { "ref" : "iotda::certificate::common_name" }, "product_id" : { "ref" : "iotda::certificate::organization" } }, "policy" : { "policy_ids" : [ "5c90fa7d3c4e4405e8525079" ] } } }, "create_time" : "20230810T070547Z", "update_time" : "20230810T070547Z" }

响应参数 状态码： 200 表3 响应Body参数 参数 参数类型 描述 template_id String 参数说明：预调配模板ID。 template_name String 参数说明：预调配模板名称。 取值范围：长度不超过128，只允许中文、字母、数字、下划线（_）、连接符（-）的组合。 description String 参数说明：预调配模板的描述信息。 取值范围：长度不超过2048，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合 最大长度：2048 template_body ProvisioningTemplateBody object 参数说明：预调配模板详细内容，json格式。 create_time String 在物联网平台创建预调配模板的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 update_time String 在物联网平台更新预调配模板的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 表4 ProvisioningTemplateBody 参数 参数类型 描述 parameters Object 参数说明：预调配模板参数， ，配置格式为{"parameter":{"type":"String"}} ，其中parameter目前支持从预调配设备的证书的使用者字段提取内容，证书必须包含模板中定义的所有参数值，华为云IoT平台定义了可在预调配模板中声明和引用的如下参数: iotda::certificate::country (国家/地区,C ) iotda::certificate::organization (组织,O) iotda::certificate::organizational_unit (组织单位,OU) iotda::certificate::distinguished_name_qualifier (可辨别名称限定符,dnQualifier) iotda::certificate::state_name (省市,ST) iotda::certificate::common_name (公用名,CN) iotda::certificate::serial_number (序列号,serialNumber) type描述parameter的类型，目前仅支持string。 配置样例： '{"iotda::certificate::country":{"type":"String"}, "iotda::certificate::organization":{"type":"String"}, "iotda::certificate::organizational_unit":{"type":"String"}, "iotda::certificate::distinguished_name_qualifier":{"type":"String"}, "iotda::certificate::state_name":{"type":"String"}, "iotda::certificate::common_name":{"type":"String"}, "iotda::certificate::serial_number":{"type":"String"}}' resources TemplateResource object 预调配模板设备资源结构体。 表5 TemplateResource 参数 参数类型 描述 device DeviceResource object 预调配模板设备资源详情结构体。 policy PolicyResource object 预调配模板设备策略资源详情结构体。 表6 DeviceResource 参数 参数类型 描述 device_name ParameterRef object 设备名称 node_id ParameterRef object 设备标识码 product_id Object 参数说明：设备所属的产品id，可以是一个明确的静态字符串id，也可以是动态的模板参数引用 明确的静态字符串："642bf260f2f9030e44210d8d"。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。" 参数引用: {"ref" : "iotda::certificate::country"} tags Array of TagRef objects 参数说明：设备绑定的标签列表 表7 ParameterRef 参数 参数类型 描述 ref String 参数引用名称 表8 TagRef 参数 参数类型 描述 tag_key Object 参数说明：标签键名称，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagKey"。取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合 参数引用: {"ref" : "iotda::certificate::country"} tag_value Object 参数说明：标签值，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagValue"。取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。 参数引用: {"ref" : "iotda::certificate::country"} 表9 PolicyResource 参数 参数类型 描述 policy_ids Array of strings 参数说明：设备需要绑定的策略id列表

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

响应参数 状态码： 200 表5 响应Body参数 参数 参数类型 描述 app_id String 参数说明：资源空间ID。 policy_id String 策略ID。 policy_name String 策略名称。 statement Array of Statement objects 策略文档。 create_time String 在物联网平台创建策略的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 update_time String 在物联网平台更新策略的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 表6 Statement 参数 参数类型 描述 effect String 指定是允许还是拒绝该操作。既有允许（ALLOW）又有拒绝（DENY）的授权语句时，遵循拒绝（DENY）优先的原则。 ALLOW：允许。 DENY：拒绝。 actions Array of strings 用于指定策略允许或拒绝的操作。格式为：服务名:资源:操作。当前支持的操作类型如下： iotda:devices:publish：设备使用MQTT协议发布消息。 iotda:devices:subscribe：设备使用MQTT协议订阅消息。 resources Array of strings 用于指定允许或拒绝对其执行操作的资源。格式为：资源类型:资源名称。如设备订阅的资源为：topic:/v1/${devices.deviceId}/test/hello。 取值范围：资源列表长度最小为1，最大为10，列表中的资源取值范围：仅支持字母，数字，以及/{}$=+#?*:._-组合。

响应示例 状态码： 200 OK { "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "policy_id" : "5c90fa7d3c4e4405e8525079", "policy_name" : "testPolicy", "statement" : [ { "effect" : "ALLOW", "actions" : [ "iotda:devices:publish", "iotda:devices:subscribe" ], "resources" : [ "topic:/v1/${devices.deviceId}/test/hello", "topic:/v1/${devices.productId}/test/hello" ] } ], "create_time" : "20230810T070547Z", "update_time" : "20230810T070547Z" }

请求示例 更新设备策略 PUT https://{endpoint}/v5/iot/{project_id}/device-policies/{policy_id} { "policy_name" : "testPolicy", "statement" : [ { "effect" : "ALLOW", "actions" : [ "iotda:devices:publish", "iotda:devices:subscribe" ], "resources" : [ "topic:/v1/${devices.deviceId}/test/hello", "topic:/v1/${devices.productId}/test/hello" ] } ] }

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 policy_name 否 String 参数说明：策略名称。 取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 statement 否 Array of Statement objects 参数说明：策略文档。 表4 Statement 参数 是否必选 参数类型 描述 effect 是 String 指定是允许还是拒绝该操作。既有允许（ALLOW）又有拒绝（DENY）的授权语句时，遵循拒绝（DENY）优先的原则。 ALLOW：允许。 DENY：拒绝。 actions 是 Array of strings 用于指定策略允许或拒绝的操作。格式为：服务名:资源:操作。当前支持的操作类型如下： iotda:devices:publish：设备使用MQTT协议发布消息。 iotda:devices:subscribe：设备使用MQTT协议订阅消息。 resources 是 Array of strings 用于指定允许或拒绝对其执行操作的资源。格式为：资源类型:资源名称。如设备订阅的资源为：topic:/v1/${devices.deviceId}/test/hello。 取值范围：资源列表长度最小为1，最大为10，列表中的资源取值范围：仅支持字母，数字，以及/{}$=+#?*:._-组合。

响应示例 状态码： 200 OK { "template_id" : "5c90fa7d3c4e4405e8525079", "template_name" : "myTemplate", "description" : "myTemplate", "template_body" : { "parameters" : { "iotda::certificate::country" : { "type" : "String" }, "iotda::certificate::organization" : { "type" : "String" }, "iotda::certificate::organizational_unit" : { "type" : "String" }, "iotda::certificate::distinguished_name_qualifier" : { "type" : "String" }, "iotda::certificate::state_name" : { "type" : "String" }, "iotda::certificate::common_name" : { "type" : "String" }, "iotda::certificate::serial_number" : { "type" : "String" } }, "resources" : { "device" : { "device_name" : { "ref" : "iotda::certificate::organization" }, "node_id" : { "ref" : "iotda::certificate::common_name" }, "product_id" : { "ref" : "iotda::certificate::organization" } }, "policy" : { "policy_ids" : [ "5c90fa7d3c4e4405e8525079" ] } } }, "create_time" : "20230810T070547Z", "update_time" : "20230810T070547Z" }

请求示例 更新预调配模板 PUT https://{endpoint}/v5/iot/{project_id}/provisioning-templates/{template_id} { "description" : "myTemplate", "template_body" : { "parameters" : { "iotda::certificate::country" : { "type" : "String" }, "iotda::certificate::organization" : { "type" : "String" }, "iotda::certificate::organizational_unit" : { "type" : "String" }, "iotda::certificate::distinguished_name_qualifier" : { "type" : "String" }, "iotda::certificate::state_name" : { "type" : "String" }, "iotda::certificate::common_name" : { "type" : "String" }, "iotda::certificate::serial_number" : { "type" : "String" } }, "resources" : { "device" : { "device_name" : { "ref" : "iotda::certificate::organization" }, "node_id" : { "ref" : "iotda::certificate::common_name" }, "product_id" : { "ref" : "iotda::certificate::organization" }, "tags" : [ { "tag_key" : { "ref" : "iotda::certificate::organization" }, "tag_value" : { "ref" : "iotda::certificate::organizational_unit" } } ] }, "policy" : { "policy_ids" : [ "5c90fa7d3c4e4405e8525079" ] } } } } 更新预调配模板-部分参数自定义 PUT https://{endpoint}/v5/iot/{project_id}/provisioning-templates/{template_id} { "description" : "myTemplate2", "template_body" : { "parameters" : { "iotda::certificate::country" : { "type" : "String" }, "iotda::certificate::organization" : { "type" : "String" }, "iotda::certificate::organizational_unit" : { "type" : "String" }, "iotda::certificate::distinguished_name_qualifier" : { "type" : "String" }, "iotda::certificate::state_name" : { "type" : "String" }, "iotda::certificate::common_name" : { "type" : "String" }, "iotda::certificate::serial_number" : { "type" : "String" } }, "resources" : { "device" : { "device_name" : { "ref" : "iotda::certificate::organization" }, "node_id" : { "ref" : "iotda::certificate::common_name" }, "product_id" : "642bf260f2f9030e44210d8d", "tags" : [ { "tag_key" : "myTagKey", "tag_value" : "myTagValue" } ] }, "policy" : { "policy_ids" : [ "5c90fa7d3c4e4405e8525079" ] } } } }

响应参数 状态码： 200 表10 响应Body参数 参数 参数类型 描述 template_id String 参数说明：预调配模板ID。 template_name String 参数说明：预调配模板名称。 取值范围：长度不超过128，只允许中文、字母、数字、下划线（_）、连接符（-）的组合。 description String 参数说明：预调配模板的描述信息。 取值范围：长度不超过2048，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合 最大长度：2048 template_body ProvisioningTemplateBody object 参数说明：预调配模板详细内容，json格式。 create_time String 在物联网平台创建预调配模板的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 update_time String 在物联网平台更新预调配模板的时间。格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。 表11 ProvisioningTemplateBody 参数 参数类型 描述 parameters Object 参数说明：预调配模板参数， ，配置格式为{"parameter":{"type":"String"}} ，其中parameter目前支持从预调配设备的证书的使用者字段提取内容，证书必须包含模板中定义的所有参数值，华为云IoT平台定义了可在预调配模板中声明和引用的如下参数: iotda::certificate::country (国家/地区,C ) iotda::certificate::organization (组织,O) iotda::certificate::organizational_unit (组织单位,OU) iotda::certificate::distinguished_name_qualifier (可辨别名称限定符,dnQualifier) iotda::certificate::state_name (省市,ST) iotda::certificate::common_name (公用名,CN) iotda::certificate::serial_number (序列号,serialNumber) type描述parameter的类型，目前仅支持string。 配置样例： '{"iotda::certificate::country":{"type":"String"}, "iotda::certificate::organization":{"type":"String"}, "iotda::certificate::organizational_unit":{"type":"String"}, "iotda::certificate::distinguished_name_qualifier":{"type":"String"}, "iotda::certificate::state_name":{"type":"String"}, "iotda::certificate::common_name":{"type":"String"}, "iotda::certificate::serial_number":{"type":"String"}}' resources TemplateResource object 预调配模板设备资源结构体。 表12 TemplateResource 参数 参数类型 描述 device DeviceResource object 预调配模板设备资源详情结构体。 policy PolicyResource object 预调配模板设备策略资源详情结构体。 表13 DeviceResource 参数 参数类型 描述 device_name ParameterRef object 设备名称 node_id ParameterRef object 设备标识码 product_id Object 参数说明：设备所属的产品id，可以是一个明确的静态字符串id，也可以是动态的模板参数引用 明确的静态字符串："642bf260f2f9030e44210d8d"。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。" 参数引用: {"ref" : "iotda::certificate::country"} tags Array of TagRef objects 参数说明：设备绑定的标签列表 表14 ParameterRef 参数 参数类型 描述 ref String 参数引用名称 表15 TagRef 参数 参数类型 描述 tag_key Object 参数说明：标签键名称，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagKey"。取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合 参数引用: {"ref" : "iotda::certificate::country"} tag_value Object 参数说明：标签值，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagValue"。取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。 参数引用: {"ref" : "iotda::certificate::country"} 表16 PolicyResource 参数 参数类型 描述 policy_ids Array of strings 参数说明：设备需要绑定的策略id列表

请求参数 表2 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 否 String 参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。 Instance-Id 否 String 参数说明：实例ID。物理多租下各实例的唯一标识，建议携带该参数，在使用专业版时必须携带该参数。您可以在IoTDA管理控制台界面，选择左侧导航栏“总览”页签查看当前实例的ID，具体获取方式请参考查看实例详情 。 表3 请求Body参数 参数 是否必选 参数类型 描述 description 否 String 参数说明：预调配模板的描述信息。 取值范围：长度不超过2048，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合 最大长度：2048 template_body 否 ProvisioningTemplateBody object 参数说明：预调配模板详细内容，json格式。 表4 ProvisioningTemplateBody 参数 是否必选 参数类型 描述 parameters 是 Object 参数说明：预调配模板参数， ，配置格式为{"parameter":{"type":"String"}} ，其中parameter目前支持从预调配设备的证书的使用者字段提取内容，证书必须包含模板中定义的所有参数值，华为云IoT平台定义了可在预调配模板中声明和引用的如下参数: iotda::certificate::country (国家/地区,C ) iotda::certificate::organization (组织,O) iotda::certificate::organizational_unit (组织单位,OU) iotda::certificate::distinguished_name_qualifier (可辨别名称限定符,dnQualifier) iotda::certificate::state_name (省市,ST) iotda::certificate::common_name (公用名,CN) iotda::certificate::serial_number (序列号,serialNumber) type描述parameter的类型，目前仅支持string。 配置样例： '{"iotda::certificate::country":{"type":"String"}, "iotda::certificate::organization":{"type":"String"}, "iotda::certificate::organizational_unit":{"type":"String"}, "iotda::certificate::distinguished_name_qualifier":{"type":"String"}, "iotda::certificate::state_name":{"type":"String"}, "iotda::certificate::common_name":{"type":"String"}, "iotda::certificate::serial_number":{"type":"String"}}' resources 是 TemplateResource object 预调配模板设备资源结构体。 表5 TemplateResource 参数 是否必选 参数类型 描述 device 是 DeviceResource object 预调配模板设备资源详情结构体。 policy 否 PolicyResource object 预调配模板设备策略资源详情结构体。 表6 DeviceResource 参数 是否必选 参数类型 描述 device_name 否 ParameterRef object 设备名称 node_id 是 ParameterRef object 设备标识码 product_id 是 Object 参数说明：设备所属的产品id，可以是一个明确的静态字符串id，也可以是动态的模板参数引用 明确的静态字符串："642bf260f2f9030e44210d8d"。取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。" 参数引用: {"ref" : "iotda::certificate::country"} tags 否 Array of TagRef objects 参数说明：设备绑定的标签列表 表7 ParameterRef 参数 是否必选 参数类型 描述 ref 是 String 参数引用名称 表8 TagRef 参数 是否必选 参数类型 描述 tag_key 否 Object 参数说明：标签键名称，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagKey"。取值范围：长度不超过64，只允许中文、字母、数字、以及_.-等字符的组合 参数引用: {"ref" : "iotda::certificate::country"} tag_value 否 Object 参数说明：标签值，可以是一个明确的静态字符串，也可以是动态的模板参数引用 明确的静态字符串："myTagValue"。取值范围：长度不超过128，只允许中文、字母、数字、以及_.-等字符的组合。 参数引用: {"ref" : "iotda::certificate::country"} 表9 PolicyResource 参数 是否必选 参数类型 描述 policy_ids 否 Array of strings 参数说明：设备需要绑定的策略id列表