使用创建和管理作业 Amazon CLI - Amazon IoT Core
创建任务更新任务取消任务取消任务执行删除任务获取任务文档列出任务描述任务列出任务的执行列出事物的任务执行描述任务执行删除任务执行
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用创建和管理作业 Amazon CLI

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

创建任务

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

有关使用 API 命令或输入日期和时间时语法的更多信息Amazon CLI，请参阅时间戳。

使用任务进行代码签名

如果您使用代码签名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 占位符和使用 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状态。 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）的任务。否则，会出现异常。但是，仅当 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/amzn-s3-demo-bucket/datafile}\"\n}"
}
注意

当您使用此命令检索任务文档时，占位符 URLs不会被预签名的 Amazon S3 所取代。 URLs当设备调用 GetPendingJobExecutionsAPI 操作时，占位符将替换 URLs 为任务文档 URLs 中预签名的 Amazon S3。

列出任务

要获取您中所有任务的列表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/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 的任务执行后，执行该任务的设备将无法访问任务信息或更新任务执行状态。请谨慎使用，并且 确保 设备能够恢复到有效状态。