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

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

取消任务

CancelJob更多信息 (2)
CancelJob

可使用 CancelJob 命令取消任务。取消任务将使 AWS IoT 停止为任务部署任何新的任务执行。这还将取消处于 QUEUED 状态的任何任务执行。IoT 会将任何任务执行保留为 IN_PROGRESS 状态或将最终状态保持不变,因为设备已在执行任务或已完成任务。

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

该命令不显示任何输出。

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

获取任务文档

GetJobDocument更多信息 (3)
GetJobDocument

可使用 GetJobDocument 命令检索任务的任务文档。

更多信息 (3)
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更多信息 (4)
ListJobs

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

更多信息 (4)
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更多信息 (5)
DescribeJob

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

更多信息 (5)
$ 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更多信息 (6)
ListJobExecutionsForJob

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

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

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

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

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

任务的执行状态必须为 QUEUEDIN_PROGRESS

更多信息 (8)
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", "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }

任务事件

当任务待处理、已完成或已取消时,或者当设备在执行任务时报告成功或失败时,Jobs 还将发布到 MQTT 协议上的预留主题。设备或管理和监控应用程序可以通过订阅这些主题来跟踪任务的状态。

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

任务待处理更多信息 (9)
任务待处理

当某个事物的待处理任务执行列表中添加或删除了任务时,或者对列表中任务的顺序有更改时,AWS IoT Jobs 会在 MQTT 主题上发布消息:

  • $aws/things/thingName/jobs/notify

  • $aws/things/thingName/jobs/notify-next

更多信息 (9)

消息包含以下示例负载:

$aws/things/thingName/jobs/notify

{ "jobs" : { "JobExecutionState": [ JobExecutionSummary ... ], }, "timestamp": timestamp, }

$aws/things/thingName/jobs/notify-next

{ "execution" : JobExecutionData, "timestamp": timestamp, }
任务已完成/已取消更多信息 (10)
任务已完成/已取消

当任务已完成或已取消时,AWS IoT Jobs 会在 MQTT 主题上发布消息:

  • $aws/events/job/jobID/completed

  • $aws/events/job/jobID/canceled

更多信息 (10)

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

{ "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, "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", "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 }
任务执行最终状态更多信息 (11)
任务执行最终状态

当设备将任务执行更新为最终状态时,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/#

更多信息 (11)

消息包含以下示例负载:

{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed", "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", "statusDetails": { "key": "value" } }