创建任务更新任务取消任务取消任务执行删除任务获取任务文档列出任务描述任务列出任务的执行列出事物的任务执行描述任务执行删除任务执行

使用 Amazon CLI 创建和管理任务。

本部分介绍如何创建和管理任务。

创建任务

要创建 Amazon IoT 任务，使用 CreateJob 命令。任务将进行排队以便在您指定的目标 (事物或事物组) 上执行。要创建 Amazon IoT 任务，您需要一个任务文档，该文档可包含在请求的正文中或作为指向 Amazon S3 文档的链接。如果任务包含使用预签名的 Amazon S3 URL 下载文件，则您需要一个 IAM 角色 Amazon Resource Name (ARN)，它具有下载文件的权限并会向 Amazon IoT Jobs 服务授予代入角色的权限。

使用任务进行代码签名

如果您使用 Amazon 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 中下载签名。有关代码签名任务的更多信息，请参阅 Amazon IoT 的代码签名。

您的任务文档必须包含代码文件的预签名 URL 占位符和使用以下内容放置在 Amazon S3 存储桶中的 JSON 签名输start-signing-job出：


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

使用任务文档创建任务

以下命令说明了如何使用存储在 Amazon S3 存储桶 (j obBucket) 中的任务文档 (j ob-document.js on) 和具有从 Amazon S3 下载文件的权限的角色 (S 3DownloadRole) 创建任务。


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 状态。Amazon 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 命令。取消任务将使 Amazon IoT 停止为任务推出任何新的任务执行。这还将取消处于 QUEUED 状态的任何任务执行。Amazon IoT 会将任何任务执行的最终状态保持不变，因为设备已完成任务。如果任务执行的状态为 IN_PROGRESS，它也将保持不变，除非您使用可选的 --force 参数。

以下命令说明如何取消 ID 为 010 的任务。


aws iot cancel-job --job-id 010

该命令将显示以下输出：


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

当您取消任务时，将取消处于 QUEUED 状态的任务执行。如果您指定了可选的 --force 参数，将取消处于 IN_PROGRESS 状态的任务执行。不会取消处于最终状态的任务执行。

警告

取消处于 IN_PROGRESS 状态的任务（通过设置 --force 参数）将取消正在进行的任何任务执行，并且会导致运行该任务的设备无法更新任务执行状态。请谨慎使用，并且确保执行已取消的任务的每个设备能够恢复到有效状态。

已取消任务或其某个任务执行的状态最终是一致的。Amazon IoT 将尽快停止将该任务的新任务执行和 QUEUED 任务执行安排给设备。将任务执行的状态更改为 CANCELED 可能需要一些时间，具体取决于设备数和其它因素。

如果任务因满足 AbortConfig 对象所定义的条件而被取消，服务会为 comment 和 reasonCode 字段添加自动填充值。当任务取消由用户驱动时，您可以为 reasonCode 创建自己的值。

取消任务执行

要取消设备上的任务执行，使用 CancelJobExecution 命令。它将取消处于 QUEUED 状态的任务执行。如果要取消正在进行的任务执行，您必须使用 --force 参数。

以下命令说明如何取消在 myThing 上运行的任务 010 的任务执行。


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

该命令不显示任何输出。

将取消处于 QUEUED 状态的任务执行。如果您指定了可选的 --force 参数，则将取消处于 IN_PROGRESS 状态的任务执行。无法取消处于最终状态的任务执行。

警告

取消处于 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。在设备调用 GetPendingJobExecutionsAPI 时：

列出任务

要获取 Amazon Web Services 账户中的所有任务的列表，使用 ListJobs 命令。任务数据和任务执行数据将在有限的时间内保留。运行以下命令来列出您的Amazon Web Services 账户中的所有任务：


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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

使用控制台创建和管理任务

任务模板