Flux de travail des tâches

Vous trouverez ci-dessous les différentes étapes du flux de travail des tâches, du démarrage d’une nouvelle tâche au signalement de l’état d’achèvement de l’exécution d’une tâche.

Démarrer une nouvelle tâche

Lorsqu'une nouvelle tâche est créée, AWS IoT Jobs publie un message sur le $aws/things/thing-name/jobs/notify sujet pour chaque appareil cible.

Le message contient les informations suivantes :

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

L'appareil reçoit ce message sur la rubrique '$aws/things/thingName/jobs/notify' lorsque l'exécution de la tâche est en file d'attente.

Note

Pour les tâches dont SchedulingConfig est facultatif, la tâche conservera un statut initial de SCHEDULED. Lorsque la tâche atteint la valeur sélectionnée startTime, les événements suivants se produisent :

• L’état du statut de la tâche sera mis à jour à IN_PROGRESS.

• La tâche commencera à déployer le document de tâche sur tous les appareils du groupe cible.

Obtenir les informations sur une tâche

Pour obtenir plus d'informations sur l'exécution d'une tâche, l'appareil appelle l'API MQTT DescribeJobExecution avec le champ includeJobDocument défini sur true (valeur par défaut).

Si la demande aboutit, le service AWS IoT Jobs publie un message sur le $aws/things/MyThing/jobs/0023/get/accepted sujet :

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

Si la demande échoue, le service AWS IoT Jobs publie un message sur le $aws/things/MyThing/jobs/0023/get/rejected sujet.

L'appareil dispose désormais du document de tâche, qu'il peut utiliser pour effectuer les opérations distantes pour la tâche. Si le document de tâche contient une URL Amazon S3 présignée, l’appareil peut utiliser cette URL pour télécharger les fichiers requis pour la tâche.

Rapport du statut d'exécution de tâche

Au fur et à mesure que l'appareil exécute la tâche, il peut appeler l'API MQTT UpdateJobExecution pour mettre à jour le statut de l'exécution de la tâche.

Par exemple, un appareil peut mettre à jour le statut de l'exécution de tâche IN_PROGRESS en publiant le message suivant sur la rubrique $aws/things/MyThing/jobs/0023/update :

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

Jobs répond en publiant un message dans la rubrique $aws/things/MyThing/jobs/0023/update/accepted ou $aws/things/MyThing/jobs/0023/update/rejected :

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

Le périphérique permet de combiner les deux demandes précédentes en appelant StartNextPendingJobExecution. La prochaine exécution de tâche en attente est ainsi obtenue et démarrée et l'appareil peut mettre à jour le statut d'exécution de la tâche. La demande renvoie aussi le document de tâche lorsqu'il y a une exécution de tâche en attente.

Si la tâche contient un TimeoutConfig, le chronomètre en cours commence à fonctionner. Vous pouvez également définir un chronomètre pour l'exécution d'une tâche en définissant une valeur pour le stepTimeoutInMinutes moment où vous appelez UpdateJobExecution. Le minuteur d'étape s'applique uniquement à l'exécution des tâches que vous mettez à jour. Vous pouvez définir une nouvelle valeur pour ce minuteur chaque fois que vous mettez à jour une exécution de tâche. Vous pouvez également créer un chronomètre lorsque vous appelez StartNextPendingJobExecution. Si l'exécution de tâche demeure dans l'état IN_PROGRESS plus longtemps que l'intervalle du minuteur d'étape, elle échoue et passe à l'état final TIMED_OUT. Le minuteur d'étape n'a aucun effet sur le minuteur d'avancement que vous définissez lorsque vous créez une tâche.

Le champ status peut avoir la valeur IN_PROGRESS, SUCCEEDED ou FAILED. Vous ne pouvez pas mettre à jour le statut d'une exécution de tâche qui est déjà dans un état terminal.

Rapport d’exécution terminée

Lorsque l'appareil a terminé l'exécution de la tâche, il appelle l'API MQTT UpdateJobExecution. Si la tâche aboutit, définissez status sur SUCCEEDED et, dans le champ statusDetails de la charge utile du message, ajoutez d'autres informations sur la tâche sous la forme de paires nom-valeur. Les minuteurs d'avancement et d'étape prennent fin lorsque l'exécution de la tâche est terminée.

Par exemple :

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

Si la tâche n'a pas réussi, définissez status sur FAILED et, dans statusDetails, ajoutez les informations sur l'erreur qui s'est produite :

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

Note

L'attribut statusDetails peut contenir n'importe quel nombre de paires nom-valeur.

Lorsque le service AWS IoT Jobs reçoit cette mise à jour, il publie un message sur le $aws/things/MyThing/jobs/notify sujet pour indiquer que l'exécution de la tâche est terminée :

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

Tâches supplémentaires

S'il existe d'autres exécutions de tâche en attente pour le périphérique, elles sont incluses dans le message publié sur $aws/things/MyThing/jobs/notify.

Par exemple :

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