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

# AWS IoT 任務 API 操作
<a name="jobs-api"></a>

AWS IoT 任務 API 可用於下列任一類別：
+ 管理任務，例如任務的管理和控制。這是*控制平面*。
+ 實施這些任務的裝置。這是*資料平面*，可讓您傳送和接收資料。

任務管理與控制會使用 HTTPS 通訊協定的 API。裝置可以使用 MQTT 或 HTTPS 通訊協定的 API。控制平面 API 適用於少量呼叫，特別是在建立與追蹤任務時使用。其通常會為單一請求開啟連線，並在接收到回應之後關閉連線。資料平面 HTTPS 和 MQTT API 允許長輪詢。這些 API 操作適用於可擴展至數百萬個裝置的大量流量。

每個 AWS IoT Jobs HTTPS API 都有對應的命令，可讓您從 AWS Command Line Interface () 呼叫 API AWS CLI。命令為小寫字母，且在組成 API 名稱的單字之間有連字號。例如，您可以輸入以下內容來呼叫 CLI 上的 `CreateJob` API：

```
aws iot create-job ...
```

如果操作期間發生錯誤，您會收到包含錯誤相關資訊的錯誤回應。

## ErrorResponse
<a name="jobs-mqtt-error-response"></a>

包含在 AWS IoT 任務服務操作期間所發生的錯誤資訊。

以下範例顯示此操作的語法：

```
{
    "code": "ErrorCode",
    "message": "string",
    "clientToken": "string",
    "timestamp": timestamp,
    "executionState": JobExecutionState
}
```

以下是 `ErrorResponse` 的說明：

`code`  
ErrorCode 可設定為：    
InvalidTopic  
請求已傳送至 AWS IoT 任務命名空間中未對應至任何 API 操作的主題。  
InvalidJson  
請求的內容無法解譯為有效的 UTF-8 編碼 JSON。  
InvalidRequest  
請求的內容無效。例如，當 `UpdateJobExecution` 請求包含了無效的狀態詳細資訊，此代碼就會傳回。訊息包含錯誤的詳細資訊。  
InvalidStateTransition  
已嘗試更新，將任務執行變更為由於任務執行目前狀態而無效的狀態。例如，嘗試將狀態為 SUCCEEDED 的請求變更為狀態 IN\$1PROGRESS。在此情況下，錯誤訊息的本文也會包含 `executionState` 欄位。  
ResourceNotFound  
請求主題指定的 `JobExecution` 不存在。  
VersionMismatch  
請求中指定的預期版本與任務服務中 AWS IoT 任務執行的版本不相符。在此情況下，錯誤訊息的本文也會包含 `executionState` 欄位。  
InternalError  
處理請求時發生內部錯誤。  
RequestThrottled  
請求受到調節。  
TerminalStateReached  
在處於結束狀態的任務上執行描述任務的命令時發生。

`message`  
錯誤訊息字串。

`clientToken`  
用於將請求與回覆建立關聯的任意字串。

`timestamp`  
Epoch 時間，以秒為單位。

`executionState`  
[https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) 物件。只有當 `code` 欄位有 `InvalidStateTransition` 或 `VersionMismatch` 值，此欄位才會包含在內。在這些情況下，就不必另外執行 `DescribeJobExecution` 請求以獲得任務執行狀態資料。

**Topics**
+ [任務管理、控制 API 和控制資料類型](jobs-management-control-api.md)
+ [任務裝置 MQTT、HTTPS API 操作和資料類型](jobs-mqtt-https-api.md)