文档首页> 设备接入 IoTDA> API参考> 应用侧API参考> API> 预调配模板管理> 创建预调配模板

更新时间：2024-06-27 GMT+08:00

查看PDF

创建预调配模板

功能介绍

应用服务器可调用此接口在物联网平台创建一个预调配模板。用户的设备未在平台注册时，可以通过预调配模板在设备首次接入物联网平台时将设备信息自动注册到物联网平台。

该预调配模板至少需要绑定到一个设备CA证书下才能生效。
一个实例最多可有10个预调配模板。
仅标准版实例、企业版实例支持该接口调用，基础版不支持。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

POST /v5/iot/{project_id}/provisioning-templates

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数说明：项目ID。获取方法请参见获取项目ID。

请求参数

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

表3 请求Body参数
参数	是否必选	参数类型	描述
template_name	是	String	参数说明：预调配模板名称。取值范围：长度不超过128，只允许中文、字母、数字、下划线（_）、连接符（-）的组合。
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列表

响应参数

状态码： 201

**表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列表

请求示例

创建预调配模板-参数引用

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"
}

状态码

状态码	描述
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
500	Internal Server Error

错误码

请参见错误码。

父主题： 预调配模板管理

上一篇：预调配模板管理

下一篇：查询预调配模板列表

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消