ジョブの作成ジョブの更新ジョブのキャンセルジョブ実行をキャンセルするジョブを削除するジョブドキュメントの取得ジョブのリスト表示ジョブの説明ジョブ実行リストモノのジョブ実行リストジョブ実行の説明ジョブ実行を削除する

AWS CLI を使用してジョブを作成および管理します。

このセクションでは、ジョブを作成して管理する方法について説明します。

ジョブの作成

AWS IoT ジョブを作成するには、CreateJob コマンドを使用します。ジョブは、指定したターゲット (モノまたはモノのグループ) で実行キューに登録されます。AWS IoT ジョブを作成するには、リクエストの本文に含めることができるジョブドキュメントまたは Amazon S3 ドキュメントへのリンクとしてジョブドキュメントを作成する必要があります。署名付き Amazon S3 URL を使用してファイルをダウンロードすることがジョブに含まれる場合は、ファイルをダウンロードするアクセス許可があり、ロールを引き受ける AWS IoT Jobs サービスにアクセス許可を付与する IAM ロール Amazon リソースネーム (ARN) が必要です。

API コマンドまたは AWS CLI を使用して日時を入力する場合の構文については、「タイムスタンプ」を参照してください。

コード署名とジョブ

AWS IoT のコード署名を使用する場合は、コード署名付きのジョブを開始し、ジョブドキュメントにその出力を含める必要があります。これは、コード署名プロファイルを使用して署名されたコードファイルパスに置き換えるまで、プレースホルダーとして必要とされる、ジョブドキュメント内のコード署名の署名プレースホルダーを置き換えます。コード署名の署名プレースホルダーは、次のようになります。


    ${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}

start-signing-job コマンドを使用してコード署名付きジョブを作成します。start-signing-job はジョブ ID を返します。署名が保存されている Amazon S3 の場所を取得するには、describe-signing-job コマンドを使用します。その後、署名は Amazon S3 からダウンロードできます。コード署名付きジョブの詳細については、AWS IoT のコード署名を参照してください。

次のように、ジョブドキュメントにはコードファイルの署名付き URL プレースホルダーおよび start-signing-job コマンドを使用して Amazon S3 バケットに配置された JSON 署名出力が含まれる必要があります。


{
    "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}",
}

ジョブドキュメントを使用したジョブの作成

次のコマンドは、Amazon S3 バケット (jobBucket) に保存されているジョブドキュメント (job-document.json) と、Amazon S3 からファイルをダウンロードするためのアクセス許可を持つロール (S3DownloadRole) を使用してジョブを作成する方法を示しています。


aws iot create-job  \
      --job-id 010  \
      --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne  \
      --document-source https://s3.amazonaws.com/my-s3-bucket/job-document.json  \
      --timeout-config inProgressTimeoutInMinutes=100 \
      --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}}, \"maximumPerMinute\": 1000}" \
      --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \          
      --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

ジョブは thingOne で実行されます。

オプションの timeout-config パラメータは、各デバイスがジョブの実行を終了する必要のある時間を指定します。ジョブの実行ステータスが IN_PROGRESS に設定されると、タイマーが開始されます。タイマーが時間切れになるまでにジョブの実行ステータスが別の終了状態に設定されない場合は、TIMED_OUT に設定されます。

進捗タイマーは更新できず、ジョブのすべての実行に適用されます。ジョブの実行がこの間隔より長時間、IN_PROGRESS 状態のままになると、ジョブの実行は失敗し、終了ステータス TIMED_OUT に切り替わります。AWS IoT は MQTT 通知も発行します。

ジョブロールアウトと中止に関する設定の作成の詳細については、「ジョブロールアウトと中止設定」を参照してください。

注記

ジョブを作成するときに、Amazon S3 ファイルとして指定されたジョブドキュメントが取得されます。ジョブドキュメントを作成した後でジョブドキュメントのソースとして使用した Amazon S3 ファイルの内容を変更しても、ジョブのターゲットに送信されるものは変更されません。

ジョブの更新

ジョブを更新するには、UpdateJob コマンドを使用します。ジョブの description、presignedUrlConfig、jobExecutionsRolloutConfig、abortConfig および timeoutConfig の各フィールドを更新できます。


aws iot update-job  \
  --job-id 010  \
  --description "updated description" \
  --timeout-config inProgressTimeoutInMinutes=100 \
  --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}, \"maximumPerMinute\": 1000}}" \
  --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \          
  --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

詳細については、「ジョブのロールアウトと中止設定」を参照してください。

ジョブのキャンセル

ジョブをキャンセルするには､CancelJob コマンドを使用します。ジョブをキャンセルすると、AWS IoT により、そのジョブの新しいジョブの実行が開始されなくなります｡また、QUEUED 状態にあるジョブの実行をキャンセルします。AWS IoT は終了状態のジョブ実行をそのままにします。デバイスがすでにジョブを完了しているためです。ジョブ実行のステータスが IN_PROGRESS の場合、オプションの --force パラメータを使用しない限り、これも変更されません。

次のコマンドでは、ID が 010 のジョブをキャンセルする方法を示しています。


aws iot cancel-job --job-id 010

コマンドによって以下の出力が表示されます。


{
    "jobArn": "string",
    "jobId": "string",
    "description": "string"
}

ジョブをキャンセルすると、QUEUED 状態のジョブ実行がキャンセルされます。IN_PROGRESS 状態のジョブ実行は、オプションの --force パラメータを指定した場合にのみキャンセルされます。終了状態のジョブ実行はキャンセルされません。

警告

(--force パラメータを設定して) IN_PROGRESS 状態のジョブをキャンセルすると、実行中のすべてのジョブ実行がキャンセルされ、このジョブを実行しているデバイスでジョブ実行ステータスを更新することができなくなります。キャンセルするジョブを実行している各デバイスが有効な状態に必ず戻ることができるように注意してください。

キャンセルされたジョブの状態、あるいはそのジョブ実行のいずれか 1 つの状態に結果整合性があります。AWS IoT は、可能な限り早急にデバイスに対してそのジョブに対する QUEUED ジョブの実行および新しいジョブ実行のスケジュールを停止します。ジョブの実行ステータスを CANCELED に変更するには、デバイスの数やその他の要因によっては時間がかかることがあります。

AbortConfig オブジェクトによって定義された基準を満たすため、ジョブがキャンセルされた場合、サービスにより comment および reasonCode フィールドに自動的に値が入力されます。カスタマーは、自らジョブをキャンセルしたときの reasonCode に対して独自の値を作成できます。

ジョブ実行をキャンセルする

デバイスでジョブ実行をキャンセルするには、CancelJobExecution コマンドを使用します。QUEUED 状態にあるジョブの実行をキャンセルします。進行中のジョブ実行をキャンセルするには、--force パラメータを使用する必要があります。

次のコマンドでは、myThing で実行されている 010 ジョブのジョブ実行をキャンセルする方法を示しています。


aws iot cancel-job-execution --job-id 010 --thing-name myThing

コマンドは出力を表示しません。

QUEUED 状態にあるジョブの実行をキャンセルします。IN_PROGRESS 状態のジョブ実行は、オプションの --force パラメータを指定した場合にのみキャンセルされます。終了状態のジョブ実行をキャンセルすることはできません。

警告

IN_PROGRESS 状態のジョブ実行をキャンセルすると、そのデバイスでジョブ実行ステータスを更新できなくなります。デバイスが有効な状態に必ず戻ることができるように注意してください。

ジョブ実行が終了状態にあるか、ジョブ実行が IN_PROGRESS 状態にあり、--force パラメータが true に設定されていない場合に、このコマンドによって InvalidStateTransitionException になります。

キャンセルされたジョブ実行のステータスは結果整合性があります。ジョブ実行のステータスの CANCELED への変更は、さまざまな要因によっては時間がかかることがあります。

ジョブを削除する

ジョブおよびジョブ実行を削除するには、DeleteJob コマンドを使用します。デフォルトでは、終了状態 (SUCCEEDED または CANCELED) にあるジョブのみが削除できます。他の場合は、例外が発生します。ただし、force パラメータが true に設定されている場合のみ、IN_PROGRESS 状態のジョブを削除できます。

ジョブを削除するには、次のコマンドを実行します。


aws iot delete-job --job-id 010 --force|--no-force

コマンドは出力を表示しません。

警告

IN_PROGRESS 状態のジョブを削除すると、ジョブをデプロイしているデバイスはジョブ情報にアクセスすることもジョブ実行ステータスを更新することもできなくなります。削除されたジョブをデプロイしている各デバイスが有効な状態に必ず戻ることができるように注意してください。

ジョブに作成されたジョブ実行の数およびその他の要因に応じて、ジョブの削除には少し時間がかかる場合があります。ジョブの削除中、そのジョブのステータスは DELETION_IN_PROGRESS として表示されます。ステータスが既に DELETION_IN_PROGRESS のジョブを削除あるいはキャンセルしようとすると、エラーになります。

同時に 10 個のジョブのみが DELETION_IN_PROGRESS ステータスになることができます。それ以外の場合は、LimitExceededException が発生します。

ジョブドキュメントの取得

ジョブのジョブドキュメントを取得するには、GetJobDocument コマンドを使用します。ジョブドキュメントは、デバイスによって実行されるリモートオペレーションの説明です。

ジョブドキュメントを取得するには、次のコマンドを実行します。


aws iot get-job-document --job-id 010

次のコマンドは、指定したジョブのジョブドキュメントを返します。


{
    "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/job-test-bucket/datafile}\"\n}"
}

注記

このコマンドを使用してジョブドキュメントを取得すると、プレースホルダー URL は署名付き Amazon S3 URL に置き換えられません。デバイスが GetPendingJobExecutions API オペレーションを呼び出すときに、プレースホルダー URL は、ジョブドキュメント内の署名付き Amazon S3 URL に置き換えられます。

ジョブのリスト表示

AWS アカウント内のすべてのジョブのリストを取得するには、ListJobs コマンドを使用ます。ジョブデータとジョブ実行データは、期間限定で保持されます。次のコマンドを実行して、AWS アカウントのすべてのジョブを一覧表示します。


aws iot list-jobs

このコマンドは、ジョブステータスでソートされたアカウント内のすべてのジョブを返します。


{
    "jobs": [
        {
            "status": "IN_PROGRESS", 
            "lastUpdatedAt": 1486687079.743, 
            "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", 
            "createdAt": 1486687079.743, 
            "targetSelection": "SNAPSHOT",
            "jobId": "013"
        }, 
        {
            "status": "SUCCEEDED", 
            "lastUpdatedAt": 1486685868.444, 
            "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", 
            "createdAt": 1486685868.444, 
            "completedAt": 148668789.690,
            "targetSelection": "SNAPSHOT",
            "jobId": "012"
        }, 
        {
            "status": "CANCELED", 
            "lastUpdatedAt": 1486678850.575, 
            "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", 
            "createdAt": 1486678850.575, 
            "targetSelection": "SNAPSHOT",
            "jobId": "011"
        }
    ]
}

ジョブの説明

ジョブのステータスを取得するには、DescribeJob コマンドを実行します。次のコマンドでは、ジョブの説明を表示する方法を示しています。


$ aws iot describe-job --job-id 010

このコマンドは、指定されたジョブのステータスを返します。以下に例を示します。


{
    "documentSource": "https://s3.amazonaws.com/job-test-bucket/job-document.json", 
    "job": {
        "status": "IN_PROGRESS", 
        "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", 
        "targets": [
            "arn:aws:iot:us-east-1:123456789012:thing/myThing"
        ], 
        "jobProcessDetails": {
            "numberOfCanceledThings": 0, 
            "numberOfFailedThings": 0,
            "numberOfInProgressThings": 0,
            "numberOfQueuedThings": 0,
            "numberOfRejectedThings": 0,
            "numberOfRemovedThings": 0,
            "numberOfSucceededThings": 0,
            "numberOfTimedOutThings": 0,
            "processingTargets": [
                arn:aws:iot:us-east-1:123456789012:thing/thingOne, 
                arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, 
                arn:aws:iot:us-east-1:123456789012:thing/thingTwo, 
                arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo 
            ]
        }, 
        "presignedUrlConfig": {
            "expiresInSec": 60, 
            "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole"
        }, 
        "jobId": "010", 
        "lastUpdatedAt": 1486593195.006, 
        "createdAt": 1486593195.006,
        "targetSelection": "SNAPSHOT",
        "jobExecutionsRolloutConfig": { 
            "exponentialRate": { 
                "baseRatePerMinute": integer,
                "incrementFactor": integer,
                "rateIncreaseCriteria": { 
                    "numberOfNotifiedThings": integer, // Set one or the other
                    "numberOfSucceededThings": integer // of these two values.
                },
            "maximumPerMinute": integer
         }
        },    
        "abortConfig": { 
            "criteriaList": [ 
                { 
                    "action": "string",
                    "failureType": "string",
                    "minNumberOfExecutedThings": integer,
                    "thresholdPercentage": integer
                }
            ]
        },
        "timeoutConfig": { 
           "inProgressTimeoutInMinutes": number
          }
    }
}

ジョブ実行リスト

特定のデバイス上で実行されているジョブは、ジョブ実行オブジェクトによって表されます。ジョブのすべてのジョブ実行を一覧表示するには、ListJobExecutionsForJob コマンドを実行します。ジョブの実行をリストする方法を次に示しています。


aws iot list-job-executions-for-job --job-id 010

このコマンドは、ジョブの実行リストを返します。


{
    "executionSummaries": [
    {
        "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", 
        "jobExecutionSummary": {
            "status": "QUEUED", 
            "lastUpdatedAt": 1486593196.378, 
            "queuedAt": 1486593196.378,
            "executionNumber": 1234567890
        }
    },
    {
        "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", 
        "jobExecutionSummary": {
            "status": "IN_PROGRESS", 
            "lastUpdatedAt": 1486593345.659, 
            "queuedAt": 1486593196.378,
            "startedAt": 1486593345.659,
            "executionNumber": 4567890123
        }
    }
    ]
}

モノのジョブ実行リスト

モノのジョブ実行をすべて一覧表示するには、ListJobExecutionsForThing コマンドを実行します。モノのジョブの実行をリストする方法を次に示しています。


aws iot list-job-executions-for-thing --thing-name thingOne

このコマンドは、指定されたモノの実行中または実行済みのジョブの実行リストを返します。


{
    "executionSummaries": [
    {
        "jobExecutionSummary": {
            "status": "QUEUED", 
            "lastUpdatedAt": 1486687082.071, 
            "queuedAt": 1486687082.071,
            "executionNumber": 9876543210
        }, 
        "jobId": "013"
    }, 
    {
        "jobExecutionSummary": {
            "status": "IN_PROGRESS",
            "startAt": 1486685870.729, 
            "lastUpdatedAt": 1486685870.729, 
            "queuedAt": 1486685870.729,
            "executionNumber": 1357924680
        }, 
        "jobId": "012"
    }, 
    {
        "jobExecutionSummary": {
            "status": "SUCCEEDED", 
            "startAt": 1486678853.415,
            "lastUpdatedAt": 1486678853.415, 
            "queuedAt": 1486678853.415,
            "executionNumber": 4357680912
        }, 
        "jobId": "011"
    }, 
    {
        "jobExecutionSummary": {
            "status": "CANCELED",
            "startAt": 1486593196.378,
            "lastUpdatedAt": 1486593196.378, 
            "queuedAt": 1486593196.378,
            "executionNumber": 2143174250
        }, 
        "jobId": "010"
    }
    ]
}

ジョブ実行の説明

ジョブ実行のステータスを取得するには、DescribeJobExecution コマンドを実行します。ジョブの実行を識別するために、ジョブ ID とモノの名前、またオプションで実行番号を指定する必要があります。ジョブ実行を記述する方法を次に示しています。


aws iot describe-job-execution --job-id 017 --thing-name thingOne

コマンドは JobExecution を返します。以下に例を示します。


{
    "execution": {
        "jobId": "017", 
        "executionNumber": 4516820379,
        "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", 
        "versionNumber": 123,
        "createdAt": 1489084805.285, 
        "lastUpdatedAt": 1489086279.937, 
        "startedAt": 1489086279.937, 
        "status": "IN_PROGRESS",
        "approximateSecondsBeforeTimedOut": 100,
        "statusDetails": {
            "status": "IN_PROGRESS", 
            "detailsMap": {
                "percentComplete": "10"
            }
        }
    }
}

ジョブ実行を削除する

ジョブ実行を削除するには、DeleteJobExecution コマンドを実行します。ジョブの実行を識別するために、ジョブ ID、モノの名前、および実行番号を指定する必要があります。ジョブ実行を削除する方法を次に示しています。


aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force

コマンドは出力を表示しません。

デフォルトでは、ジョブ実行のステータスは QUEUED または終了状態 (SUCCEEDED、FAILED、REJECTED、TIMED_OUT、REMOVED または CANCELED) である必要があります。それ以外の場合は、エラーが発生します。IN_PROGRESS 状態のジョブ実行を削除するには、force パラメータを true に設定できます。

警告

ステータスが IN_PROGRESS のジョブ実行を削除すると、ジョブを実行しているデバイスはジョブ情報にアクセスする、ジョブ実行ステータスを更新することはできません。デバイスが有効な状態に必ず戻ることができるように注意してください。

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

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

ドキュメントの表記規則

コンソールを使用してジョブを作成および管理します。

ジョブテンプレート