任务设备 MQTT API 操作

可以通过将 MQTT 消息发布到用于 Jobs 命令的保留主题来发出任务设备命令。

您的设备端客户端必须订阅这些命令的响应消息主题。如果您使用 Amazon IoT 设备客户端，您的设备将自动订阅响应主题。这意味着消息代理将向发布命令消息的客户端发布响应消息主题，无论您的客户端是否订阅了该响应消息主题。这些响应消息不会通过消息代理，也无法由其它客户端或规则订阅。

订阅机群监控解决方案的任务和 jobExecution 事件主题时，首先启用任务和任务执行事件以接收云端的任何事件。Job 进度消息，这些消息通过消息代理处理并且可以由 Amazon IoT 规则使用，将发布为任务事件。由于消息代理会发布响应消息，即使没有明确订阅响应消息也是如此，因此必须配置您的客户端以接收和标识其接收的消息。您的客户端还必须确认传入消息中的 thingName 在客户端对消息执行操作前应用于客户端的事物名称。

注意

Amazon IoT 发送的用于响应 MQTT Jobs API 命令消息的消息会计入您的账户费用，无论您是否显式订阅了这些消息。

下面显示了 MQTT API 操作及其请求和响应语法。所有 MQTT API 操作都具有以下参数：

clientToken: 用于将请求和响应关联起来的可选客户端令牌。在此处输入任意值，它将反映在响应中。
timestamp: 发送消息的时间（用从纪元开始的秒数表示）。

针对指定的事物，获取未处于最终状态的所有任务的列表。

要调用此 API，请在 $aws/things/thingName/jobs/get 上发布消息。

请求负载：


{ "clientToken": "string" }

消息代理将发布 $aws/things/thingName/jobs/get/accepted 和 $aws/things/thingName/jobs/get/rejected，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅关于 Job API 消息的说明。

响应负载：


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

其中，inProgressJobs 和 queuedJobs 返回状态为 IN_PROGRESS 或 QUEUED 的 JobExecutionSummary 对象的列表。

获取并启动事物的下一个待处理任务执行（状态为 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 字段）可能指定的任务执行超时。

消息代理将发布 $aws/things/thingName/jobs/start-next/accepted 和 $aws/things/thingName/jobs/start-next/rejected，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅关于 Job API 消息的说明。

响应负载：


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

其中，execution 是 JobExecution 对象。例如：


{
"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,
}

获取有关任务执行的详细信息。

您可以将 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 消息的说明。

响应负载：


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

其中，execution 是 JobExecution 对象。

更新任务执行的状态。（可选）您可以通过为 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: 任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在 Amazon IoT Jobs 服务中的任务执行的版本不匹配，则更新将因 VersionMismatch 错误而被拒绝。还会返回包含当前任务执行状态数据的ErrorResponse。（这样就不必执行单独的 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 消息的说明。

响应负载：


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: 一个 JobExecutionState 对象。
jobDocument: 一个任务文档对象。
timestamp: 发送消息的时间（用从纪元开始的秒数表示）。
clientToken: 用于将请求和响应关联起来的客户端令牌。

使用 MQTT 协议时，您还可以执行以下更新：

在事物的待处理任务执行列表中添加或删除任务执行时发送。

使用主题：

$aws/things/thingName/jobs/notify

消息负载：


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

当存在对事物的待处理任务执行列表中的下一个任务执行的更改（使用 jobId $next 为 DescribeJobExecution 定义）时发送。当下一个任务的执行详细信息发生更改时不会发送此消息，而仅在将由 DescribeJobExecution（jobId 为 $next）返回的下一个任务发生更改时发送。考虑状态为 QUEUED 的任务执行 J1 和 J2。J1 是待处理任务执行列表中的下一个待处理任务执行。如果 J2 的状态更改为 IN_PROGRESS，而 J1 的状态保持不变，则将发送此通知，并且此通知包含 J2 的详细信息。

使用主题：

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

消息负载：


{
"execution" : JobExecution,
"timestamp": timestamp,
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。