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

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.

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

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.

Cancela um trabalho.

Cancela uma execução de trabalho em um dispositivo.

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.

Exclui uma execução de trabalho.

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

Obtém os detalhes da execução de um trabalho. O status da execução do trabalho deve ser SUCCEEDED ou FAILED.

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.

Obtém uma lista de execuções de trabalhos para um trabalho.

Obtém uma lista de execuções de trabalhos para um objeto.

Obtém uma lista de trabalhos em sua Conta da AWS.

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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Operações de API dos trabalhos do AWS IoT

Tipos de dados e operações da API MQTT e HTTPS do dispositivo de trabalhos