As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS IoT operações de API de empregos
AWS IoT A API Jobs pode ser usada para qualquer uma das seguintes categorias:
+ Tarefas administrativas, como gerenciamento e controle de trabalhos. Esse é o *ambiente de gerenciamento*.
+ Dispositivos que realizam esses trabalhos. Esse é o *plano de dados*, que permite enviar e receber dados.
O gerenciamento e o controle de trabalhos usam uma API do protocolo HTTPS. Os dispositivos podem usar uma API MQTT ou de protocolo HTTPS. A API do ambiente de gerenciamento é projetada para um volume baixo de chamadas típicas durante a criação e o acompanhamento de trabalhos. Normalmente, ela abre uma conexão para uma única solicitação e, em seguida, fecha a conexão depois que a resposta é recebida. O plano de dados HTTPS e a API MQTT permitem pesquisas longas. Essas operações de API foram projetadas para grandes quantidades de tráfego que podem ser escaladas para milhões de dispositivos.
Cada API HTTPS do AWS IoT Jobs tem um comando correspondente que permite que você chame a API a partir do AWS Command Line Interface (AWS CLI). Os comandos são em letras minúsculas, com hifens entre as palavras que compõem o nome da API. Por exemplo, você pode chamar a API `CreateJob` na CLI, digitando:
```
aws iot create-job ...
```
No caso de erro durante uma operação, você recebe uma resposta de erro que contém as informações sobre o erro.
## ErrorResponse
Contém informações sobre um erro que ocorreu durante uma operação do serviço Jobs da AWS IoT .
O exemplo a seguir mostra a sintaxe dessa operação:
```
{
"code": "ErrorCode",
"message": "string",
"clientToken": "string",
"timestamp": timestamp,
"executionState": JobExecutionState
}
```
A seguir está uma descrição desse `ErrorResponse`:
`code`
ErrorCode pode ser configurado para:
InvalidTopic
A solicitação foi enviada para um tópico no namespace AWS IoT Jobs que não é mapeado para nenhuma operação de API.
InvalidJson
O conteúdo da solicitação não pôde ser interpretado como JSON codificado em UTF-8 válido.
InvalidRequest
O conteúdo da solicitação não era válido. Por exemplo, esse código é retornado quando uma solicitação `UpdateJobExecution` contém detalhes do status inválido. A mensagem contém detalhes sobre o erro.
InvalidStateTransition
Uma atualização tentou alterar a execução do trabalho para um estado que não é válido devido ao estado atual da execução do trabalho. Por exemplo, uma tentativa de alterar uma solicitação no estado SUCCEEDED para o estado IN\$1PROGRESS. Nesse caso, o corpo da mensagem de erro também contém o campo `executionState`.
ResourceNotFound
A `JobExecution` especificada pelo tópico da solicitação não existe.
VersionMismatch
A versão esperada especificada na solicitação não corresponde à versão da execução do trabalho no serviço AWS IoT Jobs. Nesse caso, o corpo da mensagem de erro também contém o campo `executionState`.
InternalError
Ocorreu um erro interno durante o processamento da solicitação.
RequestThrottled
A solicitação foi acelerada.
TerminalStateReached
Ocorre quando um comando para descrever um trabalho é executado em um trabalho que está em um estado terminal.
`message`
A sequência de uma mensagem de erro.
`clientToken`
Uma sequência arbitrária usada para correlacionar uma solicitação com sua resposta.
`timestamp`
O tempo, em segundos, desde a epoch.
`executionState`
Um objeto [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). Esse campo é incluído apenas quando o campo `code` tem o valor `InvalidStateTransition` ou `VersionMismatch`. Nesses casos, torna-se desnecessário executar uma solicitação `DescribeJobExecution` separada para obter os dados do status da execução do trabalho atual.
**Topics**
+ [Tipos de dados e API de controle e gerenciamento de trabalhos](jobs-management-control-api.md)
+ [Tipos de dados e operações da API MQTT e HTTPS do dispositivo de trabalhos](jobs-mqtt-https-api.md)
# Tipos de dados e API de controle e gerenciamento de trabalhos
**Topics**
+ [Tipos de dados de gerenciamento e controle de trabalhos](#jobs-control-plane-data-types)
+ [Operações de API de gerenciamento e controle de trabalhos](#jobs-http-api)
Para determinar o *endpoint-url* parâmetro para seus comandos da CLI, execute esse comando.
```
aws iot describe-endpoint --endpoint-type=iot:Jobs
```
Este comando retorna a seguinte saída.
```
{
"endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com"
}
```
**nota**
O endpoint do serviço Jobs não é compatível com o `x-amzn-http-ca` ALPN.
Se você estiver usando endpoints de pilha dupla (IPv6 e IPv6), use o endpoint. `iot:Data-ATS` Somente IPv4 o `iot:Jobs` endpoint oferece suporte.
## Tipos de dados de gerenciamento e controle de trabalhos
Os tipos de dados a seguir são usados por aplicativos de gerenciamento e controle para se comunicar com AWS IoT Jobs.
### Trabalho
O objeto `Job` contém detalhes sobre um trabalho. O exemplo a seguir mostra a sintaxe:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED",
"forceCanceled": boolean,
"targetSelection": "CONTINUOUS|SNAPSHOT",
"comment": "string",
"targets": ["string"],
"description": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp,
"jobProcessDetails": {
"processingTargets": ["string"],
"numberOfCanceledThings": long,
"numberOfSucceededThings": long,
"numberOfFailedThings": long,
"numberOfRejectedThings": long,
"numberOfQueuedThings": long,
"numberOfInProgressThings": long,
"numberOfRemovedThings": long,
"numberOfTimedOutThings": long
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html](https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job.html).
### JobSummary
O objeto `JobSummary` contém um resumo do trabalho. O exemplo a seguir mostra a sintaxe:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED",
"targetSelection": "CONTINUOUS|SNAPSHOT",
"thingGroupId": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html).
### JobExecution
O objeto `JobExecution` representa a execução de um trabalho em um dispositivo. O exemplo a seguir mostra a sintaxe:
**nota**
Quando você usa as operações da API do ambiente de gerenciamento, o tipo de dados `JobExecution` não contém um campo `JobDocument`. Para obter essas informações, você pode usar a operação da API [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) ou o comando da CLI [https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html).
```
{
"approximateSecondsBeforeTimedOut": 50,
"executionNumber": 1234567890,
"forceCanceled": true|false,
"jobId": "string",
"lastUpdatedAt": timestamp,
"queuedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"forceCanceled": boolean,
"statusDetails": {
"detailsMap": {
"string": "string" ...
},
"status": "string"
},
"thingArn": "string",
"versionNumber": 123
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html).
### JobExecutionSummary
O objeto `JobExecutionSummary` contém informações resumidas sobre a execução do trabalho. O exemplo a seguir mostra a sintaxe:
```
{
"executionNumber": 1234567890,
"queuedAt": timestamp,
"lastUpdatedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED"
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html).
### JobExecutionSummaryForJob
O objeto `JobExecutionSummaryForJob` contém um resumo das informações sobre execuções de trabalho de um trabalho específico. O exemplo a seguir mostra a sintaxe:
```
{
"executionSummaries": [
{
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing",
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
}
},
...
]
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html).
### JobExecutionSummaryForThing
O `JobExecutionSummaryForThing` objeto contém um resumo das informações sobre a execução de um trabalho em uma coisa específica. FThe o exemplo a seguir mostra a sintaxe:
```
{
"executionSummaries": [
{
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
},
"jobId": "MyThingJob"
},
...
]
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html).
## Operações de API de gerenciamento e controle de trabalhos
Use um dos seguintes comandos da CLI ou operações da API:
### AssociateTargetsWithJob
Associa um grupo a um trabalho contínuo. Os seguintes critérios devem ser atendidos:
+ O trabalho deve ter sido criado com o campo `targetSelection` definido como `CONTINUOUS`.
+ O status do trabalho deve ser `IN_PROGRESS`.
+ O número total de destinos associados a um trabalho não deve ultrapassar 100.
------
#### [ HTTPS request ]
```
POST /jobs/jobId/targets
{
"targets": [ "string" ],
"comment": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html).
------
#### [ CLI syntax ]
```
aws iot associate-targets-with-job \
--targets \
--job-id \
[--comment ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"targets": [
"string"
],
"jobId": "string",
"comment": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html).
------
### CancelJob
Cancela um trabalho.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId/cancel
{
"force": boolean,
"comment": "string",
"reasonCode": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job \
--job-id \
[--force ] \
[--comment ] \
[--reasonCode ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean,
"comment": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html).
------
### CancelJobExecution
Cancela uma execução de trabalho em um dispositivo.
------
#### [ HTTPS request ]
```
PUT /things/thingName/jobs/jobId/cancel
{
"force": boolean,
"expectedVersion": "string",
"statusDetails": {
"string": "string"
...
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job-execution \
--job-id \
--thing-name \
[--force | --no-force] \
[--expected-version ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"force": boolean,
"expectedVersion": long,
"statusDetails": {
"string": "string"
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html).
------
### CreateJob
Cria um trabalho. Você pode fornecer o documento de trabalho como um link para um arquivo em um bucket do Amazon S3; (parâmetro `documentSource`) ou no corpo da solicitação (parâmetro `document`).
Um trabalho pode se tornar *contínuo* definindo o parâmetro opcional `targetSelection` como `CONTINUOUS` (o padrão é `SNAPSHOT`). Um trabalho contínuo pode ser usado para integrar ou atualizar dispositivos à medida que são adicionados a um grupo, pois ele continua em execução e é iniciado em itens recém-adicionados. Isso pode ocorrer mesmo após as objetos do grupo no momento em que o trabalho foi criado terem concluído o trabalho.
Um trabalho pode ter um opcional [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html), que define o valor do cronômetro em andamento. O temporizador em andamento não pode ser atualizado e é aplicado a todas as execuções do trabalho.
As seguintes validações são realizadas em argumentos para a API `CreateJob`:
+ O `targets` argumento deve ser uma lista de coisas ou grupos de coisas válidos ARNs. Todas as coisas e grupos de coisas devem estar em seu Conta da AWS.
+ O argumento `documentSource` deve ser um URL válido do Amazon S3 para um documento de trabalho. O Amazon S3 URLs está no formato:. `https://s3.amazonaws.com/bucketName/objectName`
+ O documento armazenado na URL especificada pelo argumento `documentSource` deve ser um documento JSON codificado em UTF-8.
+ O tamanho de um documento de trabalho é limitado a 32 KB devido ao limite do tamanho de uma mensagem MQTT (128 KB) e da criptografia.
+ `jobId`Deve ser único em seu Conta da AWS.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
"roleArn": "string",
"expiresInSec": "integer"
},
"targetSelection": "CONTINUOUS|SNAPSHOT",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
}
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html).
------
#### [ CLI syntax ]
```
aws iot create-job \
--job-id \
--targets \
[--document-source ] \
[--document ] \
[--description ] \
[--job-template-arn ] \
[--presigned-url-config ] \
[--target-selection ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--document-parameters ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"targets": [ "string" ],
"documentSource": "string",
"document": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfig": {
"roleArn": "string",
"expiresInSec": long
},
"targetSelection": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
},
"documentParameters": {
"string": "string"
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html).
------
### DeleteJob
Exclui um trabalho e as execuções de trabalho correspondentes.
A exclusão de um trabalho pode levar tempo, dependendo do número de execuções criadas para o trabalho e de vários outros fatores. Enquanto o trabalho está sendo excluído, seu status é mostrado como "DELETION\$1IN\$1PROGRESS". A tentativa de excluir ou cancelar um trabalho cujo status já seja "DELETION\$1IN\$1PROGRESS" resulta em um erro.
------
#### [ HTTPS request ]
```
DELETE /jobs/jobId?force=force
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html).
------
#### [ CLI syntax ]
```
aws iot delete-job \
--job-id \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html).
------
### DeleteJobExecution
Exclui uma execução de trabalho.
------
#### [ HTTPS request ]
```
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot delete-job-execution \
--job-id \
--thing-name \
--execution-number \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long,
"force": boolean
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html).
------
### DescribeJob
Obtém os detalhes da execução do trabalho.
------
#### [ HTTPS request ]
```
GET /jobs/jobId
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html).
------
#### [ CLI syntax ]
```
aws iot describe-job \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html).
------
### DescribeJobExecution
Obtém os detalhes da execução de um trabalho. O status da execução do trabalho deve ser `SUCCEEDED` ou `FAILED`.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot describe-job-execution \
--job-id \
--thing-name \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html).
------
### GetJobDocument
Obtém o documento de trabalho para um trabalho.
**nota**
Os espaços reservados não URLs são substituídos pelo Amazon URLs S3 pré-assinado no documento devolvido. Os pré-assinados URLs são gerados somente quando o serviço AWS IoT Jobs recebe uma solicitação pelo MQTT.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/job-document
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html).
------
#### [ CLI syntax ]
```
aws iot get-job-document \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html).
------
### ListJobExecutionsForJob
Obtém uma lista de execuções de trabalhos para um trabalho.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-job \
--job-id \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html).
------
### ListJobExecutionsForThing
Obtém uma lista de execuções de trabalhos para um objeto.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-thing \
--thing-name \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html).
------
### ListJobs
Obtém uma lista de empregos em seu Conta da AWS.
------
#### [ HTTPS request ]
```
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html).
------
#### [ CLI syntax ]
```
aws iot list-jobs \
[--status ] \
[--target-selection ] \
[--max-results ] \
[--next-token ] \
[--thing-group-name ] \
[--thing-group-id ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"status": "string",
"targetSelection": "string",
"maxResults": "integer",
"nextToken": "string",
"thingGroupName": "string",
"thingGroupId": "string"
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html).
------
### UpdateJob
Atualiza campos compatíveis do trabalho especificado. Valores atualizados para `timeoutConfig` entram em vigor somente para novas execuções em andamento. Atualmente, os lançamentos em andamento continuam sendo lançados com a configuração de tempo limite anterior.
------
#### [ HTTPS request ]
```
PATCH /jobs/jobId
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html).
------
#### [ CLI syntax ]
```
aws iot update-job \
--job-id \
[--description ] \
[--presigned-url-config ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
Para obter mais informações, consulte [https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html).
------
# Tipos de dados e operações da API MQTT e HTTPS do dispositivo de trabalhos
Os seguintes comandos estão disponíveis por meio dos protocolos MQTT e HTTPS. Use essas operações de API no plano de dados para dispositivos que executam os trabalhos.
## Tipos de dados MQTT e HTTPS de dispositivos de trabalho
Os tipos de dados a seguir são usados para se comunicar com o serviço AWS IoT Jobs pelos protocolos MQTT e HTTPS.
### JobExecution
O objeto `JobExecution` representa a execução de um trabalho em um dispositivo. O exemplo a seguir mostra a sintaxe:
**nota**
Quando você usa as operações da API do plano de dados MQTT e HTTP, o tipo de dados `JobExecution` contém um campo `JobDocument`. Seus dispositivos podem usar essas informações para recuperar o documento de trabalho de uma execução de trabalho.
```
{
"jobId" : "string",
"thingName" : "string",
"jobDocument" : "string",
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
},
"queuedAt" : "timestamp",
"startedAt" : "timestamp",
"lastUpdatedAt" : "timestamp",
"versionNumber" : "number",
"executionNumber": long
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html).
### JobExecutionState
O `JobExecutionState` contém informações sobre o estado da execução de um trabalho. O exemplo a seguir mostra a sintaxe:
```
{
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
...
}
"versionNumber": "number"
}
```
Para acessar mais informações, consulte [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) ou [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html).
### JobExecutionSummary
Contém um subconjunto de informações sobre a execução de um trabalho. O exemplo a seguir mostra a sintaxe:
```
{
"jobId": "string",
"queuedAt": timestamp,
"startedAt": timestamp,
"lastUpdatedAt": timestamp,
"versionNumber": "number",
"executionNumber": long
}
```
Para acessar mais informações, consulte [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html) ou [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html).
**Topics**
+ [Tipos de dados MQTT e HTTPS de dispositivos de trabalho](#jobs-data-plane-data-types)
+ [Operações da API MQTT do dispositivo de trabalhos](jobs-mqtt-api.md)
+ [API HTTP do dispositivo do Jobs](jobs-http-device-api.md)
# Operações da API MQTT do dispositivo de trabalhos
Você pode emitir comandos do dispositivo de trabalhos publicando mensagens MQTT nos [Tópicos reservados usados para comandos de trabalhos](reserved-topics.md#reserved-topics-job).
Seu cliente do lado do dispositivo deve estar inscrito nos tópicos das mensagens de resposta desses comandos. Se você usar o AWS IoT Device Client, seu dispositivo se inscreverá automaticamente nos tópicos de resposta. Isso indica que agente de mensagens publicará tópicos da mensagem de resposta para o cliente que publicou a mensagem de comando, independentemente de seu cliente ter assinado ou não os tópicos da mensagem de resposta. Essas mensagens de resposta não passam pelo agente de mensagens e não podem ser assinadas por outros clientes ou regras.
Ao assinar os tópicos de trabalhos e tópicos do evento `jobExecution` de sua solução de monitoramento de frota, primeiro habilite os [eventos de trabalho e execução de trabalhos](iot-events.md) para receber quaisquer eventos no lado da nuvem. As mensagens de progresso do trabalho que são processadas por meio do agente de mensagens e podem ser usadas pelas regras de AWS IoT são publicadas como [Eventos de trabalho](events-jobs.md). Como o agente de mensagens publica mensagens de resposta, mesmo sem uma assinatura explícita, seu cliente deve estar configurado para receber e identificar as mensagens que recebe. Seu cliente também deve confirmar que o tópico *thingName* na mensagem recebida se aplica ao nome da coisa do cliente antes que o cliente aja na mensagem.
**nota**
As mensagens AWS IoT enviadas em resposta às mensagens de comando da API MQTT Jobs são cobradas em sua conta, independentemente de você ter se inscrito ou não explicitamente.
Veja a seguir as operações da API MQTT e sua sintaxe de solicitação e resposta. Todas as operações da API MQTT têm os seguintes parâmetros:
clientToken
Um token do cliente opcional usado para correlacionar solicitações e respostas. Insira um valor arbitrário aqui e ele será refletido na resposta.
`timestamp`
O tempo, em segundos, desde a epoch em que a mensagem foi enviada.
## GetPendingJobExecutions
Obtém a lista de todos os trabalhos que não estão em um status terminal, para um objeto específica.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/get`.
Carga da solicitação:
```
{ "clientToken": "string" }
```
O agente de mensagens publicará `$aws/things/thingName/jobs/get/accepted` e `$aws/things/thingName/jobs/get/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Onde `inProgressJobs` e `queuedJobs` retornam uma lista de objetos [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) que têm status de `IN_PROGRESS` ou `QUEUED`.
## StartNextPendingJobExecution
Obtém e começa a próxima execução de trabalho pendente para um objeto (status `IN_PROGRESS` ou `QUEUED`).
+ Todas as execuções de trabalho com o status `IN_PROGRESS` são retornadas primeiro.
+ As execuções de trabalho são retornadas na ordem em que foram colocadas em fila. Quando um objeto for adicionada ou removida do grupo de destino do seu trabalho, confirme a ordem de distribuição de qualquer nova execução de trabalho em comparação com as execuções de trabalhos existentes.
+ Se a execução do próximo trabalho pendente for `QUEUED`, seu estado será alterado para `IN_PROGRESS` e os detalhes do status da execução do trabalho serão definidos conforme especificado.
+ Se a execução do próximo trabalho pendente já for `IN_PROGRESS`, os detalhes de seu status não serão alterados.
+ Se nenhuma execução de trabalho estiver pendente, a resposta não incluirá o campo `execution`.
+ Se desejar, você pode criar um temporizador de etapa definindo um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution`, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/start-next`.
Carga da solicitação:
```
{
"statusDetails": {
"string": "job-execution-state"
...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`statusDetails`
Uma coleção de pares nome e valor que descrevem o status da execução do trabalho. Se não especificado, o `statusDetails` não será alterado.
`stepTimeOutInMinutes`
Especifica o tempo que este dispositivo tem para concluir a execução do trabalho. Se o status de execução do trabalho não estiver definido como um estado terminal antes que o temporizador expire ou seja redefinido (ao chamar `UpdateJobExecution`, definir o status como `IN_PROGRESS` e especificar um novo valor de tempo limite no campo `stepTimeoutInMinutes`), o status de execução do trabalho será definido como `TIMED_OUT`. A configuração do tempo limite não tem efeito sobre o tempo limite de execução desse trabalho, que pode ter sido especificado quando o trabalho foi criado (`CreateJob` usando o campo `timeoutConfig`).
Os valores válidos para este parâmetro variam de 1 a 10.080 (1 minuto a 7 dias). Um valor de -1 também é válido e cancelará o cronômetro da etapa atual (criado por um uso anterior do UpdateJobExecutionRequest).
O agente de mensagens publicará `$aws/things/thingName/jobs/start-next/accepted` e `$aws/things/thingName/jobs/start-next/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Onde `execution` é um objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data). Por exemplo:
```
{
"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
Obtém informações detalhadas sobre uma execução de trabalho.
Você pode definir `jobId` como `$next` para retornar a próxima execução de trabalho pendente para um objeto (com status `IN_PROGRESS` ou `QUEUED`).
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/jobId/get`.
Carga da solicitação:
```
{
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string"
}
```
`thingName`
O nome do objeto associada ao dispositivo.
`jobId`
O identificador exclusivo atribuído a este trabalho quando ele foi criado.
Ou usar `$next` para retornar a próxima execução de trabalho pendente para um objeto (com status `IN_PROGRESS` ou `QUEUED`). Nesse caso, todas as execuções de trabalho com o status `IN_PROGRESS` são retornadas primeiro. As execuções de trabalho são retornadas na ordem em que foram criadas.
`executionNumber`
(Opcional) Um número que identifica a execução de um trabalho em um dispositivo. Se não especificado, a execução do trabalho mais recente será retornada.
`includeJobDocument`
(Opcional) A menos que definido como `false`, a resposta conterá o documento de trabalho. O padrão é `true`.
O agente de mensagens publicará `$aws/things/thingName/jobs/jobId/get/accepted` e `$aws/things/thingName/jobs/jobId/get/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Onde `execution` é um objeto [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data).
## UpdateJobExecution
Atualiza o status de uma execução de trabalho. Você pode criar um temporizador de etapa. Para isso, defina um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution` novamente, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
Para invocar essa API, publique uma mensagem em `$aws/things/thingName/jobs/jobId/update`.
Carga da solicitação:
```
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`status`
O novo status da execução do trabalho (`IN_PROGRESS`, `FAILED`, `SUCCEEDED` ou`REJECTED`). Isso deve ser especificado em todas as atualizações.
`statusDetails`
Uma coleção de pares nome e valor que descrevem o status da execução do trabalho. Se não especificado, o `statusDetails` não será alterado.
`expectedVersion`
A versão esperada atual da execução do trabalho. Cada vez que você atualiza a execução do trabalho, sua versão é incrementada. Se a versão da execução do trabalho armazenada no serviço AWS IoT Jobs não corresponder, a atualização será rejeitada com um `VersionMismatch` erro. Um [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) que contém os dados atuais do status de execução do trabalho também é retornado. Isso torna desnecessário executar uma solicitação `DescribeJobExecution` separada para obter os dados do status da execução do trabalho.
`executionNumber`
(Opcional) Um número que identifica a execução de um trabalho em um dispositivo. Se não especificado, a execução do trabalho mais recente será usada.
`includeJobExecutionState`
(Opcional) Quando incluído e definido como `true`, a resposta conterá o campo `JobExecutionState`. O padrão é `false`.
`includeJobDocument`
(Opcional) Quando incluído e definido como `true`, a resposta conterá o `JobDocument`. O padrão é `false`.
`stepTimeoutInMinutes`
Especifica o tempo que este dispositivo tem para concluir a execução do trabalho. Se o status de execução do trabalho não for definido como um estado terminal antes que o temporizador expire ou antes que o temporizador seja redefinido, o status da execução do trabalho será definido como `TIMED_OUT`. A configuração ou a reconfiguração do tempo limite não tem efeito sobre o tempo limite de execução do trabalho que pode ter sido especificado quando o trabalho foi criado.
O agente de mensagens publicará `$aws/things/thingName/jobs/jobId/update/accepted` e `$aws/things/thingName/jobs/jobId/update/rejected` mesmo sem uma assinatura específica. No entanto, para que seu cliente receba as mensagens, ele deve estar ouvindo. Para obter mais informações, consulte a [observação sobre mensagens de API do Jobs](#jobs-mqtt-note).
Carga da resposta:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
Um objeto [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state).
`jobDocument`
Um objeto [documento de trabalho](key-concepts-jobs.md).
Nas respostas do MQTT, o campo `jobDocument` é um objeto JSON. Nas respostas HTTP, é uma representação de string do objeto JSON.
`timestamp`
O tempo, em segundos, desde a epoch em que a mensagem foi enviada.
`clientToken`
Um token do cliente usado para correlacionar solicitações e respostas.
Ao usar o protocolo MQTT, você também pode realizar as seguintes atualizações:
## JobExecutionsChanged
Enviado sempre que uma execução de trabalho é adicionada ou removida da lista de execuções de trabalhos pendentes para um objeto.
Use o tópico :
`$aws/things/thingName/jobs/notify`
Carga da mensagem:
```
{
"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
Enviado sempre que houver uma alteração em qual execução de trabalho é a seguinte na lista de execuções de trabalhos pendentes para um objeto, conforme definido para [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) com o `jobId` `$next`. Essa mensagem não é enviada quando os detalhes da próxima execução de trabalho são alterados, apenas quando o próximo trabalho que seria retornado por `DescribeJobExecution` com o `jobId` `$next` tiver sido alterado. Considere as execuções de trabalho J1 e J2 com status `QUEUED`. J1 é a próxima na lista de execuções de trabalhos pendentes. Se o status de J2 for alterado para `IN_PROGRESS` enquanto o estado de J1 permanecer inalterado, essa notificação será enviada e conterá os detalhes do J2.
Use o tópico :
`$aws/things/thingName/jobs/notify-next`
Carga da mensagem:
```
{
"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,
}
```
# API HTTP do dispositivo do Jobs
Os dispositivos podem se comunicar com AWS IoT Jobs usando a assinatura HTTP versão 4 na porta 443. Esse é o método usado pela AWS SDKs e CLI. Para obter mais informações sobre essas ferramentas, consulte [Referência de AWS CLI comandos: iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html) ou [AWS SDKs e Ferramentas](https://aws.amazon.com/tools/#sdk).
Os seguintes comandos estão disponíveis para dispositivos que executam os trabalhos. Para obter informações sobre o uso de operações de API com o protocolo MQTT, consulte [Operações da API MQTT do dispositivo de trabalhos](jobs-mqtt-api.md).
## GetPendingJobExecutions
Obtém a lista de todos os trabalhos que não estão em um status terminal, para um objeto específica.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs
```
Resposta:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ]
}
```
Para obter mais informações, consulte [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 \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string"
}
```
Para obter mais informações, consulte [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
Obtém e começa a próxima execução de trabalho pendente para um objeto (com um status de `IN_PROGRESS` ou `QUEUED`).
+ Todas as execuções de trabalho com o status `IN_PROGRESS` são retornadas primeiro.
+ As execuções de trabalho são retornadas na ordem em que foram criadas.
+ Se a execução do próximo trabalho pendente for `QUEUED`, seu status será alterado para `IN_PROGRESS` e os detalhes do status da execução do trabalho serão definidos conforme especificado.
+ Se a execução do próximo trabalho pendente já for `IN_PROGRESS`, os detalhes de seu status não se alteram.
+ Se nenhuma execução de trabalho estiver pendente, a resposta não incluirá o campo `execution`.
+ Se desejar, você pode criar um temporizador de etapa definindo um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution`, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
------
#### [ HTTPS request ]
O exemplo a seguir mostra a sintaxe da solicitação:
```
PUT /things/thingName/jobs/$next
{
"statusDetails": {
"string": "string"
...
},
"stepTimeoutInMinutes": long
}
```
Para obter mais informações, consulte [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 ]
**Resumo:**
```
aws iot-jobs-data start-next-pending-job-execution \
--thing-name \
{--step-timeout-in-minutes ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}
```
Para obter mais informações, consulte [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
Obtém informações detalhadas sobre uma execução de trabalho.
Você pode definir o `jobId` como `$next` para retornar a próxima execução de trabalho pendente para um objeto. O status da execução do trabalho deve ser `QUEUED` ou `IN_PROGRESS`.
------
#### [ HTTPS request ]
Solicitação:
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
```
Resposta:
```
{
"execution" : JobExecution,
}
```
Para obter mais informações, consulte [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 ]
**Resumo:**
```
aws iot-jobs-data describe-job-execution \
--job-id \
--thing-name \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}
```
Para obter mais informações, consulte [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
Atualiza o status de uma execução de trabalho. Se desejar, você pode criar um temporizador de etapa definindo um valor para a propriedade `stepTimeoutInMinutes`. Se você não atualizar o valor dessa propriedade executando `UpdateJobExecution` novamente, a execução do trabalho atingirá o tempo limite quando o temporizador de etapa expirar.
------
#### [ HTTPS request ]
Solicitação:
```
POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long
}
```
Para obter mais informações, consulte [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 ]
**Resumo:**
```
aws iot-jobs-data update-job-execution \
--job-id \
--thing-name \
--status \
[--status-details ] \
[--expected-version ] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--step-timeout-in-minutes ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}
```
Para obter mais informações, consulte [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).
------