AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

创建和管理作业 (CLI)

本节介绍如何创建和管理作业。

创建作业

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

使用作业进行代码签名

如果您使用 AWS IoT 的代码签名,则必须启动代码签名作业并将输出包括在您的作业文档中。使用 start-signing-job 命令创建代码签名作业。start-signing-job 将返回作业 ID。使用 describe-signing-job 命令获取存储签名的 Amazon S3 位置。然后,您可以从 Amazon S3 中下载签名。有关代码签名作业的更多信息,请参阅 AWS IoT 的代码签名

您的作业文档必须包含代码文件的预签名 URL 占位符和使用 start-signing-job 命令放置在 Amazon S3 存储桶中的 JSON 签名输出,它们括在 codesign 元素中:

{ "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", "codesign": { "rawPayloadSize": <image-file-size>, "signature": <signature>, "signatureAlgorithm": <signature-algorithm>, "payloadLocation": { "s3": { "bucketName": <my-s3-bucket>, "key": <my-code-file>, "version": <code-file-version-id> } } } }

使用作业文档创建作业

以下命令说明如何使用存储在 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

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

进行中计时器无法更新,将应用到该作业的全部作业执行。只要作业执行保持在 IN_PROGRESS 状态的时间长度超过了此间隔,作业执行将失败,并切换为最终 TIMED_OUT 状态。AWS IoT 还将发布 MQTT 通知。

有关创建作业推出和中止相关配置的更多信息,请参阅作业推出和中止配置

注意

在您创建作业时,系统会检索指定为 Amazon S3 文件的作业文档。在创建作业后,更改用作作业文档源的 Amazon S3 文件的内容时不会更改发送到作业目标的内容。

更新作业

可使用 UpdateJob 命令更新作业。您可以更新作业的 descriptionpresignedUrlConfigjobExecutionsRolloutConfigabortConfigtimeoutConfig 字段。

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 状态的作业执行。如果您指定了可选的 --force 参数,则将取消处于 IN_PROGRESS 状态的作业执行。不会取消处于最终状态的作业执行。

警告

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

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

如果作业因满足 AbortConfig 对象所定义的条件而被取消,服务会为 commentreasonCode 字段添加自动填充值。当作业取消由用户驱动时,您可以为 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 命令删除作业及其作业执行。默认情况下,您只能删除处于最终状态(SUCCEEDEDCANCELED)的作业。否则,会出现异常。如果 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/job-test-bucket/datafile}\"\n}" }

注意

在使用此命令检索作业文档时,占位符 URL 不会替换为预签名 Amazon S3 URL。在设备调用 GetPendingJobExecutions MQTT API 时,占位符 URL 将替换为作业文档中的预签名 Amazon S3 URL。

列出作业

可使用 ListJobs 命令获取 AWS 账户中的所有作业的列表。将在 90 天后清除作业数据和作业执行数据。运行以下命令来列出您的 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 或处于最终状态(SUCCEEDEDFAILEDREJECTEDTIMED_OUTREMOVEDCANCELED)。否则将出错。要删除状态为 IN_PROGRESS 的作业执行,您可以将 force 参数设置为 true

警告

删除状态为 IN_PROGRESS 的作业执行后,执行该作业的设备将无法访问作业信息或更新作业执行状态。请谨慎使用,并且确保设备能够恢复到有效状态。