Parameters セクション Resources セクション一括登録のテンプレート例ジャストインタイムプロビジョニング (JITP) のテンプレート例フリートプロビジョニング

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

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

Parameters セクション

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


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

このテンプレート本文のスニペットでは、4 つのパラメータ (ThingName、SerialNumber、Location、CSR) を宣言します。これらのすべてのパラメータタイプは String です。Location パラメータは､デフォルト値 "WA" を宣言します。

Resources セクション

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

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

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

AWS::IoT::Thing
AWS::IoT::Certificate
AWS::IoT::Policy

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

モノのリソース

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

ThingName: 文字列。
AttributePayload: オプション。名前と値のペアのリスト。
ThingTypeName: オプション。モノに関連するモノのタイプ型の文字列。
ThingGroups: オプション。モノが属するグループのリスト。
BillingGroup: オプション。関連する請求グループ名の文字列。
PackageVersions: オプション。関連するパッケージとバージョン名の文字列。

証明書リソース

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

証明書署名リクエスト (CSR)｡
既存のデバイス証明書の証明書 ID。(フリートプロビジョニングテンプレートで使用できるのは証明書 ID のみです)。
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: オプション。文字列。デフォルトはポリシードキュメントのハッシュです。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\"] }] }"
            }
        }
    }
}

ジャストインタイムプロビジョニング (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」を参照してください。

このテンプレートをジャストインタイムプロビジョニングに使用する方法の詳細については、「ジャストインタイムプロビジョニング」を参照してください。

フリートプロビジョニング

フリートプロビジョニングテンプレートは、クラウドおよびデバイス設定をセットアップするために AWS IoT によって使用されます。これらのテンプレートは、JITP テンプレートおよび一括登録テンプレートと同じパラメータおよびリソースを使用します。詳細については、「プロビジョニングテンプレート」を参照してください。フリートプロビジョニングテンプレートには、Mapping セクションと DeviceConfiguration セクションを含めることができます。フリートプロビジョニングテンプレート内で組み込み関数を使用して、デバイス固有の設定を生成できます。フリートプロビジョニングテンプレートは名前付きリソースで、ARN によって識別されます (例: arn:aws:iot:us-west-2:1234568788:provisioningtemplate/templateName)。

Mappings

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

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

デバイス設定

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


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

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

組み込み関数

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

Fn::Join

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

重要

Fn::Join はポリシーリソースに対してサポートされていません。

Fn::Select

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

重要

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

Fn::FindInMap

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

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

注記

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

一括登録

事前プロビジョニングフック