本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 任务设备 MQTT API 操作 可以通过将 MQTT 消息发布到[用于 Jobs 命令的保留主题](reserved-topics.md#reserved-topics-job)来发出任务设备命令。 您的设备端客户端必须订阅这些命令的响应消息主题。如果您使用 AWS IoT 设备客户端，您的设备将自动订阅响应主题。这意味着消息代理将向发布命令消息的客户端发布响应消息主题，无论您的客户端是否订阅了该响应消息主题。这些响应消息不会通过消息代理，也无法由其它客户端或规则订阅。 订阅实例集监控解决方案的任务和 `jobExecution` 事件主题时，首先启用[任务和任务执行事件](iot-events.md)以接收云端的任何事件。Job 进度消息，这些消息通过消息代理处理并且可以由 AWS IoT 规则使用，将发布为 [任务事件](events-jobs.md)。由于消息代理会发布响应消息，即使没有明确订阅响应消息也是如此，因此必须配置您的客户端以接收和标识其接收的消息。*thingName*在客户端对消息采取行动之前，您的客户端还必须确认传入消息主题中的是否适用于客户端的事物名称。 **注意** 为响应 MQTT Jobs API 命令消息而 AWS IoT 发送的消息将从您的账户中扣款，无论您是否明确订阅了这些消息。 下面显示了 MQTT API 操作及其请求和响应语法。所有 MQTT API 操作都具有以下参数： clientToken 用于将请求和响应关联起来的可选客户端令牌。在此处输入任意值，它将反映在响应中。 `timestamp` 发送消息的时间（用从纪元开始的秒数表示）。 ## GetPendingJobExecutions 针对指定的事物，获取未处于最终状态的所有任务的列表。 要调用此 API，请在 `$aws/things/thingName/jobs/get` 上发布消息。 请求负载： ``` { "clientToken": "string" } ``` 消息代理将发布 `$aws/things/thingName/jobs/get/accepted` 和 `$aws/things/thingName/jobs/get/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。 响应负载： ``` { "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ], "timestamp" : 1489096425069, "clientToken" : "client-001" } ``` 其中，`inProgressJobs` 和 `queuedJobs` 返回状态为 `IN_PROGRESS` 或 `QUEUED` 的 [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) 对象的列表。 ## StartNextPendingJobExecution 获取并启动事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。 + 首先返回状态为 `IN_PROGRESS` 的所有任务执行。 + 按任务执行的排队顺序返回这些任务执行。在任务的目标组中添加或移除某个事物时，请确认任何新的任务执行与现有任务执行相比的推出顺序。 + 如果下一个待处理任务执行的状态为 `QUEUED`，则其状态将更改为 `IN_PROGRESS`，并且任务执行的状态详细信息将设定为指定内容。 + 如果下一个待处理任务执行已处于 `IN_PROGRESS` 状态，则不会更改其状态详细信息。 + 如果没有待处理的任务执行，则响应不包括 `execution` 字段。 + （可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值来创建步骤计时器。如果您没有通过运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。 要调用此 API，请在 `$aws/things/thingName/jobs/start-next` 上发布消息。 请求负载： ``` { "statusDetails": { "string": "job-execution-state" ... }, "stepTimeoutInMinutes": long, "clientToken": "string" } ``` `statusDetails` 描述任务执行状态的名称-值对的集合。如果未指定，则 `statusDetails` 保持不变。 `stepTimeOutInMinutes` 指定此设备完成该任务执行所具有的时间。如果任务执行状态未在此计时器过期或者重置计时器（通过调用 `UpdateJobExecution`，将状态设置为 `IN_PROGRESS`，并在字段 `stepTimeoutInMinutes` 中指定新的超时值）之前设置为最终状态，则任务执行状态将设置为 `TIMED_OUT`。设置此超时不会影响在创建任务时（`CreateJob`，使用 `timeoutConfig` 字段）可能指定的任务执行超时。 此参数的有效值范围为 1 到 10080（1 分钟到 7 天）。值为 -1 也是有效的，它将取消当前的步进计时器（由之前的使用创建 UpdateJobExecutionRequest）。 消息代理将发布 `$aws/things/thingName/jobs/start-next/accepted` 和 `$aws/things/thingName/jobs/start-next/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。 响应负载： ``` { "execution" : JobExecutionData, "timestamp" : timestamp, "clientToken" : "string" } ``` 其中，`execution` 是 [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 对象。例如： ``` { "execution" : { "jobId" : "022", "thingName" : "MyThing", "jobDocument" : "< contents of job document >", "status" : "IN_PROGRESS", "queuedAt" : 1489096123309, "lastUpdatedAt" : 1489096123309, "versionNumber" : 1, "executionNumber" : 1234567890 }, "clientToken" : "client-1", "timestamp" : 1489088524284, } ``` ## DescribeJobExecution 获取有关任务执行的详细信息。 您可以将 `jobId` 设置为 `$next` 以返回事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。 要调用此 API，请在 `$aws/things/thingName/jobs/jobId/get` 上发布消息。 请求负载： ``` { "jobId" : "022", "thingName" : "MyThing", "executionNumber": long, "includeJobDocument": boolean, "clientToken": "string" } ``` `thingName` 与设备关联的事物的名称。 `jobId` 创建此任务时向其分配的唯一标识符。 或使用 `$next` 返回事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。在此情况下，首先返回状态为 `IN_PROGRESS` 的所有任务执行。按任务执行的创建顺序返回这些执行。 `executionNumber` （可选）标识设备上的任务执行的数字。如果未指定，则返回最新的任务执行。 `includeJobDocument` （可选）除非设置为 `false`，否则响应将包含任务文档。默认值为 `true`。 消息代理将发布 `$aws/things/thingName/jobs/jobId/get/accepted` 和 `$aws/things/thingName/jobs/jobId/get/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。 响应负载： ``` { "execution" : JobExecutionData, "timestamp": "timestamp", "clientToken": "string" } ``` 其中，`execution` 是 [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 对象。 ## UpdateJobExecution 更新任务执行的状态。（可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值创建步骤计时器。如果您没有通过再次运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。 要调用此 API，请在 `$aws/things/thingName/jobs/jobId/update` 上发布消息。 请求负载： ``` { "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "executionNumber": long, "includeJobExecutionState": boolean, "includeJobDocument": boolean, "stepTimeoutInMinutes": long, "clientToken": "string" } ``` `status` 任务执行的新状态（`IN_PROGRESS`、`FAILED`、`SUCCEEDED`，或 `REJECTED`）。这必须在每次更新时指定。 `statusDetails` 描述任务执行状态的名称-值对的集合。如果未指定，则 `statusDetails` 保持不变。 `expectedVersion` 任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在 AWS IoT 作业服务中的任务执行版本不匹配，则更新会因`VersionMismatch`错误而被拒绝。还会返回包含当前任务执行状态数据的 [ErrorResponse](jobs-api.md#jobs-mqtt-error-response)。（这样就不必执行单独的 `DescribeJobExecution` 请求以获取任务执行状态数据。） `executionNumber` （可选）标识设备上的任务执行的数字。如果未指定，则使用最新的任务执行。 `includeJobExecutionState` （可选）在包含此参数且设置为 `true` 时，响应将包含 `JobExecutionState` 字段。默认值为 `false`。 `includeJobDocument` （可选）在包含此参数且设置为 `true` 时，响应将包含 `JobDocument`。默认值为 `false`。 `stepTimeoutInMinutes` 指定此设备完成该任务执行所具有的时间。如果在该计时器到期之前或在重置计时器之前，任务执行状态未设置为最终状态，则任务执行状态设置为 `TIMED_OUT`。设置或重置此超时不会影响在创建任务时可能已指定的任务执行超时。 消息代理将发布 `$aws/things/thingName/jobs/jobId/update/accepted` 和 `$aws/things/thingName/jobs/jobId/update/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。 响应负载： ``` { "executionState": JobExecutionState, "jobDocument": "string", "timestamp": timestamp, "clientToken": "string" } ``` `executionState` 一个 [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state) 对象。 `jobDocument` 一个[任务文档](key-concepts-jobs.md)对象。 在 MQTT 响应中，`jobDocument` 字段是一个 JSON 对象。在 HTTP 响应中，它是 JSON 对象的字符串表示形式。 `timestamp` 发送消息的时间（用从纪元 开始的秒数表示）。 `clientToken` 用于将请求和响应关联起来的客户端令牌。 使用 MQTT 协议时，您还可以执行以下更新： ## JobExecutionsChanged 在事物的待处理任务执行列表中添加或删除任务执行时发送。 使用 主题： `$aws/things/thingName/jobs/notify` 消息负载： ``` { "jobs" : { "JobExecutionState": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ] }, "timestamp": timestamp } ``` ## NextJobExecutionChanged 当存在对事物的待处理任务执行列表中的下一个任务执行的更改（使用 `jobId` `$next` 为 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 定义）时发送。当下一个任务的执行详细信息发生更改时不会发送此消息，而仅在将由 `DescribeJobExecution`（`jobId` 为 `$next`）返回的下一个任务发生更改时发送。考虑状态为 `QUEUED` 的任务执行 J1 和 J2。J1 是待处理任务执行列表中的下一个待处理任务执行。如果 J2 的状态更改为 `IN_PROGRESS`，而 J1 的状态保持不变，则将发送此通知，并且此通知包含 J2 的详细信息。 使用 主题： `$aws/things/thingName/jobs/notify-next` 消息负载： ``` { "execution" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html), "timestamp": timestamp, } ```