使用 AWS CLI 建立和管理任務。 - AWS IoT Core
建立任務更新任務取消任務取消任務執行刪除任務取得任務文件列出任務描述任務列出任務的執行列出物件的任務執行描述任務執行刪除任務執行

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 AWS CLI 建立和管理任務。

本節說明如何建立和管理任務。

建立任務

若要建立 AWS IoT 任務，請使用 CreateJob 命令。任務會排入所指定目標 (物件或物件群組) 的執行佇列。若要建立 AWS IoT 任務，您需要可以加入請求本文中或作為 Amazon S3 文件連結的任務文件。如果任務包含使用預先簽章的 Amazon S3 URL 下載檔案，您就需要 IAM 角色 Amazon 資源名稱 (ARN) 來得到檔案下載許可，並授予 AWS IoT 任務服務許可來擔任此角色。

如需使用 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 參數。處於結束狀態的任務執行不會取消。

警告

取消狀態為 IN_PROGRESS (透過設定 --force 參數) 的任務將取消任何進行中的任務執行，並導致正在執行任務的裝置無法更新任務執行狀態。請謹慎執行，並確認每個裝置所執行的已取消任務可以復原至有效狀態。

取消的任務或其中一項任務執行的狀態具有最終一致性，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) 的任務。否則會發生例外狀況。不過，只在 IN_PROGRESS 參數設定為 force 時，您才能刪除處於 true 狀態的任務。

若要刪除任務，請執行下列命令：

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 的任務執行時，正在執行任務的裝置將無法存取任務資訊或更新任務執行狀態。請謹慎使用並確保裝置可以還原為有效狀態。