API de administración y control de trabajos y tipos de datos - AWS IoT Core

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

API de administración y control de trabajos y tipos de datos

Los siguientes comandos están disponibles para la administración y control de trabajos en la CLI a través del protocolo HTTPS.

Para determinar el parámetro endpoint-url de los comandos de la CLI, ejecute este comando.

aws iot describe-endpoint --endpoint-type=iot:Jobs

Este comando devuelve la siguiente salida.

{ "endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com" }
nota

El punto de conexión de Jobs no admite la ALPN z-amzn-http-ca.

Tipos de datos de administración y control de trabajo

Las aplicaciones de administración y control utilizan los siguientes tipos de datos para comunicarse con Jobs de AWS IoT.

El objeto Job contiene detalles acerca de un trabajo. En el siguiente ejemplo se muestra la sintaxis:

{ "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 obtener más información, consulte Job o job.

El objeto JobSummary contiene un resumen de trabajos. En el siguiente ejemplo se muestra la sintaxis:

{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED", "targetSelection": "CONTINUOUS|SNAPSHOT", "thingGroupId": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp }

Para obtener más información, consulte JobSummary o job-summary.

El objeto JobExecution representa la ejecución de un trabajo en un dispositivo. En el siguiente ejemplo se muestra la sintaxis:

nota

Cuando se utilizan las operaciones de la API del plano de control, el tipo de datos JobExecution no contiene ningún campo JobDocument. Para obtener esta información, puede utilizar la operación GetJobDocument de la API o el comando get-job-document de la CLI.

{ "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 obtener más información, consulte JobExecution o job-execution.

El objeto JobExecutionSummary contiene información del resumen de ejecución de trabajo. En el siguiente ejemplo se muestra la sintaxis:

{ "executionNumber": 1234567890, "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED" }

Para obtener más información, consulte JobExecutionSummary o job-execution-summary.

El objeto JobExecutionSummaryForJob contiene un resumen de información acerca de las ejecuciones de trabajo para un trabajo específico. En el siguiente ejemplo se muestra la sintaxis:

{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1549395301.389, "queuedAt": 1541526002.609, "executionNumber": 1 } }, ... ] }

Para obtener más información, consulte JobExecutionSummaryForJob o job-execution-summary-for-job.

El objeto JobExecutionSummaryForThing contiene un resumen de información acerca de una ejecución de trabajo en un objeto específico. En el siguiente ejemplo se muestra la sintaxis:

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

Para obtener más información, consulte JobExecutionSummaryForThing o job-execution-summary-for-thing.

Operaciones de la API de administración y control del trabajo

Utilice las siguientes operaciones de la API o comandos de la CLI:

Asocia un grupo a un trabajo continuo. Deben cumplirse los siguientes criterios:

  • El trabajo debe haberse creado con el campo targetSelection establecido en CONTINUOUS.

  • El estado del trabajo debe ser actualmente IN_PROGRESS.

  • El número total de destinos asociados con un trabajo no debe ser superior a 100.

HTTPS request
POST /jobs/jobId/targets { "targets": [ "string" ], "comment": "string" }

Para obtener más información, 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 formato:

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

Para obtener más información, consulte associate-targets-with-job.

Cancela un trabajo.

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

Para obtener más información, 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 formato:

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

Para obtener más información, consulte cancel-job.

Cancela la ejecución de un trabajo en un dispositivo.

HTTPS request
PUT /things/thingName/jobs/jobId/cancel { "force": boolean, "expectedVersion": "string", "statusDetails": { "string": "string" ... } }

Para obtener más información, 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 formato:

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

Para obtener más información, consulte cancel-job-execution.

Crea un trabajo. Puede proporcionar el documento de trabajo como enlace a un archivo en un bucket de Amazon S3 (parámetro documentSource) o en el cuerpo de la solicitud (parámetro document).

Un trabajo puede ser continuo si se establece el parámetro opcional targetSelection en CONTINUOUS (el predeterminado es SNAPSHOT). Un trabajo continuo se puede usar para incorporar o actualizar los dispositivos a medida que se agregan a un grupo, ya que continúa ejecutándose y se lanza cuando se agregan nuevos objetos. Esto puede ocurrir incluso después de que los objetos del grupo en el momento en que se creó el trabajo lo hayan completado.

Un trabajo puede tener un valor TimeoutConfig opcional que establece el valor del temporizador en curso. El temporizador en curso no se puede actualizar y se aplica a todas las ejecuciones del trabajo.

Se realizan las siguientes validaciones en los argumentos para la API CreateJob:

  • El argumento targets debe ser una lista de ARN de grupo de objetos u objetos válidos. Todos los objetos y grupos de objetos deben estar en la Cuenta de AWS.

  • El argumento documentSource debe ser una URL de Amazon S3 válida para un documento de trabajo. Las URL de Amazon S3 tienen el formato: https://s3.amazonaws.com/bucketName/objectName.

  • El documento almacenado en la URL especificada por el argumento documentSource debe ser un documento JSON con codificación UTF-8.

  • El tamaño del documento de trabajo está limitado a 32 KB debido al límite del tamaño de un mensaje MQTT (128 KB) y el cifrado.

  • El jobId debe ser único en la Cuenta de 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 obtener más información, 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 formato:

{ "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 obtener más información, consulte create-job.

Elimina un trabajo y sus ejecuciones de trabajo relacionadas.

La eliminación de un trabajo puede tardar tiempo, en función del número de ejecuciones de trabajo creadas para el trabajo y otros factores diversos. Aunque el trabajo se está eliminando, el estado del trabajo se muestra como "DELETION_IN_PROGRESS". Si se intenta eliminar o cancelar un trabajo cuyo estado ya es DELETION_IN_PROGRESS, se producirá un error.

HTTPS request
DELETE /jobs/jobId?force=force

Para obtener más información, consulte DeleteJob.

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

cli-input-json formato:

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

Para obtener más información, consulte delete-job.

Elimina una ejecución de trabajo.

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

Para obtener más información, 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 formato:

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

Para obtener más información, consulte delete-job-execution.

Obtiene los detalles de la ejecución de trabajo.

HTTPS request
GET /jobs/jobId

Para obtener más información, consulte DescribeJob.

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

cli-input-json formato:

{ "jobId": "string" }

Para obtener más información, consulte describe-job.

Obtiene los detalles de una ejecución de trabajo. El estado de la ejecución del trabajo debe ser SUCCEEDED o FAILED.

HTTPS request
GET /things/thingName/jobs/jobId?executionNumber=executionNumber

Para obtener más información, 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 formato:

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

Para obtener más información, consulte describe-job-execution.

Obtiene el documento de trabajo para un trabajo.

nota

Las URL de marcador de posición no se reemplazan por las URL de Amazon S3 prefirmadas en el documento devuelto. Las URL prefirmadas se generan solo cuando el servicio Jobs de AWS IoT recibe una solicitud a través de MQTT.

HTTPS request
GET /jobs/jobId/job-document

Para obtener más información, consulte GetJobDocument.

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

cli-input-json formato:

{ "jobId": "string" }

Para obtener más información, consulte get-job-document.

Obtiene una lista de ejecuciones de trabajo para un trabajo.

HTTPS request
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken

Para obtener más información, 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 formato:

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

Para obtener más información, consulte list-job-executions-for-job.

Obtiene una lista de ejecuciones de trabajo para un objeto.

HTTPS request
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken

Para obtener más información, 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 formato:

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

Para obtener más información, consulte list-job-executions-for-thing.

Obtiene una lista de trabajos en la Cuenta de AWS.

HTTPS request
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken

Para obtener más información, 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 formato:

{ "status": "string", "targetSelection": "string", "maxResults": "integer", "nextToken": "string", "thingGroupName": "string", "thingGroupId": "string" }

Para obtener más información, consulte list-jobs.

Actualiza los campos admitidos del trabajo especificado. Los valores actualizados de timeoutConfig surten efecto solo en lanzamientos recientemente en curso. Actualmente, los lanzamientos en curso siguen lanzándose con la configuración de tiempo de espera 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 obtener más información, 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 formato:

{ "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 obtener más información, consulte update-job.