Flujo de trabajo

A continuación se muestran los diferentes pasos del flujo de trabajo, desde el inicio de un nuevo trabajo hasta el informe del estado de finalización de la ejecución de un trabajo.

Inicio de un nuevo trabajo

Cuando se crea un trabajo nuevo, AWS IoT Jobs publica un mensaje sobre el $aws/things/thing-name/jobs/notify tema para cada dispositivo de destino.

El mensaje contiene la siguiente información:

{
    "timestamp":1476214217017,
    "jobs":{
        "QUEUED":[{
            "jobId":"0001",
            "queuedAt":1476214216981,
            "lastUpdatedAt":1476214216981,
            "versionNumber" : 1
        }]
    }
}

El dispositivo recibe este mensaje en el tema '$aws/things/thingName/jobs/notify' cuando la ejecución del trabajo está en la cola.

nota

En el caso de los trabajos con la SchedulingConfig opcional, mantendrán el estado inicial SCHEDULED. Cuando el trabajo alcance el startTime seleccionado, ocurrirá lo siguiente:

• El estado del trabajo se actualizará a IN_PROGRESS.

• El trabajo comenzará el despliegue del documento de trabajo en todos los dispositivos del grupo de destino.

Obtención de información de trabajo

Para obtener más información sobre la ejecución de un trabajo, el dispositivo llama a la API de MQTT DescribeJobExecution con el campo includeJobDocument establecido en true (el valore predeterminado).

Si la solicitud se realiza correctamente, el servicio AWS IoT Jobs publica un mensaje sobre el $aws/things/MyThing/jobs/0023/get/accepted tema:

{
    "clientToken" : "client-001",
    "timestamp" : 1489097434407,
    "execution" : {
        "approximateSecondsBeforeTimedOut": number,
        "jobId" : "023",
        "status" : "QUEUED",
        "queuedAt" : 1489097374841,
        "lastUpdatedAt" : 1489097374841,
        "versionNumber" : 1,
        "jobDocument" : {
            < contents of job document >
        }
    }
}

Si se produce un error en la solicitud, el servicio AWS IoT Jobs publica un mensaje sobre el $aws/things/MyThing/jobs/0023/get/rejected tema.

El dispositivo ahora tiene el documento de trabajo que puede usar para realizar las operaciones remotas para el trabajo. Si el documento de trabajo contiene una URL prefirmada de Amazon S3, el dispositivo puede usar esa URL para descargar los archivos necesarios para el trabajo.

Informe del estado de la ejecución de trabajo

A medida que el dispositivo ejecute el trabajo, puede llamar a la API de MQTT de UpdateJobExecution para actualizar el estado de la ejecución de trabajo.

Por ejemplo, un dispositivo puede actualizar el estado de ejecución de trabajo a IN_PROGRESS mediante la publicación del siguiente mensaje en el tema $aws/things/MyThing/jobs/0023/update:

{
    "status":"IN_PROGRESS",
    "statusDetails": {
        "progress":"50%"
    },
    "expectedVersion":"1",
    "clientToken":"client001"
}

Jobs responde mediante la publicación de un mensaje en el tema $aws/things/MyThing/jobs/0023/update/accepted o $aws/things/MyThing/jobs/0023/update/rejected:

{
    "clientToken":"client001",
    "timestamp":1476289222841
}

El dispositivo puede combinar las dos solicitudes anteriores llamando a StartNextPendingJobExecution. Esto obtiene e inicia la ejecución del trabajo pendiente y permite al dispositivo actualizar el estado de ejecución del trabajo. Esta solicitud también devuelve el documento de trabajo cuando hay una ejecución de trabajo pendiente.

Si el trabajo contiene un TimeoutConfig, el temporizador en curso comienza a ejecutarse. También puede configurar un temporizador por pasos para la ejecución de un trabajo estableciendo un valor para stepTimeoutInMinutes cuando llame UpdateJobExecution. El temporizador de pasos se aplica únicamente a la ejecución del trabajo que actualice. Puede establecer un nuevo valor para este temporizador cada vez que actualice la ejecución de un trabajo. También puedes crear un temporizador por pasos cuando llames StartNextPendingJobExecution. Si la ejecución del trabajo permanece en estado IN_PROGRESS durante un periodo superior a este intervalo del temporizador de pasos, generará un error y cambiará al estado terminal TIMED_OUT. El temporizador de pasos no tiene ningún efecto en el temporizador en curso que establezca al crear un trabajo.

El campo status se puede definir en IN_PROGRESS, SUCCEEDED o FAILED. No puede actualizar el estado de una ejecución de trabajo que ya está en estado terminal.

Informe de ejecución completada

Cuando el dispositivo ha acabado de ejecutar el trabajo, llama a la API de MQTT de UpdateJobExecution. Si el trabajo se realizó correctamente, establezca status en SUCCEEDED y, en la carga del mensaje, en statusDetails, añada otra información acerca del trabajo, como pares nombre-valor. Los temporizadores en curso y de pasos finalizan cuando se completa la ejecución del trabajo.

Por ejemplo:

{
    "status":"SUCCEEDED",
    "statusDetails": {
        "progress":"100%"
    },
    "expectedVersion":"2",
    "clientToken":"client-001"
}

Si el trabajo no se realizó correctamente, establezca status en FAILED y, en statusDetails, añada información acerca del error que se ha producido:

{
    "status":"FAILED",
    "statusDetails": {
        "errorCode":"101",
        "errorMsg":"Unable to install update"
    },
    "expectedVersion":"2",
    "clientToken":"client-001"
}

nota

El atributo statusDetails puede contener cualquier número de pares nombre-valor.

Cuando el servicio AWS IoT Jobs recibe esta actualización, publica un mensaje sobre el $aws/things/MyThing/jobs/notify tema para indicar que se ha completado la ejecución del trabajo:

{
    "timestamp":1476290692776,
    "jobs":{}
}

Trabajos adicionales

Si hay otras ejecuciones de trabajo pendientes para el dispositivo, se incluyen en el mensaje publicado en $aws/things/MyThing/jobs/notify.

Por ejemplo:

{
    "timestamp":1476290692776,
    "jobs":{
        "QUEUED":[{
            "jobId":"0002",
            "queuedAt":1476290646230,
            "lastUpdatedAt":1476290646230
        }],
        "IN_PROGRESS":[{
            "jobId":"0003",
            "queuedAt":1476290646230,
            "lastUpdatedAt":1476290646230
        }]
    }
}