AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

预配置模板

预置模板是一个 JSON 文档,该文档使用参数来描述设备与 AWS IoT 交互时必须使用的资源。模板包含两个部分:ParametersResources

参数部分

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 通信所需的资源:事物、证书以及一个或多个策略。每个资源指定一个逻辑名称、一个类型和一组属性。

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

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

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

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

事物资源

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

  • ThingName: 字符串.

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

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

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

证书资源

可以使用以下方法之一指定证书:

  • 证书签名请求 (CSR)。

  • 现有设备证书的证书 ID。

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

注意

当您在模板中声明证书时,请只使用这些方法之一。例如,如果您使用了 CSR,就不能同时指定证书 ID 或设备证书。

有关更多信息,请参阅 AWS IoT 和证书

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

  • CertificateSigningRequest: 字符串.

  • CertificatePem: 字符串.

  • CACertificatePem: 字符串.

  • Status: 可选. 字符串,可以是以下值之一:ACTIVE、INACTIVE、PENDING_ACTIVATION。默认值为 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: 可选. 字符串。默认值为策略文档的哈希值。

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

注意

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

覆盖设置

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

DO_NOTHING

将资源保留为原样。

REPLACE

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

FAIL

导致请求失败,出现 ResourceConflictsException

MERGE

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

资源示例

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

"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" }, "OverrideSettings" : { "Status" : "DO_NOTHING" } }, "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\"] }] }" } } } }

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

{ "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" : { "CertificateId": {"Ref" : "CertificateId"} }, "OverrideSettings" : { "Status" : "DO_NOTHING" } }, "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\"] }] }" } } } }