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.
Creación y administración de trabajos mediante la AWS CLI
En esta sección se describe cómo crear y administrar trabajos.
Creación de trabajos
Para crear un trabajo de AWS IoT, utilice el comando CreateJob. El trabajo se pone en cola para la ejecución en los destinos (objetos o grupos de objetos) que especifique. Para crear un trabajo de AWS IoT necesita un documento de trabajo que pueda incluirse en el cuerpo de la solicitud o como un enlace a un documento de Amazon S3. Si el trabajo incluye la descarga de archivos mediante direcciones URL de Amazon S3 prefirmadas, necesita un nombre de recurso de Amazon (ARN) de un rol de IAM que tenga permiso para descargar el archivo y conceda permiso al servicio Jobs de AWS IoT para asumir el rol.
Para obtener más información sobre la sintaxis cuando se introduce la fecha y hora mediante un comando de la API o la AWS CLI, consulte Marca temporal.
Firma de código con trabajos
Si utiliza la firma de código para AWS IoT, debe iniciar un trabajo de firma de código e incluir el resultado en el documento del trabajo. Esto sustituirá al marcador de posición de firma de código del documento de trabajo, que es obligatorio como marcador de posición hasta que se sustituya por la ruta del archivo de código firmada mediante su Perfil de firma de código. El marcador de la firma de código tendrá el siguiente aspecto:
${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}
Utilice el comando start-signing-job para crear un trabajo de firma de código. start-signing-job devuelve un ID de trabajo. Utilice el comando describe-signing-job para obtener la ubicación de Amazon S3 donde se almacena la firma. Después podrá descargar la firma desde Amazon S3. Para obtener más información sobre trabajos de firma de código, consulte la sección sobre Firma de código para AWS IoT.
El documento de trabajo debe contener un marcador de posición de URL prefirmada para su archivo de código y el resultado de la firma JSON en un bucket de Amazon S3 con el comando start-signing-job:
{ "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", }
Creación de un trabajo con un documento de trabajo
El siguiente comando muestra cómo crear un trabajo mediante un documento de trabajo (job-document.json) almacenado en un bucket de Amazon S3 (jobBucket) y un rol con permiso para descargar archivos desde 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}"
El trabajo se ejecuta en thingOne.
El parámetro timeout-config opcional especifica la cantidad de tiempo que cada dispositivo tiene para finalizar su ejecución del trabajo. El temporizador comienza cuando el estado de ejecución del trabajo se establece en IN_PROGRESS. Si el estado de ejecución del trabajo no se establece en otro estado terminal antes de que se cumpla el plazo, se establecerá en TIMED_OUT.
El temporizador en curso no se puede actualizar y se aplica a todas las ejecuciones de trabajos para el trabajo. Cuando la ejecución de un trabajo permanece en estado IN_PROGRESS durante un periodo superior a este intervalo, producirá un error y cambiará al estado final TIMED_OUT. AWS IoT también publica una notificación MQTT.
Para obtener más información acerca de cómo crear configuraciones sobre despliegues de trabajos y anulaciones, consulte Despliegue de trabajos y configuración de anulaciones.
nota
Los documentos de trabajo que está especificados como archivos de Amazon S3 se recuperan en el momento en el que crea el trabajo. Si cambia el contenido del archivo de Amazon S3 que usó como origen de su documento de trabajo después de haberlo creado, no cambia lo que se envía a los destinos del trabajo.
Actualización de un trabajo
Para actualizar un trabajo se utiliza el comando UpdateJob. Puede actualizar los campos description, presignedUrlConfig, jobExecutionsRolloutConfig, abortConfig y timeoutConfig para un trabajo.
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 obtener más información, consulte Despliegue de trabajos y configuración de anulaciones.
Cancelación de un trabajo
Para cancelar un trabajo se utiliza el comando CancelJob. Al cancelar un trabajo, AWS IoT dejará de desplegar nuevas ejecuciones de trabajos para el trabajo. También cancela la ejecución de cualquier trabajo que se encuentre en estado QUEUED. AWS IoT deja las ejecuciones de los trabajos en estado final intactas, ya que el dispositivo ya ha completado el trabajo. Si el estado de la ejecución de un trabajo es IN_PROGRESS, también se mantendrá intacta a menos que se use el parámetro opcional --force.
El siguiente comando muestra cómo cancelar un trabajo con ID 010.
aws iot cancel-job --job-id 010
El comando muestra el resultado siguiente:
{ "jobArn": "string", "jobId": "string", "description": "string" }
Cuando se cancela un trabajo, se cancelan las ejecuciones de trabajos con estado QUEUED. Las ejecuciones de trabajos en estado IN_PROGRESS se cancelarán, pero solo si especifica el parámetro opcional --force. Las ejecuciones de trabajo con un estado terminal no se cancelarán.
aviso
Si se cancela un trabajo en estado IN_PROGRESS (al establecer el parámetro --force), se cancelarán las ejecuciones de trabajos en curso, y se hará que el dispositivo que está ejecutando el trabajo no pueda actualizar el estado de ejecución del trabajo. Actúe con precaución y asegúrese de que cada dispositivo que esté ejecutando un trabajo cancelado pueda recuperarse a un estado válido.
El estado de un trabajo cancelado o de una de sus ejecuciones de trabajos es a la larga coherente: AWS IoT detiene lo antes posible la programación de nuevas ejecuciones de trabajos y las ejecuciones en dispositivos de trabajos con estado QUEUED. Cambiar el estado de la ejecución de un trabajo a CANCELED puede llevar algo de tiempo, según el número de dispositivos y otros factores.
Si un trabajo se cancela porque cumple los criterios definidos por un objeto AbortConfig, el servicio añade valores rellenados automáticamente para los campos comment y reasonCode. Puede crear sus propios valores reasonCode cuando el trabajo se cancela por iniciativa del usuario.
Cancelación de una ejecución de trabajo
Para cancelar la ejecución de un trabajo en un dispositivo, utilice el comando CancelJobExecution. Este cancela la ejecución de un trabajo que se encuentra en estado QUEUED. Si desea cancelar la ejecución de un trabajo en curso, debe utilizar el parámetro --force.
El siguiente comando muestra cómo cancelar la ejecución de un trabajo del trabajo 010 que se ejecuta en myThing.
aws iot cancel-job-execution --job-id 010 --thing-name myThing
El comando no muestra ninguna salida.
Se cancela la ejecución de un trabajo que se encuentra en estado QUEUED. La ejecución de un trabajo en estado IN_PROGRESS se cancela, pero solo si especifica el parámetro opcional --force. Las ejecuciones de trabajo con un estado terminal no se pueden cancelar.
aviso
Cuando se cancela la ejecución de un trabajo con estado IN_PROGRESS, el dispositivo no puede actualizar el estado de ejecución del trabajo. Actúe con precaución y asegúrese de que el dispositivo pueda recuperarse a un estado válido.
Si la ejecución del trabajo se encuentra en estado final, o si la ejecución del trabajo está en estado IN_PROGRESS y el parámetro --force no está definido en true, el comando genera InvalidStateTransitionException.
El estado de la ejecución de un trabajo cancelada es a la larga coherente. Cambiar el estado de la ejecución de un trabajo a CANCELED puede llevar algo de tiempo, dependiendo de varios factores.
Eliminación de un trabajo
Para eliminar un trabajo y sus ejecuciones, utilice el comando DeleteJob. De forma predeterminada, solo puede eliminar un trabajo en estado final (SUCCEEDED o CANCELED). En caso contrario, se produce una excepción. Podrá eliminar un trabajo con estado IN_PROGRESS, aunque solo si el parámetro force está definido en true.
Para eliminar un trabajo, ejecute el siguiente comando:
aws iot delete-job --job-id 010 --force|--no-force
El comando no muestra ninguna salida.
aviso
Cuando se elimina un trabajo que se encuentra en estado IN_PROGRESS, el dispositivo que está implementando el trabajo no puede obtener acceso a la información del trabajo ni actualizar el estado de su ejecución. Actúe con precaución y asegúrese de que cada dispositivo que implemente un trabajo eliminado pueda recuperarse a un estado válido.
Eliminar un trabajo podría llevar algún tiempo, en función del número de ejecuciones de trabajos creadas para el trabajo y otros factores. Aunque el trabajo se esté eliminando, como estado del trabajo se muestra DELETION_IN_PROGRESS. Si se intenta eliminar o cancelar un trabajo cuyo estado ya es DELETION_IN_PROGRESS, se producirá un error.
Solo puede haber 10 trabajos con estado DELETION_IN_PROGRESS al mismo tiempo. De lo contrario, se genera LimitExceededException.
Obtención de un documento de trabajo
Para recuperar un documento de trabajo para un trabajo, utilice el comando GetJobDocument. Un documento de trabajo es una descripción de las operaciones remotas que deben ejecutar los dispositivos.
Para obtener un documento de trabajo, ejecute el siguiente comando:
aws iot get-job-document --job-id 010
El comando devuelve el documento de trabajo para el trabajo 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
Al usar este comando para recuperar un documento de trabajo, las URL de marcador de posición no se sustituirán por URL de Amazon S3 prefirmadas. Cuando un dispositivo llama a la operación GetPendingJobExecutions de la API, las URL de marcador de posición se sustituyen por URL de Amazon S3 prefirmadas en el documento de trabajo.
Enumeración de trabajos
Para obtener una lista de todos los trabajos de su Cuenta de AWS, utilice el comando ListJobs. Los datos del trabajo y los datos de ejecución del trabajo se conservan durante un tiempo limitado. Ejecute el siguiente comando para listar todos los trabajos de su Cuenta de AWS:
aws iot list-jobs
El comando devuelve todos los trabajos en su cuenta ordenados por estado del trabajo:
{ "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" } ] }
Descripción de un trabajo
Para obtener el estado de un trabajo, ejecute el comando DescribeJob. El siguiente comando muestra cómo describir un trabajo:
$ aws iot describe-job --job-id 010
El comando devuelve el estado de un trabajo especificado. Por ejemplo:
{ "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 } } }
Enumeración de ejecuciones para un trabajo
Un trabajo que se ejecuta en un dispositivo específico se representa mediante un objeto de ejecución de trabajo. Ejecute el comando ListJobExecutionsForJob para enumerar todas las ejecuciones de trabajo para un trabajo. A continuación se muestra cómo enumerar las ejecuciones para un trabajo:
aws iot list-job-executions-for-job --job-id 010
El comando devuelve una lista de ejecuciones de trabajo:
{ "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 } } ] }
Enumeración de ejecuciones de trabajo para un objeto
Ejecute el comando ListJobExecutionsForThing para enumerar todas las ejecuciones de trabajo que se ejecutan en un objeto. A continuación se muestra cómo listar las ejecuciones de trabajos para un objeto:
aws iot list-job-executions-for-thing --thing-name thingOne
El comando devuelve una lista de ejecuciones de trabajo que se ejecutan o se han ejecutado en el objeto especificado:
{ "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" } ] }
Descripción de una ejecución de trabajo
Ejecute el comando DescribeJobExecution para obtener el estado de la ejecución de un trabajo. Debe especificar un ID de trabajo y el nombre del objeto y, opcionalmente, un número de ejecución para identificar la ejecución del trabajo. A continuación se muestra cómo describir la ejecución de un trabajo:
aws iot describe-job-execution --job-id 017 --thing-name thingOne
El comando devuelve JobExecution. Por ejemplo:
{ "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" } } } }
Eliminación de una ejecución de trabajo
Ejecute el comando DeleteJobExecution para eliminar la ejecución de un trabajo. Debe especificar un ID de trabajo, un nombre de objeto y un número de ejecución para identificar la ejecución del trabajo. A continuación se muestra cómo eliminar la ejecución de un trabajo:
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force
El comando no muestra ninguna salida.
De forma predeterminada, el estado de ejecución de los trabajos debe ser QUEUED o un estado final (SUCCEEDED, FAILED, REJECTED, TIMED_OUT, REMOVED o CANCELED). En caso contrario, se produce un error. Para eliminar la ejecución de un trabajo con estado IN_PROGRESS, puede establecer el parámetro force en true.
aviso
Cuando se elimina la ejecución de un trabajo con estado IN_PROGRESS, el dispositivo que está ejecutando el trabajo no puede obtener acceso a la información del trabajo ni actualizar el estado de su ejecución. Actúe con precaución y asegúrese de que el dispositivo pueda recuperarse a un estado válido.
