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

管理任务

Jobs 是使用 Jobs HTTPS API、AWS Command Line Interface 或 AWS 开发工具包创建和管理的。有关这些工具的更多信息,请参阅任务管理和控制 APIAWS CLI 命令参考:iotAWS 开发工具包和工具

创建任务

CreateJob更多信息 (1)授予权限
CreateJob

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

更多信息 (1)

如果您有一个存储在名为 jobBucket 的 Amazon S3 存储桶中的名为 job-document.json 的文件,并且具有从 Amazon S3 下载文件的权限的角色名为 S3DownloadRole,则用于创建任务的 CLI 命令将类似于以下内容:

aws iot create-job \ --job-id 010 \ --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \ --document-source https://s3.amazonaws.com/jobBucket/job-document.json \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

如果您需要指定内联任务文档,可使用 --document 参数而非 --document-source 参数。

将按任务在 --targets 列表中的显示顺序发送任务并在目标上执行任务。例如,如果目标列表为:

[ 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 ]

则将在 thingOne 上执行任务,随后依次在 thinggroupOne 中的事物、thingTwothinggroupTwo 中的事物上执行。

注意

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

授予权限

在创建使用预签名 Amazon S3 URL 的任务时,您必须提供一个 IAM 角色 ARN 来授予从存储数据或更新的 Amazon S3 存储桶中下载文件的权限。该角色还必须向 AWS IoT 授予代入角色的权限。

要向 Jobs 授予代入角色的权限,请执行以下操作:

  1. 登录 AWS 管理控制台 并通过以下网址打开 IAM 控制台 https://console.amazonaws.cn/iam/

  2. 在左侧导航窗格中,选择 Roles

  3. 搜索您的角色,然后选择它。

  4. 选择 Trust Relationships 选项卡。

  5. 选择编辑信任关系按钮。

  6. 编辑信任关系页面上,将策略文档替换为以下 JSON:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] }
  7. 选择 Update Trust Policy

  8. 如果您的任务使用的任务文档是一个 Amazon S3 对象,请选择权限,然后使用以下 JSON 添加授予从您的 Amazon S3 存储桶下载文件的权限的策略:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::your_S3_bucket/*" } ] }

您可以选择性地指定预签名 URL 的超时值。有关更多信息,请参阅 CreateJob

取消任务

CancelJob更多信息 (2)
CancelJob

可使用 CancelJob 命令取消任务。取消任务将使 AWS IoT 停止为任务部署任何新的任务执行。这还将取消处于 QUEUED 状态的任何任务执行。IoT 会将处于最终状态的任何任务执行保持不变,因为设备已完成任务。如果任务执行的状态为 IN_PROGRESS,它也将保持不变,除非您使用可选的 --force 参数。

更多信息 (2)
aws iot cancel-job --job-id 010

该命令不显示任何输出。

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

警告

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

已取消任务或其某个任务执行的状态最终是一致的 – IoT 将停止计划新的任务执行,并且不会尽快将该任务的 QUEUED 任务执行提供给设备。不过,将任务执行的状态更改为 CANCELED 可能需要一些时间,具体取决于设备数和其他因素。

取消任务执行

CancelJobExecution更多信息 (3)
CancelJobExecution

可使用 CancelJobExecution 命令取消特定设备上的任务执行。它将取消状态为 QUEUED 的任务执行。如果您想要取消状态为 IN_PROGRESS 的任务执行,您必须使用 --force 参数。

更多信息 (3)
aws iot cancel-job-execution --job-id 010 --thing-name myThing

该命令不显示任何输出。

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

警告

取消状态为 IN_PROGRESS 的任务执行将导致设备无法更新任务执行状态。请谨慎使用,并且确保设备能够恢复到有效状态。

如果任务执行处于最终状态,或者任务执行的状态为 IN_PROGRESS 并且 --force 参数未设置为 true,则此命令将引发 InvalidStateTransitionException

已取消任务执行的状态最终是一致的 – 将任务执行的状态更改为 CANCELED 可能需要一些时间,具体取决于各种因素。

删除任务

DeleteJob更多信息 (3)
DeleteJob

可使用 DeleteJob 命令删除任务及其相关的任务执行。默认情况下,您只能删除处于最终状态 (“COMPLETED”或“CANCELED”) 的任务,否则会出现异常。但是,如果 force 参数设置为 true,您可以删除状态为“IN_PROGRESS”的任务。

更多信息 (3)
aws iot delete-job --job-id 010 --force|--no-force

该命令不显示任何输出。

警告

删除状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法访问任务信息或更新任务执行状态。请谨慎使用,并且确保执行已删除的任务的每个设备能够恢复到有效状态。

删除任务可能需要一些时间,具体取决于为该任务创建的任务执行的数量以及其他各种因素。正在删除任务时,任务的状态将显示为“DELETION_IN_PROGRESS”。尝试删除或取消其状态已为“DELETION_IN_PROGRESS”的任务将导致错误。

只能有 10 个任务的状态可以同时为“DELETION_IN_PROGRESS”,否则会出现 LimitExceededException。

获取任务文档

GetJobDocument更多信息 (4)
GetJobDocument

可使用 GetJobDocument 命令检索任务的任务文档。任务文档是对设备将执行的远程操作的描述。

更多信息 (4)
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。占位符 URL 将替换为在设备调用 GetPendingJobExecutions MQTT API 时返回的任务文档中的预签名 Amazon S3 URL。

列出任务

ListJobs更多信息 (5)
ListJobs

可使用 ListJobs 命令获取 AWS 账户中的所有任务的列表。请注意,任务数据和任务执行数据将在 90 天后被清除。

更多信息 (5)
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": "COMPLETED", "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更多信息 (6)
DescribeJob

可使用 DescribeJob 命令获取特定任务的状态。

更多信息 (6)
$ 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, "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" } }

列出任务的执行

ListJobExecutionsForJob更多信息 (7)
ListJobExecutionsForJob

在特定设备上运行的任务由任务执行对象表示。可使用 ListJobExecutionsForJob 命令列出任务的所有任务执行。

更多信息 (7)
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更多信息 (8)
ListJobExecutionsForThing

可使用 ListJobExecutionsForThing 命令列出正在事物上运行的所有任务执行。

更多信息 (8)
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_PROCESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "COMPLETED", "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更多信息 (9)
DescribeJobExecution

可使用 DescribeJobExecution 命令获取特定任务执行的状态。您可以指定任务 ID 和事物名称 (也可以选择指定执行编号) 来标识任务执行。

任务的执行状态必须为 QUEUEDIN_PROGRESS

更多信息 (9)
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", "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }

删除任务执行

DeleteJobExecution更多信息 (10)
DeleteJobExecution

可使用 DeleteJobExecution 命令删除特定任务执行。您必须指定任务 ID 和事物名称 (也可以选择指定执行编号) 来标识任务执行。

更多信息 (10)
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force

该命令不显示任何输出。

默认情况下,任务执行必须处于“QUEUED”状态或处于最终状态 (SUCCEEDEDFAILEDREJECTEDREMOVEDCANCELED),否则会出现错误。否则,您可以将 force 参数设置为 true 来删除状态为 IN_PROGRESS 的任务执行。

警告

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

任务事件

当任务已完成、已取消或已删除时,以及设备在执行任务时报告成功或失败时,AWS IoT 任务将向预留主题发布 MQTT 消息。

由于任务取消和删除需要一些时间,所以发送两条消息来指示请求的开始和结束。例如,当取消请求开始时,系统会向 $aws/events/job/jobID/cancellation_in_progress 主题发送一条消息;当取消请求完成时,系统会向 $aws/events/job/jobID/canceled 主题发送一条消息。任务删除请求的过程与之相似。管理和监控应用程序可以通过订阅这些主题来跟踪任务的状态。

有关发布和订阅 MQTT 主题的更多信息,请参阅AWS IoT 的消息代理

job completed/canceled/deleted/cancellation_in_progress/deletion_in_progress更多信息 (12)
job completed/canceled/deleted/cancellation_in_progress/deletion_in_progress

当任务已完成、已取消和已删除时,AWS IoT 任务会在 MQTT 主题上发布消息:

  • $aws/events/job/jobID/completed

  • $aws/events/job/jobID/canceled

  • $aws/events/job/jobID/deleted

  • $aws/events/job/jobID/cancellation_in_progress

  • $aws/events/job/jobID/deletion_in_progress

更多信息 (12)

“已完成”消息包含以下示例负载:

{ "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation", "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } }

“已取消”消息包含以下示例负载:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "forceCanceled": true, "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation", "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } }

“已删除”消息包含以下示例负载:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deleted", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }

“cancellation_in_progress”消息包含以下示例负载:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "cancellation_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELLATION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }

“deletion_in_progress”消息包含以下示例负载:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deletion_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }
任务执行最终状态更多信息 (13)
任务执行最终状态

当设备将任务执行更新为最终状态时,AWS IoT Jobs 会发布消息:

  • $aws/events/jobExecution/jobID/succeeded

  • $aws/events/jobExecution/jobID/failed

  • $aws/events/jobExecution/jobID/rejected

  • $aws/events/jobExecution/jobID/canceled

  • $aws/events/jobExecution/jobID/removed

  • $aws/events/jobExecution/jobID/deleted

更多信息 (13)

消息包含以下示例负载:

{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed|deleted", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED|DELETED", "statusDetails": { "key": "value" } }

注意

当任务已删除时,消息中的 operation 字段将显示这个,但 status 字段将反映删除之前的任务执行状态。