预调配模板 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

预调配模板

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

参数部分

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

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

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

资源部分

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

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

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

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

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

事物资源

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

  • ThingName: 字符串。

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

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

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

  • BillingGroup:可选。关联账单组名称的字符串。

  • PackageVersions:可选。关联软件包名称和版本名称的字符串。

证书资源

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

  • 证书签名请求 (CSR)。

  • 现有设备证书的证书 ID。(仅证书 ID 可与实例集预调配模板一起使用。)

  • 使用注册到 Amazon 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:可选。字符串。默认值为策略文档的哈希值。PolicyName 只能参考 Amazon IoT 策略但不是 IAM policy。如果您使用的是现有 Amazon 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" : { "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

有关配置模板类型的更多信息,请参阅 Amazon API 参考CreateProvisioningTemplate中的。

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

实例集预调配

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

映像

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

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

设备配置

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

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

如果您使用 JavaScript 对象表示法 (JSON) 有效负载格式向设备发送消息, Amazon IoT Core 请将此数据格式化为 JSON。如果您使用的是简明二进制对象表示 (CBOR) 有效载荷格式, Amazon 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"]} } }
注意

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