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 nuevo trabajo, Jobs de AWS IoT publica un mensaje en el tema $aws/things/thing-name/jobs/notify 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.

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 es correcta, el servicio Jobs de AWS IoT publica un mensaje en el tema $aws/things/MyThing/jobs/0023/get/accepted:

{
    "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 Jobs de AWS IoT publica un mensaje en el tema $aws/things/MyThing/jobs/0023/get/rejected.

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 valor TimeoutConfig, el temporizador en curso empezará a funcionar. También puede establecer un temporizador de pasos para la ejecución de un trabajo especificando un valor para stepTimeoutInMinutes al llamar a 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 puede crear un temporizador de pasos al llamar a 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"
}

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

{
    "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
        }]
    }
}