プロビジョニングテンプレート - AWS IoT コア

「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」

プロビジョニングテンプレート

プロビジョニングテンプレートは、パラメータを使用してデバイスが AWS IoT と対話するために使用する必要があるリソースについて説明する JSON ドキュメントです。テンプレートには 2 つのセクションがあります。Parameters および Resources。 には、2 種類のプロビジョニングテンプレートがあります。AWS IoT1 つはジャストインタイムプロビジョニング (JITP) と一括登録に使用され、もう 1 つはフリートプロビジョニングに使用されます。

Parameters セクション

Parameters セクションでは、Resources セクションで使用されるパラメータを宣言します。各パラメータは、名前、タイプ、およびオプションのデフォルト値を宣言します。デフォルト値は、テンプレートで渡されたディクショナリにパラメータの値が含まれていない場合に使用されます。テンプレートドキュメントの Parameters セクションは、次のようになります。

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

このテンプレートでは、4 つのパラメーターを宣言します。ThingNameSerialNumberLocation、および CSR。 これらのパラメータはすべて、String 型です。 パラメータは、デフォルト値 Location を宣言します。"WA"

Resources セクション

テンプレートの Resources セクションは、デバイスが AWS IoT と通信するために必要なリソース、つまりモノ、証明書、および 1 つ以上の IoT ポリシーを宣言します。各リソースは、論理名、タイプ、および一連のプロパティを指定します。

論理名を使用すると、テンプレートの別の場所でリソースを参照できます。

タイプは、宣言するリソースの種類を指定します。有効なタイプは次のとおりです。

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

指定するプロパティは、宣言するリソースのタイプによって異なります。

モノのリソース

モノのリソースは、次のプロパティを使用して宣言されます。

  • ThingName : 文字列。

  • AttributePayload : 省略可能。名前と値のペアのリスト。

  • ThingTypeName : 省略可能。モノに関連するモノのタイプ型の文字列。

  • ThingGroups : 省略可能。モノが属するグループのリスト。

証明書リソース

証明書は、次のいずれかの方法で指定できます。

  • 証明書署名リクエスト (CSR)。

  • 既存のデバイス証明書の証明書 ID。(フリートプロビジョニングテンプレートで使用できるのは証明書 IDs のみです)。

  • AWS IoT で登録された CA 証明書で作成されたデバイス証明書。同じ件名フィールドに複数の CA 証明書が登録されている場合は、デバイス証明書の署名に使用された CA 証明書も渡す必要があります。

注記

テンプレートで証明書を宣言する場合は、これらのいずれかの方法のみを使用してください。たとえば、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 および CA 証明書 .pem で指定された証明書:

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

ポリシーリソース

ポリシーリソースは、以下のいずれかのプロパティを使用して宣言されます。

  • PolicyName : 省略可能。文字列。デフォルトはポリシードキュメントのハッシュです。既存の 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

  • 既存のポリシー名またはポリシードキュメントの名前。

JITP および一括登録のテンプレート例

以下の 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" }, "CertificateId" : { "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"} } }, "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 セクションを含めることができます。フリートプロビジョニングテンプレート内で組み込み関数を使用して、デバイス固有の設定を生成できます。フリートプロビジョニングテンプレートは名前付きリソースで、ARNs によって識別されます (例: arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName)。

Mappings

任意の Mappings セクションでは、キーと名前付きの一連の値とが対応付けられます。たとえば、AWS リージョンに基づく値を設定する場合、キーとして AWS リージョン名を使用し、特定のリージョンごとに指定する値を含むマッピングを作成できます。マップ内の値を取得するには、Fn::FindInMap 組み込み関数を使用します。

Mappings セクションにパラメータ、擬似パラメータを含めること、または組み込み関数を呼び出すことはできません

デバイス設定

デバイス設定セクションには、プロビジョニング時にデバイスに送信する任意のデータが含まれています。次に例を示します。

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

オブジェクト表記 (JSON) ペイロード形式を使用してデバイスにメッセージを送信する場合、JavaScript はこのデータを JSON としてフォーマットします。AWS IoT Core簡潔なバイナリオブジェクト表現 (CBOR) ペイロード形式を使用している場合、AWS IoT Core はこのデータを CBOR としてフォーマットします。セクションは、ネストされた JSON オブジェクトをサポートしていません。DeviceConfiguration

組み込み関数

組み込み関数は、Mappings セクションを除くプロビジョニングテンプレートの任意のセクションで使用されます。

Fn::Join

一連の値を特定の区切り文字で区切って 1 つの値に追加します。区切り文字が空の文字列の場合、一連の値は区切り文字を使用することなく連結されます。

Fn::Select

インデックスによってオブジェクトのリストから単一のオブジェクトを返します。

重要

Fn::Select では、null 値のチェックや、インデックスが配列の範囲外であるかどうかのチェックは行われません。どちらの条件もプロビジョニングエラーになるため、有効なインデックス値を選択し、リストに null 以外の値が含まれていることを確認してください。

Fn::FindInMap

Mappings セクションで宣言された 2 つのレベルのマッピングのキーに対応する値を返します。

Fn::Split

文字列を文字列値のリストに分割して、文字列リストから要素を選択できるようにします。文字列の分割位置を決定する区切り文字を指定します(コンマなど)。文字列を分割した後、Fn::Select を使用して要素を選択します。

たとえば、サブネット IDs のカンマ区切りの文字列がスタックテンプレートにインポートされる場合、各カンマで文字列を分割できます。サブネット IDs のリストから、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"]} } }
注記

既存のプロビジョニングテンプレートを更新して、事前プロビジョニングフックを追加できます。