预置模板 - AWS IoT

预置模板

预置模板是一个 JSON 文档,该文档使用参数来描述设备与 AWS IoT 交互时必须使用的资源。模板包含两个部分:ParametersResources。AWS IoT 中有两种类型的预置模板。一个用于即时配置 (JITP) 和批量注册,另一个用于队列预置。

参数部分

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

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

此模板片段声明四个参数:ThingNameSerialNumberLocationCSR。所有这些参数均为 String 类型。Location 参数声明了默认值 "WA"

资源部分

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

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

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

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

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

事物资源

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

  • ThingName: 字符串.

  • AttributePayload: 可选.名称-值对的列表。

  • ThingTypeName: 可选.用于事物的关联事物类型的字符串。

  • ThingGroups: 可选.事物所属的组的列表。

证书资源

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

  • 证书签名请求 (CSR)。

  • 现有设备证书的证书 ID。(仅证书 ID 可与队列预置模板一起使用。)

  • 使用注册到 AWS IoT 的 CA 证书创建的设备证书。如果您有多个 CA 证书注册到同一使用者字段,则还必须传入用于对设备证书进行签名的 CA 证书。

注意

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

有关更多信息,请参阅 X.509 证书概述

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

  • CertificateSigningRequest: 字符串.

  • CertificateID: 字符串.

  • CertificatePem: 字符串.

  • CACertificatePem: 字符串.

  • Status: 可选.字符串可以是 ACTIVEINACTIVE。默认值为 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: 可选.字符串。默认值为策略文档的哈希值。如果您使用现有的 AWS IoT 策略,则对于 PolicyName 属性,输入策略的名称。请勿包含 PolicyDocument 属性。

  • PolicyDocument: 可选.指定为转义字符串的 JSON 对象。如果未提供 PolicyDocument,则必须已经创建了策略。

注意

如果存在 Policy 部分,则必须指定 PolicyNamePolicyDocument,但不能同时指定。

覆盖设置

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

DO_NOTHING

将资源保留为原样。

REPLACE

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

FAIL

导致请求失败,出现 ResourceConflictsException

MERGE

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

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

  • ATTRIBUTE_PAYLOAD

  • THING_TYPE_NAME

  • THING_GROUPS

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

OverrideSettings 不可用于策略资源。

资源示例

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

{ "Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "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

  • 现有策略的名称或策略文档的名称。

JITP 和批量注册的模板示例

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

(PolicyDocument 字段值必须是指定为转义字符串的 JSON 对象。)

{ "Parameters" : { "SerialNumber" : { "Type" : "String" }, "Location" : { "Type" : "String", "Default" : "WA" }, "CSR" : { "Type" : "String" } }, "Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "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\"] }] }" } } } }

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

{ "Parameters" : { "SerialNumber" : { "Type" : "String" }, "Location" : { "Type" : "String", "Default" : "WA" }, "CertificateId" : { "Type" : "String" } }, "Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "AttributePayload" : { "version" : "v1", "serialNumber" : {"Ref" : "SerialNumber"}}, "ThingTypeName" : "lightBulb-versionA", "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}] } }, "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "CertificateId": {"Ref" : "CertificateId"} } }, "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\"] }] }" } } } }

队列预置

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

映像

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

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

设备配置

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

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

内部函数

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

Fn:Join

将一组值附加到单值中,中间用特定分隔符隔开。如果分隔符为空字符串,则该组值不通过分隔符被连接在一起。

Fn:Select

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

重要

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

Fn:FindInMap

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

Fn:Split

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

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

Fn:Sub

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

队列预置模板示例

{ "Parameters" : { "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" }, "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"]} } } }
注意

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