本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 任务设备 HTTP API
<a name="jobs-http-device-api"></a>

设备可以在端口 443 上使用 HTTP 签名版本 4 与 AWS IoT Job 通信。这是 AWS SDKs 和 CLI 使用的方法。有关这些工具的更多信息，请参阅[AWS CLI 命令参考：iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html)或[AWS SDKs 和工具](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)。

------