Tipos de dados e API de controle e gerenciamento de trabalhos - AWS IoT Core

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á.

Tipos de dados e API de controle e gerenciamento de trabalhos

Os comandos a seguir estão disponíveis para aplicativos de gerenciamento e controle de trabalhos na CLI e por meio do protocolo HTTPS.

Para determinar o parâmetro endpoint-url 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 z-amzn-http-ca ALPN.

Tipos de dados de gerenciamento e controle de trabalhos

Os seguintes tipos de dados são usados pelos aplicativos de gerenciamento e controle para comunicação com o serviço Jobs de AWS IoT.

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 ter mais informações, consulte Job ou job.

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 ter mais informações, consulte JobSummary ou job-summary.

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 GetJobDocument ou o comando da CLI get-job-document.

{ "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 ter mais informações, consulte JobExecution ou job-execution.

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 ter mais informações, consulte JobExecutionSummary ou job-execution-summary.

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 ter mais informações, consulte JobExecutionSummaryForJob ou job-execution-summary-for-job.

O objeto JobExecutionSummaryForThing contém um resumo das informações sobre a execução de um trabalho de um objeto específica. O exemplo a seguir mostra a sintaxe:

{ "executionSummaries": [ { "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1549395301.389, "queuedAt": 1541526002.609, "executionNumber": 1 }, "jobId": "MyThingJob" }, ... ] }

Para ter mais informações, consulte JobExecutionSummaryForThing ou job-execution-summary-for-thing.

Operações de API de gerenciamento e controle de trabalhos

Use um dos seguintes comandos da CLI ou operações da API:

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 AssociateTargetsWithJob.

CLI syntax
aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "targets": [ "string" ], "jobId": "string", "comment": "string" }

Para obter mais informações, consulte associate-targets-with-job.

Cancela um trabalho.

HTTPS request
PUT /jobs/jobId/cancel { "force": boolean, "comment": "string", "reasonCode": "string" }

Para obter mais informações, consulte CancelJob.

CLI syntax
aws iot cancel-job \ --job-id <value> \ [--force <value>] \ [--comment <value>] \ [--reasonCode <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "force": boolean, "comment": "string" }

Para obter mais informações, consulte cancel-job.

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 CancelJobExecution.

CLI syntax
aws iot cancel-job-execution \ --job-id <value> \ --thing-name <value> \ [--force | --no-force] \ [--expected-version <value>] \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "force": boolean, "expectedVersion": long, "statusDetails": { "string": "string" } }

Para obter mais informações, consulte cancel-job-execution.

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 TimeoutConfig opcional, que define o valor do temporizador 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 argumento targets deve ser uma lista de ARNs válidos de objetos ou de grupos de objetos. Todas as objetos e grupos de objetos devem estar em sua Conta da AWS.

  • O argumento documentSource deve ser um URL válido do Amazon S3 para um documento de trabalho. Os URLs do Amazon S3 estão 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.

  • O jobId deve ser exclusivo na sua 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 CreateJob.

CLI syntax
aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--job-template-arn <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--abort-config <value>] \ [--timeout-config <value>] \ [--document-parameters <value>] \ [--cli-input-json <value>] \ [--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 create-job.

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_IN_PROGRESS". A tentativa de excluir ou cancelar um trabalho cujo status já seja "DELETION_IN_PROGRESS" resulta em um erro.

HTTPS request
DELETE /jobs/jobId?force=force

Para obter mais informações, consulte DeleteJob.

CLI syntax
aws iot delete-job \ --job-id <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "force": boolean }

Para obter mais informações, consulte delete-job.

Exclui uma execução de trabalho.

HTTPS request
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force

Para obter mais informações, consulte DeleteJobExecution.

CLI syntax
aws iot delete-job-execution \ --job-id <value> \ --thing-name <value> \ --execution-number <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "executionNumber": long, "force": boolean }

Para obter mais informações, consulte delete-job-execution.

Obtém os detalhes da execução do trabalho.

HTTPS request
GET /jobs/jobId

Para obter mais informações, consulte DescribeJob.

CLI syntax
aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string" }

Para obter mais informações, consulte describe-job.

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 DescribeJobExecution.

CLI syntax
aws iot describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "executionNumber": long }

Para obter mais informações, consulte describe-job-execution.

Obtém o documento de trabalho para um trabalho.

nota

URLs de espaço reservado não são substituídos por URLs do Amazon S3 pré-assinados no documento retornado. As pre-signed URLs são geradas apenas quando o serviço Jobs da AWS IoT recebe uma solicitação por meio do MQTT.

HTTPS request
GET /jobs/jobId/job-document

Para obter mais informações, consulte GetJobDocument.

CLI syntax
aws iot get-job-document \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string" }

Para obter mais informações, consulte get-job-document.

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 ListJobExecutionsForJob.

CLI syntax
aws iot list-job-executions-for-job \ --job-id <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

Para obter mais informações, consulte list-job-executions-for-job.

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 ListJobExecutionsForThing.

CLI syntax
aws iot list-job-executions-for-thing \ --thing-name <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

Para obter mais informações, consulte list-job-executions-for-thing.

Obtém uma lista de trabalhos em sua 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 ListJobs.

CLI syntax
aws iot list-jobs \ [--status <value>] \ [--target-selection <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--thing-group-name <value>] \ [--thing-group-id <value>] \ [--cli-input-json <value>] \ [--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 list-jobs.

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 UpdateJob.

CLI syntax
aws iot update-job \ --job-id <value> \ [--description <value>] \ [--presigned-url-config <value>] \ [--job-executions-rollout-config <value>] \ [--abort-config <value>] \ [--timeout-config <value>] \ [--cli-input-json <value>] \ [--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 update-job.