使用建立和管理任務 AWS CLI

焦點模式

使用建立和管理任務 AWS CLI - AWS IoT Core

建立任務更新任務取消任務取消任務執行刪除任務取得任務文件列出任務描述任務列出任務的執行列出物件的任務執行描述任務執行刪除任務執行

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

建立任務

若要建立 AWS IoT 任務，請使用 CreateJob命令。任務會排入所指定目標 (物件或物件群組) 的執行佇列。若要建立 AWS IoT 任務，您需要一個任務文件，該文件可以包含在請求內文中，或做為 Amazon S3 文件的連結。如果任務包含使用預先簽章的 Amazon S3 下載檔案URLs，您需要一個角色 Amazon Resource Name (ARN)，該IAM角色具有下載檔案的許可，並授予 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 儲存貯體 (job-document.json) 中的任務文件 (jobBucket) 以及具有從 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通知。

如需建立任務推展和中止組態的詳細資訊，請參閱任務推展和中止組態。

注意

指定為 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/amzn-s3-demo-bucket/datafile}\"\n}"
}

注意

當您使用此命令擷取任務文件時，預留位置URLs不會取代為預先簽章的 Amazon S3URLs。當裝置呼叫 GetPendingJobExecutionsAPI操作時，預留位置URLs會由任務文件中預先簽章URLs的 Amazon S3 取代。

列出任務

若要取得中所有任務的清單 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/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

此命令會傳回 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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

使用主控台建立和管理任務

任務範本

在本頁面

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定

使用建立和管理任務 AWS CLI

建立任務

使用任務進行程式碼簽署

使用任務文件建立任務

注意

更新任務

取消任務

警告

取消任務執行

警告

刪除任務

警告

取得任務文件

注意

列出任務

描述任務

列出任務的執行

列出物件的任務執行

描述任務執行

刪除任務執行

警告

在本頁面

Related resources

此頁面是否有幫助？

Related resources

下一個主題：

上一個主題：

需要協助？

選取您的 Cookie 偏好設定

使用 建立和管理任務 AWS CLI

建立任務

使用任務進行程式碼簽署

使用任務文件建立任務

注意

更新任務

取消任務

警告

取消任務執行

警告

刪除任務

警告

取得任務文件

注意

列出任務

描述任務

列出任務的執行

列出物件的任務執行

描述任務執行

刪除任務執行

警告

在本頁面

Related resources

此頁面是否有幫助？

Related resources

下一個主題：

上一個主題：

需要協助？

使用建立和管理任務 AWS CLI