Updated on 2024-06-27 GMT+08:00

Create a Pre-provisioning Template

Function

This API is used by an application to create a pre-provisioning template on the IoT platform. For a device not registered, you can use a pre-provisioning template to automatically register the device information on the IoT platform when the device connects to the platform for the first time.

  • A pre-provisioning template takes effect only after it is bound to at least one device CA certificate.

  • An instance can have a maximum of 10 pre-provisioning templates.

  • This API is supported only by standard and enterprise editions.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Parameter description: project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

Parameter description: user token. Obtain the token by calling the IAM API for obtaining a user token through password authentication. In the returned response header, X-Subject-Token is the desired user token. For details about how to obtain the token, see Token Authentication.

Instance-Id

No

String

Parameter description: instance ID. Unique identifier of each instance in the physical multi-tenant scenario. Mandatory for professional editions and recommended in other cases. Log in to the IoTDA console and choose Overview in the navigation pane to view the instance ID. For details, see Viewing Instance Details.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

template_name

Yes

String

Parameter description: name of the pre-provisioning template. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

description

No

String

Parameter description: description of the pre-provisioning template. Value: The value can contain a maximum of 2,048 characters. Only letters, digits, and special characters (_?'#().,&%@!-) are allowed.

Maximum: 2048

template_body

Yes

ProvisioningTemplateBody object

Parameter description: detailed content of the pre-provisioning template in JSON format.

Table 4 ProvisioningTemplateBody

Parameter

Mandatory

Type

Description

parameters

Yes

Object

Parameter description: pre-provisioning template parameters, which can be extracted from the user fields of pre-provisioning device certificates. The configuration format is {"parameter":{"type":"String"}}. Huawei Cloud IoT platform defines the parameters that can be declared and referenced in pre-provisioning templates. A device certificate must contain the parameters referenced in the template.

  • iotda::certificate::country: country/region, C

  • iotda::certificate::organization: organization, O

  • iotda::certificate::organizational_unit: organizational unit, OU

  • iotda::certificate::distinguished_name_qualifier: distinguishable name qualifier, dnQualifier

  • iotda::certificate::state_name: province, ST

  • iotda::certificate::common_name: common name, CN

  • iotda::certificate::serial_number: serial number, serialNumber

type indicates the parameter type. Currently, only String is supported.

Configuration example:

'{"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

Yes

TemplateResource object

Structure of device resources of a pre-provisioning template.

Table 5 TemplateResource

Parameter

Mandatory

Type

Description

device

Yes

DeviceResource object

Structure of device resource details of a pre-provisioning template.

policy

No

PolicyResource object

Structure of device policy resource details of a pre-provisioning template.

Table 6 DeviceResource

Parameter

Mandatory

Type

Description

device_name

No

ParameterRef object

Device name.

node_id

Yes

ParameterRef object

Node ID.

product_id

Yes

Object

Parameter description: ID of the product to which the device belongs. The value can be a static string ID or dynamic parameters referenced from the template.

  • Static string: 642bf260f2f9030e44210d8d. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. "

  • Parameter reference: {"ref": "iotda::certificate::country"}

tags

No

Array of TagRef objects

Parameter description: list of tags bound to a device.

Table 7 ParameterRef

Parameter

Mandatory

Type

Description

ref

Yes

String

Parameter reference name.

Table 8 TagRef

Parameter

Mandatory

Type

Description

tag_key

No

Object

Parameter description: tag key name. The value can be a static string or dynamic parameters referenced from the template.

  • Static string: myTagKey. Value: The value can contain a maximum of 64 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.

  • Parameter reference: {"ref": "iotda::certificate::country"}

tag_value

No

Object

Parameter description: tag value. The value can be a static string or dynamic parameters referenced from the template.

  • Static string: "myTagValue". Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.

  • Parameter reference: {"ref": "iotda::certificate::country"}

Table 9 PolicyResource

Parameter

Mandatory

Type

Description

policy_ids

No

Array of strings

Parameter description: ID list of policies to be bound to a device.

Response Parameters

Status code: 201

Table 10 Response body parameters

Parameter

Type

Description

template_id

String

Parameter description: ID of the pre-provisioning template.

template_name

String

Parameter description: name of the pre-provisioning template. Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

description

String

Parameter description: description of the pre-provisioning template. Value: The value can contain a maximum of 2,048 characters. Only letters, digits, and special characters (_?'#().,&%@!-) are allowed.

Maximum: 2048

template_body

ProvisioningTemplateBody object

Parameter description: detailed content of the pre-provisioning template in JSON format.

create_time

String

Time when a pre-provisioning template is created on the IoT platform. The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z.

update_time

String

Time when the pre-provisioning template is updated in the IoT platform. The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z.

Table 11 ProvisioningTemplateBody

Parameter

Type

Description

parameters

Object

Parameter description: pre-provisioning template parameters, which can be extracted from the user fields of pre-provisioning device certificates. The configuration format is {"parameter":{"type":"String"}}. Huawei Cloud IoT platform defines the parameters that can be declared and referenced in pre-provisioning templates. A device certificate must contain the parameters referenced in the template.

  • iotda::certificate::country: country/region, C

  • iotda::certificate::organization: organization, O

  • iotda::certificate::organizational_unit: organizational unit, OU

  • iotda::certificate::distinguished_name_qualifier: distinguishable name qualifier, dnQualifier

  • iotda::certificate::state_name: province, ST

  • iotda::certificate::common_name: common name, CN

  • iotda::certificate::serial_number: serial number, serialNumber

type indicates the parameter type. Currently, only String is supported.

Configuration example:

'{"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

Structure of device resources of a pre-provisioning template.

Table 12 TemplateResource

Parameter

Type

Description

device

DeviceResource object

Structure of device resource details of a pre-provisioning template.

policy

PolicyResource object

Structure of device policy resource details of a pre-provisioning template.

Table 13 DeviceResource

Parameter

Type

Description

device_name

ParameterRef object

Device name.

node_id

ParameterRef object

Node ID.

product_id

Object

Parameter description: ID of the product to which the device belongs. The value can be a static string ID or dynamic parameters referenced from the template.

  • Static string: 642bf260f2f9030e44210d8d. Value: The value can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. "

  • Parameter reference: {"ref": "iotda::certificate::country"}

tags

Array of TagRef objects

Parameter description: list of tags bound to a device.

Table 14 ParameterRef

Parameter

Type

Description

ref

String

Parameter reference name.

Table 15 TagRef

Parameter

Type

Description

tag_key

Object

Parameter description: tag key name. The value can be a static string or dynamic parameters referenced from the template.

  • Static string: myTagKey. Value: The value can contain a maximum of 64 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.

  • Parameter reference: {"ref": "iotda::certificate::country"}

tag_value

Object

Parameter description: tag value. The value can be a static string or dynamic parameters referenced from the template.

  • Static string: "myTagValue". Value: The value can contain a maximum of 128 characters. Only letters, digits, underscores (_), periods (.), and hyphens (-) are allowed.

  • Parameter reference: {"ref": "iotda::certificate::country"}

Table 16 PolicyResource

Parameter

Type

Description

policy_ids

Array of strings

Parameter description: ID list of policies to be bound to a device.

Example Requests

  • Creates a pre-provisioning template with parameter reference.

    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" ]
          }
        }
      }
    }
  • Creates a pre-provisioning template some custom parameters.

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

Example Responses

Status code: 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"
}

Status Codes

Status Code

Description

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

Error Codes

See Error Codes.