本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 预置模板
<a name="provision-template"></a>

配置模板是一个 JSON 文档，它使用参数来描述您的设备必须使用哪些资源才能与之交互 AWS IoT。预调配模板包含两个部分：`Parameters` 和 `Resources`。中有两种类型的配置模板 AWS IoT。一个用于 just-in-time配置 (JITP) 和批量注册，第二个用于队列配置。

**Topics**
+ [参数部分](#parameters-section)
+ [资源部分](#resources-section)
+ [批量注册的模板示例](#bulk-template-example)
+ [just-in-time置备模板示例 (JITP)](#JITP-template-example)
+ [实例集预置](#fleet-provision-template)

## 参数部分
<a name="parameters-section"></a>

`Parameters` 部分声明在 `Resources` 部分中使用的参数。每个参数声明一个名称、一个类型以及一个可选的默认值。在随模板传入的字典不包含参数的值时，会使用默认值。模板文档的 `Parameters` 部分类似于以下所示：

```
{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber" : {
            "Type" : "String"
        },
        "Location" : {
            "Type" : "String",
            "Default" : "WA"
        },
        "CSR" : {
            "Type" : "String"    
        }
    }
}
```

此模板正文片段声明四个参数：`ThingName`、`SerialNumber`、`Location` 和 `CSR`。所有这些参数均为 `String` 类型。`Location` 参数声明了默认值 `"WA"`。

## 资源部分
<a name="resources-section"></a>

模板正`Resources`文的部分声明了您的设备与之通信所需的资源 AWS IoT：事物、证书以及一个或多个 IoT 策略。每个资源指定一个逻辑名称、一个类型和一组属性。

您可以使用逻辑名称在模板的其它位置引用资源。

类型指定您所声明的资源的种类。有效类型为：
+ `AWS::IoT::Thing`
+ `AWS::IoT::Certificate`
+ `AWS::IoT::Policy`

您指定的属性取决于所声明的资源的类型。

### 事物资源
<a name="thing-resources"></a>

事物资源使用以下属性进行声明：
+ `ThingName`: 字符串。
+ `AttributePayload`: 可选。名称-值对的列表。
+ `ThingTypeName`: 可选。用于事物的关联事物类型的字符串。
+ `ThingGroups`: 可选。事物所属的组的列表。
+ `BillingGroup`: 可选。关联账单组名称的字符串。
+ `PackageVersions`: 可选。关联软件包名称和版本名称的字符串。

### 证书资源
<a name="certificate-resources"></a>

您可以通过以下方式之一指定证书：
+ 证书签名请求（CSR）。
+ 现有设备证书的证书 ID。（只有证书 IDs 可以与队列配置模板一起使用。）
+ 使用注册到 AWS IoT的 CA 证书创建的设备证书。如果您有多个 CA 证书注册到同一使用者字段，则还必须传入用于对设备证书进行签名的 CA 证书。

**注意**  
当您在模板中声明证书时，请只使用这些方法之一。例如，如果您使用了 CSR，就不能同时指定证书 ID 或设备证书。有关更多信息，请参阅 [X.509 客户端证书](x509-client-certs.md)。

有关更多信息，请参阅 [X.509 证书概览](authentication.md#x509-certificate-overview)。

证书资源使用以下属性进行声明：
+ `CertificateSigningRequest`: 字符串。
+ `CertificateId`: 字符串。
+ `CertificatePem`: 字符串。
+ `CACertificatePem`: 字符串。
+ `Status`: 可选。字符串可以是 `ACTIVE` 或 `INACTIVE`。默认值为 ACTIVE。
+ `ThingPrincipalType`: 可选。指定事物与主体（证书）之间关系类型的字符串。
  + `EXCLUSIVE_THING`：建立独占关系。该主体只能附加到此特定事物，不能附加到其他事物。
  + `NON_EXCLUSIVE_THING`：将指定主体附加到事物。您可以将多个事物附加到该主体。如果未指定，这是默认值。
**注意**  
您也可以在没有设备证书的情况下配置设备。有关更多信息，请参阅 [使用实例集预调配来预调配没有设备证书的设备](provision-wo-cert.md)。

示例：
+ 使用 CSR 指定的证书：

  ```
  {
      "certificate" : {
          "Type" : "AWS::IoT::Certificate",
          "Properties" : {
              "CertificateSigningRequest": {"Ref" : "CSR"},
              "Status" : "ACTIVE"      
          }
      }
  }
  ```
+ 使用现有证书 ID 指定的证书：

  ```
  {
      "certificate" : {
          "Type" : "AWS::IoT::Certificate",
          "Properties" : {
              "CertificateId": {"Ref" : "CertificateId"}
          }
      }
  }
  ```
+ 使用现有证书 .pem 和 CA 证书 .pem 指定的证书：

  ```
  {
      "certificate" : {
          "Type" : "AWS::IoT::Certificate",
          "Properties" : {
              "CACertificatePem": {"Ref" : "CACertificatePem"},
              "CertificatePem": {"Ref" : "CertificatePem"}
          }
      }
  }
  ```
+ 独占地将一个事物附加到主体：

  ```
  {
      "certificate" : {
          "Type" : "AWS::IoT::Certificate",
          "Properties" : {
              "ThingPrincipalType" : "EXCLUSIVE_THING"
          }
      }
  }
  ```

### 策略资源
<a name="policy-resources"></a>

策略资源使用以下属性之一进行声明：
+ `PolicyName`: 可选。字符串。默认值为策略文档的哈希值。`PolicyName` 只能参考 AWS IoT 策略但不是 IAM 策略。如果您使用现有的 AWS IoT 策略，则对于 `PolicyName` 属性，输入策略的名称。请勿包含 `PolicyDocument` 属性。
+ `PolicyDocument`: 可选。指定为转义字符串的 JSON 对象。如果未提供 `PolicyDocument`，则必须已经创建了策略。

**注意**  
如果存在 `Policy` 部分，则必须指定 `PolicyName` 或 `PolicyDocument`，但不能同时指定。

### 覆盖设置
<a name="override-settings"></a>

如果模板指定了已经存在的资源，则使用 `OverrideSettings` 部分可以指定要采取的操作：

`DO_NOTHING`  
将资源保留为原样。

`REPLACE`  
使用在模板中指定的资源替换该资源。

`FAIL`  
导致请求失败，出现 `ResourceConflictsException`。

`MERGE`  
仅对 `ThingGroups` 的 `AttributePayload` 和 `thing` 属性有效。将事物的现有属性或组成员资格与模板中指定的同等内容合并。

当您声明事物资源时，您可以为以下属性指定 `OverrideSettings`：
+ `ATTRIBUTE_PAYLOAD`
+ `THING_TYPE_NAME`
+ `THING_GROUPS`

当您声明证书资源时，您可以为 `OverrideSettings` 属性指定 `Status`。

`OverrideSettings` 不可用于策略资源。

### 资源示例
<a name="resource-example"></a>

以下模板片段声明了一个事物、一个证书和一个策略：

```
{ 
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "ThingName" : {"Ref" : "ThingName"},
                "AttributePayload" : { "version" : "v1", "serialNumber" :  {"Ref" : "SerialNumber"}}, 
                "ThingTypeName" :  "lightBulb-versionA",
                "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}]
            },
            "OverrideSettings" : {
                "AttributePayload" : "MERGE",
                "ThingTypeName" : "REPLACE",
                "ThingGroups" : "DO_NOTHING"
            }
        },  
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateSigningRequest": {"Ref" : "CSR"},
                "Status" : "ACTIVE"      
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : "{ \"Version\": \"2012-10-17\",		 	 	  \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
            }
        }
    }
}
```

使用以下项声明事物：
+ 逻辑名称 `"thing"`。
+ 类型 `AWS::IoT::Thing`。
+  一组事物属性。

  事物属性包括事物名称、一组属性、一个事物类型名称（可选）以及事物所属的事物组列表（可选）。

使用 `{"Ref":"parameter-name"}` 引用参数。评估模板时，使用随模板传入的字典中提供的参数值来替换参数。

使用以下项声明证书：
+ 逻辑名称 `"certificate"`。
+ 类型 `AWS::IoT::Certificate`。
+ 一组属性。

  属性包括证书的 CSR 并将状态设置为 `ACTIVE`。CSR 文本作为随模板传入的字典中的参数传递。

使用以下项声明策略：
+ 逻辑名称 `"policy"`。
+ 类型 `AWS::IoT::Policy`。
+ 现有策略的名称或策略文档的名称。

## 批量注册的模板示例
<a name="bulk-template-example"></a>

以下 JSON 文件是使用 CSR 指定证书的完整预调配模板的一个示例：

（`PolicyDocument` 字段值必须是指定为转义字符串的 JSON 对象。）

```
{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber" : {
            "Type" : "String"
        },
        "Location" : {
            "Type" : "String",
            "Default" : "WA"
        },
        "CSR" : {
            "Type" : "String"    
        }
    },
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "ThingName" : {"Ref" : "ThingName"},
                "AttributePayload" : { "version" : "v1", "serialNumber" :  {"Ref" : "SerialNumber"}}, 
                "ThingTypeName" :  "lightBulb-versionA",
                "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}]
            }
        },
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateSigningRequest": {"Ref" : "CSR"},
                "Status" : "ACTIVE",
                "ThingPrincipalType" : "EXCLUSIVE_THING"
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : "{ \"Version\": \"2012-10-17\",		 	 	  \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
            }
        }
    }
}
```

## just-in-time置备模板示例 (JITP)
<a name="JITP-template-example"></a>

以下 JSON 文件是使用证书 ID 指定现有证书的完整预调配模板的一个示例：

```
{
   "Parameters":{
      "AWS::IoT::Certificate::CommonName":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::SerialNumber":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::Country":{
         "Type":"String"
      },
      "AWS::IoT::Certificate::Id":{
         "Type":"String"
      }
   },
   "Resources":{
      "thing":{
         "Type":"AWS::IoT::Thing",
         "Properties":{
            "ThingName":{
               "Ref":"AWS::IoT::Certificate::CommonName"
            },
            "AttributePayload":{
               "version":"v1",
               "serialNumber":{
                  "Ref":"AWS::IoT::Certificate::SerialNumber"
               }
            },
            "ThingTypeName":"lightBulb-versionA",
            "ThingGroups":[
               "v1-lightbulbs",
               {
                  "Ref":"AWS::IoT::Certificate::Country"
               }
            ]
         },
         "OverrideSettings":{
            "AttributePayload":"MERGE",
            "ThingTypeName":"REPLACE",
            "ThingGroups":"DO_NOTHING"
         }
      },
      "certificate":{
         "Type":"AWS::IoT::Certificate",
         "Properties":{
            "CertificateId":{
               "Ref":"AWS::IoT::Certificate::Id"
            },
            "Status":"ACTIVE",
            "ThingPrincipalType" : "EXCLUSIVE_THING"
         }
      },
      "policy":{
         "Type":"AWS::IoT::Policy",
         "Properties":{
            "PolicyDocument":"{ \"Version\": \"2012-10-17\",		 	 	  \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }"
         }
      }
   }
}
```

**重要**  
您必须在用于 JIT 预调配的模板中使用 `CertificateId`。

有关配置模板类型的更多信息，请参阅 AWS API 参考[https://docs.aws.amazon.com/iot/latest/apireference/API_CreateProvisioningTemplate.html#iot-CreateProvisioningTemplate-request-type](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateProvisioningTemplate.html#iot-CreateProvisioningTemplate-request-type)中的。

有关如何使用此模板进行 just-in-time置备的更多信息，请参阅：[J Provisi ust-in-time oning](https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html)。

## 实例集预置
<a name="fleet-provision-template"></a>

队列配置模板 AWS IoT 用于设置云和设备配置。这些模板使用与 JITP 和批量注册模板相同的参数和资源。有关更多信息，请参阅 [预置模板](#provision-template)。实例集预调配模板可以包含一个 `Mapping` 部分和一个 `DeviceConfiguration` 部分。您可以在实例集预调配模板中使用内置函数来生成设备特定的配置。舰队配置模板被命名为资源，并由 ARNs （例如`arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName`）标识。

### 映像
<a name="mappings"></a>

可选的 `Mappings` 部分将密钥与对应的一组命名值相匹配。例如，如果要根据某个 AWS 区域设置值，则可以创建一个使用该 AWS 区域 名称作为键并包含要为每个特定区域指定的值的映射。您使用 `Fn::FindInMap` 内置函数来检索映射中的值。

您不得在 `Mappings` 部分包含参数、虚拟参数或调用内置函数。

### 设备配置
<a name="device-config"></a>

设备配置部分包含要在预调配时发送到设备的任意数据。例如：

```
{
    "DeviceConfiguration": {
        "Foo":"Bar"
    }
}
```

如果您使用 JavaScript 对象表示法 (JSON) 有效负载格式向设备发送消息， AWS IoT Core 请将此数据格式化为 JSON。如果您使用 Concise Binary Object Representation（CBOR）有效载荷格式， AWS IoT Core 会将此数据格式化为 CBOR。`DeviceConfiguration` 部分不支持嵌套 JSON 对象。

### 内置函数
<a name="intrinsic-functions"></a>

内置函数在预调配模板中除了 `Mappings` 部分以外的任何部分使用。

`Fn::Join`  
将一组值附加到单值中，中间用特定分隔符隔开。如果分隔符为空字符串，则值连接在一起而不使用分隔符。  
`Fn::Join` 不受 [策略资源](#policy-resources) 支持。

`Fn::Select`  
通过索引返回对象列表中的单个对象。  
`Fn::Select` 不会检查 `null` 值，或检查索引是否超出数组边界。这两种情况都会导致预调配错误，因此您应确保选择了一个有效的索引值，并且列表中包含非空值。

`Fn::FindInMap`  
返回与 `Mappings` 部分声明的双层映射中的键对应的值。

`Fn::Split`  
将字符串拆分为字符串值列表，以便您可以从字符串列表中选择一个元素。您可以指定一个分隔符（如逗号），用于确定拆分字符串的位置。拆分字符串后，使用 `Fn::Select` 选择一个元素。  
例如，如果将以逗号分隔的子网 IDs 字符串导入到堆栈模板中，则可以在每个逗号处拆分字符串。在子网列表中 IDs，使用`Fn::Select`为资源指定子网 ID。

`Fn::Sub`  
将输入字符串中的变量替换为您指定的值。您可以使用此函数构建命令或输出，其中包含在创建或更新堆栈之前不可用的值。

### 实例集预调配的模板示例
<a name="fleet-provisioning-example"></a>

```
{
    "Parameters" : {
        "ThingName" : {
            "Type" : "String"
        },
        "SerialNumber": {
            "Type": "String"
        },
        "DeviceLocation": {
            "Type": "String"
        }
    },
    "Mappings": {
        "LocationTable": {
            "Seattle": {
                "LocationUrl": "https://example.aws"
            }
        }
    },
    "Resources" : {
        "thing" : {
            "Type" : "AWS::IoT::Thing",
            "Properties" : {
                "AttributePayload" : { 
                    "version" : "v1",
                    "serialNumber" : "serialNumber"
                },
                "ThingName" : {"Ref" : "ThingName"},
                "ThingTypeName" : {"Fn::Join":["",["ThingPrefix_",{"Ref":"SerialNumber"}]]},
                "ThingGroups" : ["v1-lightbulbs", "WA"],
                "BillingGroup": "LightBulbBillingGroup"
            },
            "OverrideSettings" : {
                "AttributePayload" : "MERGE",
                "ThingTypeName" : "REPLACE",
                "ThingGroups" : "DO_NOTHING"
            }
        },
        "certificate" : {
            "Type" : "AWS::IoT::Certificate",
            "Properties" : {
                "CertificateId": {"Ref": "AWS::IoT::Certificate::Id"},
                "Status" : "Active",
                "ThingPrincipalType" : "EXCLUSIVE_THING"
            }
        },
        "policy" : {
            "Type" : "AWS::IoT::Policy",
            "Properties" : {
                "PolicyDocument" : {
                    "Version": "2012-10-17",		 	 	 
                    "Statement": [{
                        "Effect": "Allow",
                        "Action":["iot:Publish"],
                        "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/foo/bar"]
                    }]
                }
            }
        }
    },
    "DeviceConfiguration": {
        "FallbackUrl": "https://www.example.com/test-site",
        "LocationUrl": {
            "Fn::FindInMap": ["LocationTable",{"Ref": "DeviceLocation"}, "LocationUrl"]}
        }
}
```

**注意**  
可以对现有预调配模板进行更新以添加[预先预调配挂钩](pre-provisioning-hook.md)。