本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 佈建範本 佈建範本是 JSON 文件，使用參數來描述裝置與之互動時必須使用的資源 AWS IoT。佈建範本內含兩個部分：`Parameters` 和 `Resources`。佈建範本有兩種類型 AWS IoT。一個用於即時佈建 (JITP) 和大量註冊，第二個則用於機群佈建。 **Topics** + [ ## 參數部分 ](#parameters-section) + [ ## 資源部分 ](#resources-section) + [ ## 大量註冊的範本範例 ](#bulk-template-example) + [ ## 即時佈建 (JITP) 的範本範例 ](#JITP-template-example) + [ ## 機群佈建 ](#fleet-provision-template) ## 參數部分 `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註冊所建立的裝置憑證。如果您的多個 憑證授權機構憑證註冊使用相同的主體欄位，您也必須輸入用於簽署該裝置憑證的憑證授權機構憑證。 **注意** 若您使用範本宣告憑證，請透過這些方法其中之一。例如，若您使用 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 和憑證授權機構憑證 .pem 指定的憑證： ``` { "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "CACertificatePem": {"Ref" : "CACertificatePem"}, "CertificatePem": {"Ref" : "CertificatePem"} } } } ``` + 僅將一個物件連接至委託人： ``` { "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "ThingPrincipalType" : "EXCLUSIVE_THING" } } } ``` ### 政策資源 政策資源宣告使用下列屬性之一： + `PolicyName`：選用。字串. 預設為政策文件雜湊。此 `PolicyName` 只能參考 AWS IoT 政策，而不是 IAM 政策。如果您使用的是現有 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", "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\"] }] }" } } } } ``` ## 即時佈建 (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", "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)中的 。 如需了解如何使用此範本進行即時佈建，請參閱：[即時佈建](https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html)。 ## 機群佈建 機群佈建範本由 AWS IoT 用來設定雲端和裝置組態。這些範本會使用與 JITP 和大量註冊範本相同的參數和資源。如需詳細資訊，請參閱[佈建範本](#provision-template)。機群佈建範本可以包含一個 `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。如果您使用的是 Concise Binary Object Representation (CBOR) 承載格式， AWS IoT Core 會將此資料格式化為 CBOR。`DeviceConfiguration` 區段不支援巢狀 JSON 物件。 ### 內建函數 內部函數用於佈建範本的任何區段，但 `Mappings` 區段除外。 `Fn::Join` 將一組值附加至單一值，並以指定的分隔符號隔開。如果分隔符號是空白字串，系統即會串連這些值，而不使用分隔符號。 [政策資源](#policy-resources) 不支援 `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", "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](pre-provisioning-hook.md)。