AWS IoT ジョブの準備 - AWS IoT Core
AWS IoT ジョブの代替パラメータデプロイ用のジョブドキュメントとパッケージバージョンの準備デプロイ時のパッケージとバージョンの命名AWS IoT モノの動的グループによるジョブのターゲット設定予約済みの名前付きシャドウとパッケージバージョンソフトウェアパッケージのアンインストール

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

AWS IoT ジョブの準備

AWS IoT Device Management Software Package Catalog は、置換パラメータ、 AWS IoT フリートインデックス作成、動的モノのグループ、 AWS IoT モノの予約済み名前付きシャドウとの統合を通じて AWS IoT ジョブを拡張します。

注記

Software Package Catalog が提供するすべての機能を使用するには、次の AWS Identity and Access Management （IAM) ロールとポリシーを作成する必要があります。AWS IoT パッケージバージョンをデプロイするジョブ権限とAWS IoT 、予約された名前付きシャドウ を更新するためのジョブ権限。詳細については、「セキュリティの準備」を参照してください。

AWS IoT ジョブの代替パラメータ

置換パラメータは、 AWS IoT ジョブドキュメント内のプレースホルダーとして使用できます。ジョブサービスが代替パラメータを検出すると、そのジョブは、指定されたソフトウェアバージョンのパラメータ値の属性を指します。このプロセスを使用して 1 つのジョブドキュメントを作成し、汎用属性を介してメタデータをジョブに渡すことができます。例えば、Amazon Simple Storage Service (Amazon S3) URL、ソフトウェアパッケージ Amazon リソースネーム (ARN）、または署名をパッケージバージョン属性を介してジョブドキュメントに渡すことができます。

代替パラメータは、ジョブドキュメントで次のようにフォーマットする必要があります。

  • ソフトウェアパッケージ名とパッケージバージョン

    • 間の空の文字列は、ソフトウェアパッケージ名の置換パラメータpackage::versionを表します。間の空の文字列は、ソフトウェアパッケージバージョン置換パラメータversion::attributeを表します。ジョブドキュメントでパッケージ名とパッケージ検証置換パラメータを使用するには、次の例を参照してください。 ${aws:iot:package::version::attributes:<attributekey>}

    • ジョブドキュメントは、パッケージバージョンARNの詳細から バージョンを使用して、これらの置換パラメータを自動入力します。API または CLI コマンドを使用して単一パッケージデプロイ用のジョブまたはジョブテンプレートを作成する場合、パッケージバージョンのバージョンARNは CreateJobおよび の destinationPackageVersionsパラメータで表されますDescribeJob。

  • ソフトウェアパッケージバージョンのすべての属性

    • ジョブドキュメントでソフトウェアパッケージバージョン置換パラメータのすべての属性を使用するには、次の例を参照してください。 ${aws:iot:package:<packageName>:version:<versionName>:attributes}

注記

パッケージ名、パッケージバージョン、およびすべての属性置換パラメータを一緒に使用できます。ジョブドキュメントで 3 つの置換パラメータをすべて使用する方法については、次の例を参照してください。 ${aws:iot:package::version::attributes}

次の例では、 という名前のソフトウェアパッケージsamplePackageがあり、次の属性を持つ という名前2.1.5のパッケージバージョンがあります。

  • 名前: s3URL、値: https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile

    • この属性は、Amazon S3 内に保存されているコードファイルの場所を識別します。

  • 名前: signature、値: aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj

    • この属性は、デバイスがセキュリティ対策として必要とするコード署名値を提供します。詳細については、「ジョブのコード署名」を参照してください。注: この属性は一例であり、Software Package Catalog やジョブの一部としては必須ではありません。

s3URL の場合、ジョブドキュメントパラメータは次のように記述されます。

{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
}

signature の場合、ジョブドキュメントパラメータは次のように記述されます。

{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
}

ジョブドキュメント全体は次のように記述されます。

{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
      },
    ],
    "signature": [
      "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
    ]
  }
}

置換が行われると、次のジョブドキュメントがデバイスにデプロイされます。

{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile"
      },
    ],
    "signature": [
      "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj"
    ]
  }
}

置換パラメータ (表示前と表示後）

代替パラメータは、デフォルトのパッケージバージョンなど、さまざまなフラグを使用してジョブドキュメントの作成$defaultを効率化します。これにより、特定のパッケージ検証で参照されるメタデータがそれらのフラグに自動入力されるため、ジョブデプロイごとに特定のパッケージバージョンメタデータを手動で入力する必要がなくなります。デフォルトのパッケージバージョンの など、パッケージバージョンの属性の詳細については、$default「」を参照してくださいデプロイ用のジョブドキュメントとパッケージバージョンの準備。

で AWS Management Console、パッケージバージョンのジョブデプロイ中にデプロイ指示ファイルエディタウィンドウの置換プレビューボタンを切り替えると、置換パラメータの有無にかかわらずジョブドキュメントが表示されます。

DescribeJob および GetJobDocument の「置換前」パラメータを使用するとAPIs、置換パラメータが削除される前後のAPIレスポンスを表示できます。DescribeJob および で次の例を参照してくださいGetJobDocumentAPIs。

  • DescribeJob

    • デフォルトビュー

      {
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"]
}

    • 置換前ビュー

      {
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"]
}

  • GetJobDocument

    • デフォルトビュー

      {
    "attributes": {
        "location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core",
        "signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI",
        "streamName": "mqtt-core",
        "fileId": "0"
    },
}

    • 置換前ビュー

      {
    "attributes": "${aws:iot:package:TestPackage:version:$default:attributes}",
}

AWS IoT ジョブ、ジョブドキュメントの作成、ジョブのデプロイの詳細については、「ジョブ」を参照してください。

デプロイ用のジョブドキュメントとパッケージバージョンの準備

パッケージバージョンが作成されると、デプロイの準備中であることを示すdraft状態になります。パッケージバージョンをデプロイ用に準備するには、ジョブドキュメントを作成し、ジョブがアクセスできる場所 (Amazon S3 など) にドキュメントを保存し、パッケージバージョンにジョブドキュメントで使用する属性値があることを確認する必要があります。（注: パッケージバージョンの属性を更新できるのは、 draft 状態のときのみです）。

単一パッケージデプロイ用の AWS IoT ジョブまたはジョブテンプレートを作成する場合、ジョブドキュメントをカスタマイズするための以下のオプションがあります。

デプロイ指示ファイル (recipe）

  • パッケージバージョンのデプロイ指示ファイルには、パッケージバージョンを複数のデバイスにデプロイするためのインラインジョブドキュメントを含むデプロイ指示が含まれています。ファイルは、迅速かつ効率的なジョブデプロイのために、特定のデプロイ手順をパッケージバージョンに関連付けます。

    では AWS Management Console、新しいパッケージの作成ワークフローのバージョンデプロイ設定タブのデプロイ手順ファイルプレビューウィンドウでファイルを作成できます。 AWS IoT を使用して、推奨ファイルから AWS IoT 開始を使用してパッケージバージョン属性から指示ファイルを自動的に生成するか、独自のデプロイ指示ファイル を使用して Amazon S3 バケットに保存されている既存のジョブドキュメントを使用できます。

    注記

    独自のジョブドキュメントを使用する場合は、デプロイ手順ファイルプレビューウィンドウで直接更新できますが、Amazon S3 バケットに保存されている元のジョブドキュメントは自動的に更新されません。

    AWS CLI または CreatePackageVersion、、 GetPackageVersionなどのAPIコマンドを使用する場合UpdatePackageVersion、 は、インラインジョブドキュメントを含むデプロイ指示ファイルrecipeを表します。

    ジョブドキュメントの詳細については、「」を参照してください基本概念。

    で表されるデプロイ指示ファイルについては、次の例を参照してくださいrecipe。

    {
    "packageName": "sample-package-name",
    "versionName": "sample-package-version",
    ...
    "recipe": "{...}"
}
    注記

    で表されるデプロイインストラクションファイルは、パッケージバージョンがパッケージバージョンメタデータとは別にpublishedステータス状態にあるときに更新recipeできます。ジョブのデプロイ中に変更できなくなります。

Artifact バージョン属性

  • ソフトウェアパッケージバージョンartifactのバージョン属性を使用して、パッケージバージョンアーティファクトの Amazon S3 の場所を追加できます。Jobs を使用して AWS IoT パッケージバージョンのジョブデプロイがトリガーされると、ジョブドキュメント ${aws:iot:package:<packageName>:version:<versionName>:artifact-location:s3-presigned-url}の署名付きURLプレースホルダーは、Amazon S3 バケット、バケットキー、および Amazon S3 バケットに保存されているファイルのバージョンを使用して更新されます。パッケージバージョンのアーティファクトを保存する Amazon S3 バケットは、パッケージバージョンが作成されたのと同じリージョンに配置する必要があります。

    注記

    Amazon S3 バケットに同じファイルの複数のオブジェクトバージョンを保存するには、バケットでバージョニングを有効にする必要があります。詳細については、「バケットでのバージョニングの有効化」を参照してください。

    CreatePackageVersion または UpdatePackageVersionAPIオペレーションを使用するときに Amazon S3 バケット内のパッケージバージョンアーティファクトにアクセスするには、次のアクセス許可が必要です。

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:<partition>:s3:::<bucket>/<key>"
        }
    ]
}

    CreatePackageVersion および UpdatePackageVersionAPIオペレーションのバージョン属性の詳細については、artifactCreatePackageVersion「」および「」を参照してくださいUpdatePackageVersion。

    新しいパッケージバージョンを作成するときに Amazon S3 のアーティファクトの場所artifactをサポートするバージョン属性を示す次の例を参照してください。

    {
    "packageName": "sample package name",
    "versionName": "1.0",
    "artifact": {
        "s3Location": {
            "bucket": "firmware",
            "key": "image.bin",
            "version": "12345"
        }
    }
}
    注記

    パッケージバージョンがdraftステータス状態からpublishedステータス状態に更新されると、パッケージバージョンの属性とアーティファクトの場所は不変になります。この情報を更新するには、新しいパッケージバージョンを作成し、draftステータス状態で更新を実行する必要があります。

パッケージバージョン

  • デフォルトのソフトウェアパッケージバージョンは、安全で安定したパッケージバージョンを提供するソフトウェアパッケージの利用可能なバージョンに表示できます。これは、 AWS IoT Jobs を使用してデフォルトのパッケージバージョンをデバイスフリートにデプロイする際のソフトウェアパッケージのベースラインバージョンとして機能します。ソフトウェアパッケージの$defaultパッケージバージョンをデプロイするジョブを作成する場合、ジョブドキュメントと新しいジョブデプロイのパッケージバージョンは と一致する必要があります$default。ジョブデプロイのパッケージバージョンは、 API および CLI コマンドdestinationPackageVersionsの および VersionARNで表されます AWS Management Console。ジョブドキュメントのパッケージバージョンは、以下に示すジョブドキュメントプレースホルダーによって表されます。

    arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$default

    デフォルトのパッケージバージョンを使用してジョブまたはジョブテンプレートを作成するには、以下に示すように、 CreateJobまたは CreateJobTemplate API コマンドで $defaultフラグを使用します。

    "$ aws iot create-job \
    --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"
    --document file://jobdoc.json
    注記

    デフォルトバージョンを参照する$defaultパッケージバージョン属性は、ジョブを介した AWS IoT ジョブデプロイのデフォルトパッケージバージョンを参照する場合にのみ必要なオプションの属性です。

パッケージバージョンに満足したら、 AWS IoT コンソールのソフトウェアパッケージの詳細ページまたは UpdatePackageVersionAPIオペレーションを発行して公開します。その後、 AWS IoT コンソールを介して、または CreateJob API オペレーションを発行することで、ジョブを作成するときにパッケージバージョンを参照できます。

デプロイ時のパッケージとバージョンの命名

ソフトウェアパッケージバージョンをデバイスにデプロイするには、ジョブドキュメントで参照されているソフトウェアパッケージとパッケージバージョンが、 CreateJob API オペレーションの destinationPackageVersionsパラメータに記載されているソフトウェアパッケージとパッケージバージョンと一致していることを確認します。一致しない場合は、両方の参照を一致させるように促すエラーメッセージが表示されます。Software Package Catalog のエラーメッセージの詳細については、「」を参照してください一般的なトラブルシューティングエラーメッセージ。

ジョブドキュメントで参照されているソフトウェアパッケージとパッケージバージョンに加えて、ジョブドキュメントで参照されていないCreateJobAPIオペレーションの destinationPackageVersionsパラメータに追加のソフトウェアパッケージとパッケージバージョンを含めることができます。追加のソフトウェアパッケージバージョンを適切にインストールするために必要なインストール情報が、 デバイスのジョブドキュメントに含まれていることを確認します。CreateJob API オペレーションの詳細については、「」を参照してくださいCreateJob。

AWS IoT モノの動的グループによるジョブのターゲット設定

Software Package Catalogは、フリートインデックス作成、AWS IoT のジョブ、AWS IoT のモノの動的グループと連携して、フリート内のデバイスをフィルタリングしてターゲットにし、デバイスにデプロイするパッケージバージョンを選択します。デバイスの現在のパッケージ情報に基づいてフリートインデックス作成クエリを実行し、ジョブのそれらの項目をターゲットにできます AWS IoT 。ソフトウェアアップデートをリリースすることもできますが、対象となるターゲットデバイスに対してのみです。例えば、現在 iot-device-client 1.5.09 を実行しているデバイスにのみ設定をデプロイするように指定できます。詳細については、「モノの動的グループを作成する」を参照してください。

予約済みの名前付きシャドウとパッケージバージョン

設定されている場合、 AWS IoT ジョブが正常に完了すると、ジョブはモノの予約済み名前付きシャドウ ($package) を更新できます。そうすれば、パッケージバージョンをモノの予約済みの名前付きシャドウに手動で関連付ける必要がなくなります。

次のような状況では、パッケージバージョンをモノの予約済みの名前付きシャドウに手動で関連付けるか、更新することを選択できます。

  • インストールされたパッケージバージョンを関連付け AWS IoT Core ずに、モノを に登録します。

  • AWS IoT ジョブは、モノの予約済み名前付きシャドウを更新するように設定されていません。

  • 社内のプロセスを使用してパッケージバージョンをフリートにディスパッチすると、そのプロセスは完了 AWS IoT Core しても更新されません。

注記

AWS IoT Jobs を使用して、予約された名前付きシャドウ () のパッケージバージョンを更新することをお勧めします$package。 AWS IoT Jobs $package もシャドウを更新するように設定されている場合、他のプロセス (手動またはプログラムによるAPI呼び出しなど) を通じてシャドウ内のバージョンパラメータを更新すると、デバイスの実際のバージョンと予約された名前付きシャドウに報告されたバージョンとの間に不一致が発生する可能性があります。

コンソールまたは UpdateThingShadowAPIオペレーションを使用して、モノの予約済み名前付きシャドウ ($package) にパッケージバージョンを追加または更新できます。詳細については、「 AWS IoT のモノへのパッケージバージョンの関連付け」を参照してください。

注記

パッケージバージョンを AWS IoT モノに関連付けると、デバイスソフトウェアは直接更新されません。デバイスソフトウェアを更新するには、パッケージバージョンをデバイスにデプロイする必要があります。

ソフトウェアパッケージとそのパッケージバージョンのアンインストール

$null は、 AWS IoT Jobs サービスに、デバイスの予約済み名前付きシャドウ から既存のソフトウェアパッケージとパッケージバージョンを削除するように求める予約済みプレースホルダーです$package。詳細については、「予約済みの名前付きシャドウ」を参照してください。

この機能を使用するには、destinationPackageVersionAmazon リソースネーム (ARN) の末尾にあるバージョン名を に置き換えます$null。その後、デバイスからソフトウェアを削除するようにサービスに指示する必要があります。

認可された は、次の形式ARNを使用します。

arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

例えば、 などです

$ aws iot create-job \
    ... \
    --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]