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

# 任務裝置 HTTP API
<a name="jobs-http-device-api"></a>

裝置可以在連接埠 443 上使用 HTTP Signature 第 4 版與 AWS IoT 任務通訊。這是 AWS SDKs和 CLI 所使用的方法。如需這些工具詳細資訊，請參閱 [AWS CLI 命令參考：iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html) 或 [AWS SDK 與工具](https://aws.amazon.com/tools/#sdk)。

以下命令可用於執行任務的裝置。如需如何使用 API 操作搭配 MQTT 通訊協定的詳細資訊，請參閱 [任務裝置 MQTT API 操作](jobs-mqtt-api.md)。

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

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

------
#### [ HTTPS request ]

```
GET /things/thingName/jobs
```

回應：

```
{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ]
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html)。

------
#### [ CLI syntax ]

```
aws iot-jobs-data get-pending-job-executions \
--thing-name <value>  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]
```

 `cli-input-json` 格式：

```
{
"thingName": "string"
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html)。

------

## StartNextPendingJobExecution
<a name="http-startnextpendingjobexecution"></a>

取得並啟動物件的下一個待定任務執行 (狀態 `IN_PROGRESS` 或 `QUEUED`)。
+ 狀態為 `IN_PROGRESS` 的任務執行會先傳回。
+ 工作執行會依照其建立的順序傳回。
+ 如果下一個待定任務執行為 `QUEUED`，則其狀態會變更為 `IN_PROGRESS`，而任務執行狀態詳細資訊也會依指定設定。
+ 如果下一個待定任務執行已經為 `IN_PROGRESS`，則其狀態詳細資訊不會變更。
+ 如果沒有工作執行為待定，則回應不會包括 `execution` 欄位。
+ 您也可以選擇透過設定 `stepTimeoutInMinutes` 的屬性來新增步驟計時器。如果您未透過執行 `UpdateJobExecution` 來更新此屬性的值，則步驟計時器逾期時，任務執行將逾時。

------
#### [ HTTPS request ]

請求語法如下列範例所示：

```
PUT /things/thingName/jobs/$next
{
"statusDetails": { 
    "string": "string" 
    ... 
},
"stepTimeoutInMinutes": long
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html)。

------
#### [ CLI syntax ]

**概要：**

```
aws iot-jobs-data  start-next-pending-job-execution \
--thing-name <value> \
{--step-timeout-in-minutes <value>] \
[--status-details <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]
```

 `cli-input-json` 格式：

```
{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html)。

------

## DescribeJobExecution
<a name="http-describejobexecution"></a>

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

您可以將 `jobId` 設定為 `$next`，傳回物件的下一個待定任務執行。任務的執行狀態必須為 `QUEUED`或 `IN_PROGRESS`。

------
#### [ HTTPS request ]

要求:

```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
```

回應：

```
{
"execution" : JobExecution,
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html)。

------
#### [ CLI syntax ]

**概要：**

```
aws iot-jobs-data  describe-job-execution \
--job-id <value> \
--thing-name <value> \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]
```

 `cli-input-json` 格式：

```
{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html)。

------

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

更新工作執行的狀態。您也可以選擇透過設定 `stepTimeoutInMinutes` 的屬性來新增步驟計時器。如果您未透過再次執行 `UpdateJobExecution` 來更新此屬性的值，則步驟計時器逾期時，任務執行將逾時。

------
#### [ HTTPS request ]

要求:

```
POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long 
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html)。

------
#### [ CLI syntax ]

**概要：**

```
aws iot-jobs-data  update-job-execution \
--job-id <value> \
--thing-name <value> \
--status <value> \
[--status-details <value>] \
[--expected-version <value>] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--step-timeout-in-minutes <value>] \
[--generate-cli-skeleton]
```

 `cli-input-json` 格式：

```
{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}
```

如需詳細資訊，請參閱[https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html)。

------