本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 建立和管理任務 AWS CLI 本節說明如何建立和管理任務。 ## 建立任務 若要建立 AWS IoT 任務，請使用 **CreateJob**命令。任務會排入所指定目標 (物件或物件群組) 的執行佇列。若要建立 AWS IoT 任務，您需要可以包含在請求內文中的任務文件，或做為 Amazon S3 文件的連結。如果任務包含使用預先簽章的 Amazon S3 URLs 下載檔案，您需要 IAM 角色 Amazon Resource Name (ARN)，其具有下載檔案的許可，並授予 AWS IoT Jobs 服務擔任該角色的許可。 如需使用 API 命令或 輸入日期和時間時語法的詳細資訊 AWS CLI，請參閱[時間戳記](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp)。 ### 使用任務進行程式碼簽署 如果您使用 的程式碼簽署 AWS IoT，則必須啟動程式碼簽署任務，並在任務文件中包含輸出。這會取代任務文件中的程式碼簽署簽章預留位置，在使用**程式碼簽署設定檔**將其替換為已簽署程式碼檔案路徑之前，這個預留位置是必要的。程式碼簽署簽章預留位置將如下所示： ``` ${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id} ``` 使用 [start-signing-job](https://docs.aws.amazon.com/signer/latest/developerguide/api-startsigningjob.html) 命令來建立程式碼簽署任務。`start-signing-job` 會傳回任務 ID。若要取得存放簽章的 Amazon S3 位置，請使用 **describe-signing-job** 命令。然後，您可以從 Amazon S3 下載簽章。如需程式碼簽署任務的詳細資訊，請參閱[適用於 AWS IoT的程式碼簽署](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)。 您的任務文件必須包含程式碼檔的預先簽章 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/amzn-s3-demo-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 通知。 如需建立任務推展和中止組態的詳細資訊，請參閱[任務推展和中止組態](job-rollout-abort.html)。 **注意** 指定為 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}" ``` 如需詳細資訊，請參閱[任務推展和中止組態](job-rollout-abort.html)。 ## 取消任務 若要取消任務，請使用 **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` 參數) 的任務將取消任何進行中的任務執行，並導致正在執行任務的裝置無法更新任務執行狀態。請謹慎執行，並確認每個裝置所執行的已取消任務可以復原至有效狀態。 已取消任務或其其中一個任務執行的狀態最終是一致的。 會停止盡快將該任務的新任務執行和任務`QUEUED`執行 AWS IoT 排程到裝置。將任務執行的狀態變更為 `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/amzn-s3-demo-bucket/datafile}\"\n}" } ``` **注意** 在使用此命令擷取任務文件時，預留位置 URL 並不會被預先簽章的 Amazon S3 URL 取代。當裝置呼叫 [GetPendingJobExecutions](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) API 操作時，預留位置 URL 才會被任務文件中的預先簽章 Amazon S3 URL 取代。 ## 列出任務 若要取得 中所有任務的清單 AWS 帳戶，請使用 **ListJobs**命令。任務資料和任務執行資料會保留一段[有限的時間](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#job-limits)。執行下列命令來列出 中的所有任務 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/amzn-s3-demo-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 ``` 此命令會傳回 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html)。例如： ``` { "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` 的任務執行時，正在執行任務的裝置將無法存取任務資訊或更新任務執行狀態。請謹慎使用並確保裝置可以還原為有效狀態。