本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 任務裝置 MQTT API 操作
<a name="jobs-mqtt-api"></a><a name="jobs-mqtt-note"></a>

您可以發出任務裝置命令，方法為將 MQTT 訊息發佈至[用於任務命令的保留主題](reserved-topics.md#reserved-topics-job)。

您的裝置端用戶端必須訂閱這些命令的回應訊息主題。如果您使用 AWS IoT 裝置用戶端，您的裝置會自動訂閱回應主題。這表示，無論您的用戶端是否已訂閱回應訊息主題，訊息代理程式都會將回應訊息主題發佈至發佈命令訊息的用戶端。這些回應訊息不會透過訊息代理程式傳遞，而且其他用戶端或規則無法訂閱這些訊息。

訂閱機群監控解決方案的任務和 `jobExecution` 事件主題時，首先啟用[任務和任務執行事件](iot-events.md)來接收雲端的任何事件。透過訊息代理程式處理並可由 AWS IoT 規則使用的任務進度訊息會發佈為 [任務事件](events-jobs.md)。由於訊息代理程式會發佈回應訊息，即使沒有明確地訂閱它們，您的用戶端也必須設定為接收並識別其所接收的訊息。您的用戶端也必須確認，在用戶端對訊息採取動作之前，內送訊息主題中的 {{thingName}} 套用至用戶端的物件名稱。

**注意**  
為回應 MQTT Jobs API 命令訊息而 AWS IoT 傳送的訊息會向您的 帳戶收費，無論您是否明確訂閱。

以下說明 MQTT API 操作及其請求和回應語法。所有 MQTT API 操作均有下列參數：

clientToken  
用來關聯請求和回應的選用用戶端字符。在此輸入任意值，就會在回應中反映出來。

`timestamp`  
訊息傳送的 epoch 時間，以秒為單位。

## GetPendingJobExecutions
<a name="mqtt-getpendingjobexecutions"></a>

針對特定物件，取得其所有未處於終止狀態之任務的清單。

欲呼叫此 API，請發佈訊息於 `$aws/things/{{thingName}}/jobs/get`。

請求酬載：

```
{ "clientToken": "string" }
```

訊息代理程式將發佈 `$aws/things/{{thingName}}/jobs/get/accepted` 和 `$aws/things/{{thingName}}/jobs/get/rejected`，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱[關於任務 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
<a name="mqtt-startnextpendingjobexecution"></a>

取得並啟動物件的下一個待定任務執行 (狀態 `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`。設定此逾時不會影響任務執行逾時，該任務執行逾時可能已在建立任務時加以指定 (使用欄位 `timeoutConfig` 的 `CreateJob`)。  
此參數的有效值範圍是 1 到 10080 (1 分鐘到 7 天)。值 -1 也有效，且會取消目前的步驟計時器 （由先前使用的 UpdateJobExecutionRequest 所建立）。

訊息代理程式將發佈 `$aws/things/{{thingName}}/jobs/start-next/accepted` 和 `$aws/things/{{thingName}}/jobs/start-next/rejected`，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱[關於任務 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
<a name="mqtt-describejobexecution"></a>

取得工作執行的詳細資訊。

您可以將 `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`，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱[關於任務 API 訊息的注意事項](#jobs-mqtt-note)。

回應酬載：

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

`execution` 為 [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 物件。

## UpdateJobExecution
<a name="mqtt-updatejobexecution"></a>

更新工作執行的狀態。您可以選擇透過設定 `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`  
預期的目前工作執行版本。每次您更新工作執行，其版本編號就會增加。如果存放在 Jobs 服務中的 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`，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱[關於任務 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`  
訊息傳送的 epoch 時間，以秒為單位。

`clientToken`  
用於將請求和回應建立關聯的用戶端符記。

使用 MQTT 通訊協定時，也可以執行下列更新：

## JobExecutionsChanged
<a name="mqtt-jobexecutionschanged"></a>

每當物件的待定任務執行清單新增或移除任務執行時就會傳送。

使用主題：

`$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
<a name="mqtt-nextjobexecutionchanged"></a>

每當物件待定任務清單上的下一個任務執行變更就會傳送，亦即定義 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 時加上 `jobId` `$next`。當下一個任務的執行詳細資訊變更，此訊息並不會傳送，只有在加上 `jobId` `$next` 之 `DescribeJobExecution` 傳回的下一個任務變更時才會傳送。考量狀態為 `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,
}
```