参数部分资源部分批量注册的模板示例 just-in-time配置模板示例 (JITP)实例集预调配

预调配模板

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

主题

参数部分
资源部分
批量注册的模板示例
just-in-time配置模板示例 (JITP)
实例集预调配

参数部分

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

资源部分

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

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

类型指定您所声明的资源的种类。有效类型为：

AWS::IoT::Thing
AWS::IoT::Certificate
AWS::IoT::Policy

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

事物资源

事物资源使用以下属性进行声明：

ThingName: 字符串。
AttributePayload：可选。名称-值对的列表。
ThingTypeName：可选。用于事物的关联事物类型的字符串。
ThingGroups：可选。事物所属的组的列表。
BillingGroup：可选。关联账单组名称的字符串。
PackageVersions：可选。关联软件包名称和版本名称的字符串。

证书资源

您可以通过以下方式之一指定证书：

证书签名请求 (CSR)。
现有设备证书的证书 ID。（仅证书 ID 可与实例集预调配模板一起使用。）
使用注册到 AWS IoT的 CA 证书创建的设备证书。如果您有多个 CA 证书注册到同一使用者字段，则还必须传入用于对设备证书进行签名的 CA 证书。

注意

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

有关更多信息，请参阅 X.509 证书概览。

证书资源使用以下属性进行声明：

CertificateSigningRequest: 字符串。
CertificateId: 字符串。
CertificatePem: 字符串。
CACertificatePem: 字符串。
Status：可选。字符串可以是 ACTIVE 或 INACTIVE。默认值为 ACTIVE。

示例：

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

策略资源

策略资源使用以下属性之一进行声明：

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

注意

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

覆盖设置

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

DO_NOTHING: 将资源保留为原样。
REPLACE: 使用在模板中指定的资源替换该资源。
FAIL: 导致请求失败，出现 ResourceConflictsException。
MERGE: 仅对 ThingGroups 的 AttributePayload 和 thing 属性有效。将事物的现有属性或组成员资格与模板中指定的同等内容合并。

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

ATTRIBUTE_PAYLOAD
THING_TYPE_NAME
THING_GROUPS

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

OverrideSettings 不可用于策略资源。

资源示例

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


{ 
    "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。
现有策略的名称或策略文档的名称。

批量注册的模板示例

以下 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"      
            }
        },
        "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)

以下 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"
         }
      },
      "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 参考CreateProvisioningTemplate中的。

有关如何使用此模板进行置备的更多信息，请参阅：即时 just-in-time 配置。

实例集预调配

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

映像

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

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

设备配置

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


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

如果您使用 JavaScript 对象表示法 (JSON) 有效负载格式向设备发送消息， AWS IoT Core 请将此数据格式化为 JSON。如果您使用的是简明二进制对象表示 (CBOR) 有效载荷格式， AWS IoT Core 请将此数据格式化为 CBOR。DeviceConfiguration 部分不支持嵌套 JSON 对象。

内置函数

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

Fn::Join

将一组值附加到单值中，中间用特定分隔符隔开。如果分隔符为空字符串，则值连接在一起而不使用分隔符。

重要

Fn::Join 不受策略资源支持。

Fn::Select

通过索引返回对象列表中的单个对象。

重要

Fn::Select 不会检查 null 值，或检查索引是否超出数组边界。这两个条件都会导致配置错误，因此请确保您选择了有效的索引值并且列表包含非空值。

Fn::FindInMap

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

Fn::Split

将字符串拆分为字符串值列表，以便您可以从字符串列表中选择一个元素。您可以指定一个分隔符（如逗号），用于确定拆分字符串的位置。拆分字符串后，使用 Fn::Select 选择一个元素。

例如，如果将以逗号分隔的子网 ID 字符串导入您的堆栈模板，您可以在每个逗号的位置拆分字符串。从子网 ID 列表中，使用 Fn::Select 指定资源的子网 ID。

Fn::Sub

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

实例集预调配的模板示例


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

注意

可以对现有预调配模板进行更新以添加预先预调配挂钩。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

批量注册

预先预调配挂钩