华为云用户手册

功能介绍 物联网平台 可向设备下发消息，应用服务器可调用此接口向指定设备下发消息，以实现对设备的控制。应用将消息下发给平台后，平台返回应用响应结果，平台再将消息发送给设备。平台返回应用响应结果不一定是设备接收结果，建议用户应用通过订阅设备消息状态变更通知，订阅后平台会将设备接收结果推送给订阅的应用。 注意： 此接口适用于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 } }

请求参数 表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

响应参数 状态码： 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，具体获取方式请参考查看实例详情 。

请求示例 创建自定义鉴权 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" }

响应参数 状态码： 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。

请求参数 表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，具体获取方式请参考查看实例详情 。

请求示例 更新设备策略 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" ] } ] }

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

请求参数 表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，列表中的资源取值范围：仅支持字母，数字，以及/{}$=+#?*:._-组合。

请求示例 更新预调配模板 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 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 表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列表

请求示例 创建设备策略-允许设备订阅与发布指定topic POST https://{endpoint}/v5/iot/{project_id}/device-policies { "policy_name" : "myPolicyAllow", "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "statement" : [ { "effect" : "ALLOW", "actions" : [ "iotda:devices:publish\niotda:devices:subscribe" ], "resources" : [ "topic:/v1/${devices.deviceId}/test/allow" ] } ] } 创建设备策略-不允许设备订阅与发布指定topic POST https://{endpoint}/v5/iot/{project_id}/device-policies { "policy_name" : "myPolicyDeny", "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "statement" : [ { "effect" : "DENY", "actions" : [ "iotda:devices:publish\niotda:devices:subscribe" ], "resources" : [ "topic:/v1/${devices.deviceId}/test/deny" ] } ] }

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

请求参数 表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，只允许字母、数字、下划线（_）、连接符（-）的组合。 app_id 否 String 参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的设备归属到哪个资源空间下，否则创建的设备将会归属到默认资源空间下。 取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。 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，列表中的资源取值范围：仅支持字母，数字，以及/{}$=+#?*:._-组合。

响应参数 状态码： 201 表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，列表中的资源取值范围：仅支持字母，数字，以及/{}$=+#?*:._-组合。

请求示例 创建预调配模板-参数引用 POST https://{endpoint}/v5/iot/{project_id}/provisioning-templates { "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" }, "tags" : [ { "tag_key" : { "ref" : "iotda::certificate::organization" }, "tag_value" : { "ref" : "iotda::certificate::organizational_unit" } } ] }, "policy" : { "policy_ids" : [ "5c90fa7d3c4e4405e8525079" ] } } } } 创建预调配模板-部分参数自定义 POST https://{endpoint}/v5/iot/{project_id}/provisioning-templates { "template_name" : "myTemplate2", "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" ] } } } }

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