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á.
Crie e gerencie trabalhos usando o AWS CLI
Esta seção descreve como criar e gerenciar trabalhos.
Criar trabalhos
Para criar um trabalho da AWS IoT, use o comando CreateJob. O trabalho é enfileirado para execução nos destinos (objetos ou grupos de objetos) que você especifica. Para criar um trabalho da AWS IoT, você precisa de um documento de trabalho que possa ser incluído no corpo da solicitação ou como link para um documento do Amazon S3. Se o trabalho incluir arquivos de download que usam URLs pré-assinados do Amazon S3, você precisará de um nome do recurso da Amazon (ARN) do perfil do IAM que tenha permissão para fazer download do arquivo e conceda permissão ao serviço de trabalhos da AWS IoT para assumir a função.
Para obter mais informações sobre a sintaxe ao inserir a data e a hora usando um comando da API ou o AWS CLI, consulte Timestamp.
Assinatura de código com trabalhos
Se estiver usando a assinatura de código para a AWS IoT, você deve iniciar um trabalho de assinatura de código e incluir a saída no seu documento de trabalho. Isso substituirá o espaço reservado para assinatura de código em seu documento de trabalho, que é necessário como espaço reservado até que seja substituído pelo caminho do arquivo de código assinado usando seu perfil de assinatura de código. O espaço reservado para assinatura de código será exibido da seguinte forma:
${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}
Use o comando start-signing-job para criar um trabalho de assinatura de código. start-signing-job retorna um ID de trabalho. Use o comando describe-signing-job para obter o local do Amazon S3 onde a assinatura é armazenada. Em seguida, você pode baixar a assinatura do Amazon S3. Para obter mais informações sobre trabalhos de assinatura de código, consulte Assinatura de código do AWS IoT.
Seu documento de trabalho deve conter um espaço reservado de pré-assinatura do URL para o arquivo de código e a saída da assinatura JSON inserida em um bucket do Amazon S3 usando o comando start-signing-job:
{ "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", }
Criar um trabalho com um documento de trabalho
O comando a seguir mostra como criar um trabalho usando um documento de trabalho (job-document.json) armazenado em um bucket do Amazon S3 (jobBucket) e uma função com permissão para fazer download de arquivos do Amazon S3 (S3DownloadRole).
aws iot create-job \ --job-id 010 \ --targetsarn:aws:iot:us-east-1:123456789012:thing/thingOne\ --document-sourcehttps://s3.amazonaws.com/my-s3-bucket/job-document.json\ --timeout-config inProgressTimeoutInMinutes=100\ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\":50, \"incrementFactor\":2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\":1000, \"numberOfSucceededThings\":1000}}, \"maximumPerMinute\":1000}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\":100, \"thresholdPercentage\":20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\":200, \"thresholdPercentage\":50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
O trabalho é executado no thingOne.
O parâmetro timeout-config opcional especifica o tempo que cada dispositivo tem para concluir a execução do trabalho. O temporizador é iniciado quando o status da execução do trabalho é definido como IN_PROGRESS. Se o status da execução do trabalho não estiver definido como outro estado terminal antes que o tempo expire, ele será definido como TIMED_OUT.
O temporizador em andamento não pode ser atualizado e é aplicado a todas as execuções do trabalho. Sempre que uma execução de trabalho permanece no estado IN_PROGRESS por mais tempo que esse intervalo, ela falha e alterna para o status TIMED_OUT terminal. O AWS IoT também publica uma notificação MQTT.
Para obter mais informações sobre como criar configurações para distribuir e anular trabalhos, consulte Configuração para Distribuir e Anular Trabalhos.
nota
Os documentos de trabalho que são especificados como arquivos do Amazon S3 são recuperados no momento em que você cria o trabalho. Se você alterar o conteúdo do arquivo do Amazon S3 que você usou como a origem de seu documento de trabalho depois de ter criado o documento de trabalho, o que é enviado para os destinos do trabalho não é alterado.
Atualizar um trabalho
Para atualizar um trabalho, use o comando UpdateJob. Você pode atualizar os campos description, presignedUrlConfig, jobExecutionsRolloutConfig, abortConfig e timeoutConfig de um trabalho.
aws iot update-job \ --job-id 010 \ --description "updated description" \ --timeout-config inProgressTimeoutInMinutes=100\ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\":50, \"incrementFactor\":2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\":1000, \"numberOfSucceededThings\":1000}, \"maximumPerMinute\":1000}}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\":100, \"thresholdPercentage\":20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\":200, \"thresholdPercentage\":50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
Para obter mais informações, consulte Configuração de distribuição e anulação de trabalhos.
Cancelar um trabalho
Para cancelar um trabalho, use o comando CancelJob. O cancelamento de um trabalho fará com que a AWS IoT pare de distribuir novas execuções do trabalho. Ele também cancela as execuções de trabalho que estão em um estado QUEUED. A AWS IoT mantém as execuções de trabalho em um estado terminal inalteradas se o dispositivo já concluiu o trabalho. Se o status de uma execução de trabalho for IN_PROGRESS, ele também permanecerá inalterado, a menos que você use o parâmetro opcional --force.
O comando a seguir mostra como cancelar um trabalho com ID 010.
aws iot cancel-job --job-id 010
O comando exibe a seguinte saída:
{ "jobArn": "string", "jobId": "string", "description": "string" }
Ao cancelar um trabalho, as execuções de trabalho em estado QUEUED serão canceladas. As execuções de trabalho em estado IN_PROGRESS serão canceladas, mas somente se você especificar o parâmetro opcional --force. As execuções de trabalhos em estado terminal não são canceladas.
Atenção
O cancelamento de um trabalho no estado IN_PROGRESS (por meio da definição do parâmetro --force) cancelará qualquer execução de trabalho em andamento e impedirá que o dispositivo que está executando o trabalho atualize o status da execução do trabalho. Tenha cuidado e certifique-se de que todo dispositivo que esteja executando um trabalho cancelado possa ser recuperado para um estado válido.
O status de um trabalho cancelado ou de uma de suas execuções em algum momento torna-se consistente. A AWS IoT interrompe o mais rápido possível a programação de novas execuções QUEUED e não apresenta execuções desse trabalho aos dispositivos. A alteração do status de uma execução de trabalho para CANCELED pode levar algum tempo, dependendo do número de dispositivos e de outros fatores.
Se um trabalho for cancelado porque atende aos critérios definidos por um objeto AbortConfig, o serviço adicionará valores de preenchimento automático para os campos comment e reasonCode. É possível criar seus próprios valores de reasonCode se o cancelamento de trabalho for acionado pelo usuário.
Cancelar uma execução de trabalho
Use o comando CancelJobExecution para cancelar uma execução de trabalho em um dispositivo. Ele cancelará uma execução de trabalho que esteja em estado QUEUED. Se desejar cancelar uma execução de trabalho em andamento, deverá usar o parâmetro --force.
O comando a seguir mostra como cancelar a execução de trabalho 010 em execução em myThing.
aws iot cancel-job-execution --job-id 010 --thing-name myThing
O comando não exibe nenhuma saída.
Uma execução de trabalho que esteja em estado QUEUED será cancelada. Uma execução de trabalho em estado IN_PROGRESS será cancelada, mas somente se você especificar o parâmetro opcional --force. As execuções de trabalho em estado terminal não podem ser canceladas.
Atenção
Cancelar uma execução de trabalho em estado IN_PROGRESS impedirá que o dispositivo atualize o status da execução do trabalho. Tenha cuidado e certifique-se de que o dispositivo possa ser recuperado para um estado válido.
Se a execução do trabalho estiver em estado terminal ou em estado IN_PROGRESS e o parâmetro --force não estiver definido como true, esse comando gerará InvalidStateTransitionException.
O status de uma execução de trabalho cancelada é eventualmente consistente. A alteração do status de uma execução de trabalho para CANCELED pode levar algum tempo, dependendo de vários fatores.
Excluir um trabalho
Use o comando DeleteJob para excluir um trabalho e suas execuções de trabalho. Por padrão, você só pode excluir um trabalho em estado terminal (SUCCEEDED ou CANCELED). Caso contrário, ocorrerá uma exceção. Você pode excluir um trabalho em estado IN_PROGRESS, mas somente se o parâmetro force for definido como true.
Para excluir um trabalho, execute o comando a seguir:
aws iot delete-job --job-id 010 --force|--no-force
O comando não exibe nenhuma saída.
Atenção
Ao excluir um trabalho no estado IN_PROGRESS, o dispositivo que está executando o trabalho não pode acessar informações do trabalho nem atualizar o status da execução do trabalho. Tenha cuidado e certifique-se de que todo dispositivo executando um trabalho que tenha sido excluído possa ser recuperado para um estado válido.
A exclusão de um trabalho pode levar algum tempo, dependendo do número de execuções criadas para o trabalho e de outros fatores. Enquanto o trabalho está sendo excluído, DELETION_IN_PROGRESS aparece como status do trabalho. Ocorrerá erro se você tentar excluir ou cancelar um trabalho cujo status já seja DELETION_IN_PROGRESS.
Somente 10 trabalhos podem ter, simultaneamente, o status DELETION_IN_PROGRESS. Caso contrário, um LimitExceededException ocorre.
Obter um documento de trabalho
Use o comando GetJobDocument para recuperar um documento de trabalho para um trabalho. Um documento de trabalho é uma descrição das operações remotas a serem realizadas pelos dispositivos.
Execute o seguinte comando para obter um documento de trabalho:
aws iot get-job-document --job-id 010
O comando retorna o documento de trabalho para o trabalho especificado:
{ "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/job-test-bucket/datafile}\"\n}" }
nota
Quando você usa esse comando para recuperar um documento de trabalho, URLs de espaço reservado são substituídas por pré-assinadas URLs do . Quando um dispositivo chama a operação de API GetPendingJobExecutions, as URLs de espaço reservado são substituídas por URLs pré-assinadas do Amazon S3 no documento de trabalho.
Listar trabalhos
Para obter uma lista de todos os trabalhos em sua Conta da AWS, use o comando ListJobs . Os dados do trabalho e os dados de execução do trabalho são retidos por um tempo limitado. Execute o comando a seguir para listar todos os trabalhos em sua Conta da AWS:
aws iot list-jobs
O comando retorna todos os trabalhos em sua conta, classificados pelo status do trabalho:
{ "jobs": [ { "status": "IN_PROGRESS", "lastUpdatedAt": 1486687079.743, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", "createdAt": 1486687079.743, "targetSelection": "SNAPSHOT", "jobId": "013" }, { "status": "SUCCEEDED", "lastUpdatedAt": 1486685868.444, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", "createdAt": 1486685868.444, "completedAt": 148668789.690, "targetSelection": "SNAPSHOT", "jobId": "012" }, { "status": "CANCELED", "lastUpdatedAt": 1486678850.575, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", "createdAt": 1486678850.575, "targetSelection": "SNAPSHOT", "jobId": "011" } ] }
Descrever um trabalho
Execute o comando DescribeJob para obter o status de um trabalho. O comando a seguir mostra como descrever um trabalho:
$ aws iot describe-job --job-id 010
O comando retorna o status do trabalho especificado. Por exemplo:
{ "documentSource": "https://s3.amazonaws.com/job-test-bucket/job-document.json", "job": { "status": "IN_PROGRESS", "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/myThing" ], "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfFailedThings": 0, "numberOfInProgressThings": 0, "numberOfQueuedThings": 0, "numberOfRejectedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 0, "numberOfTimedOutThings": 0, "processingTargets": [ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ] }, "presignedUrlConfig": { "expiresInSec": 60, "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole" }, "jobId": "010", "lastUpdatedAt": 1486593195.006, "createdAt": 1486593195.006, "targetSelection": "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 } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } } }
Listar execuções para um trabalho
Um trabalho em execução em um dispositivo específico é representado por um objeto de execução de trabalho. Execute o comando ListJobExecutionsForJob para listar todas as execuções de um trabalho. O exemplo a seguir mostra como listar as execuções de um trabalho:
aws iot list-job-executions-for-job --job-id 010
O comando retorna uma lista de execuções do trabalho:
{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 1234567890 } }, { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1486593345.659, "queuedAt": 1486593196.378, "startedAt": 1486593345.659, "executionNumber": 4567890123 } } ] }
Listar execuções de trabalho para um objeto
Execute o comando ListJobExecutionsForThing para listar todas as execuções de trabalho em execução em um objeto. O exemplo a seguir mostra como listar execuções de trabalho para um objeto:
aws iot list-job-executions-for-thing --thing-name thingOne
O comando retorna uma lista de execuções de trabalho que estão em execução ou que executaram no objeto especificada:
{ "executionSummaries": [ { "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486687082.071, "queuedAt": 1486687082.071, "executionNumber": 9876543210 }, "jobId": "013" }, { "jobExecutionSummary": { "status": "IN_PROGRESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "SUCCEEDED", "startAt": 1486678853.415, "lastUpdatedAt": 1486678853.415, "queuedAt": 1486678853.415, "executionNumber": 4357680912 }, "jobId": "011" }, { "jobExecutionSummary": { "status": "CANCELED", "startAt": 1486593196.378, "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 2143174250 }, "jobId": "010" } ] }
Descrever a execução do trabalho
Execute o comando DescribeJobExecution para obter o status de execução de um trabalho. Você deve especificar um ID de trabalho e um nome de objeto e, opcionalmente, um número de execução para identificar a execução do trabalho. O comando a seguir mostra como descrever a execução de um trabalho:
aws iot describe-job-execution --job-id 017 --thing-name thingOne
O comando retorna a JobExecution. Por exemplo:
{ "execution": { "jobId": "017", "executionNumber": 4516820379, "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "versionNumber": 123, "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "approximateSecondsBeforeTimedOut": 100, "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }
Excluir uma execução de trabalho
Execute o comando DeleteJobExecution para excluir a execução de um trabalho. Você deve especificar um ID de trabalho, um nome de objeto e um número de execução para identificar a execução do trabalho. O comando a seguir mostra como excluir a execução de um trabalho:
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force
O comando não exibe nenhuma saída.
Por padrão, o status de execução do trabalho deve ser QUEUED ou em estado terminal (SUCCEEDED, FAILED, REJECTED, TIMED_OUT, REMOVED ou CANCELED). Caso contrário, ocorrerá um erro. Para excluir uma execução de trabalho com status IN_PROGRESS, você pode definir o parâmetro force como true.
Atenção
Ao excluir uma execução de trabalho com status IN_PROGRESS, o dispositivo que está executando o trabalho não pode acessar informações do trabalho nem atualizar o status da execução do trabalho. Tenha cuidado e certifique-se de que o dispositivo possa ser recuperado para um estado válido.
