佈建範本

焦點模式

佈建範本 - AWS IoT Core

參數部分資源部分大量註冊的範本範例 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註冊所建立的裝置憑證。如果您的多個憑證授權機構憑證註冊使用相同的主體欄位，您也必須輸入用於簽署該裝置憑證的憑證授權機構憑證。

注意

若您使用範本宣告憑證，請透過這些方法其中之一。例如，若您使用 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 和憑證授權機構憑證 .pem 指定的憑證：


{
    "certificate" : {
        "Type" : "AWS::IoT::Certificate",
        "Properties" : {
            "CACertificatePem": {"Ref" : "CACertificatePem"},
            "CertificatePem": {"Ref" : "CertificatePem"}
        }
    }
}

政策資源

政策資源宣告使用下列屬性之一：

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

注意

您可以更新現有的佈建範本，以新增 pre-provisioning hook。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

大量註冊

預先佈建掛接

在本頁面

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定