Opérations de l'API MQTT de l'appareil de tâches

Vous pouvez émettre des commandes de tâches sur l'appareil en publiant des messages MQTT surRubriques réservées utilisées pour les commandes Jobs.

Votre client côté appareil doit être abonné aux rubriques des messages de réponse de ces commandes. Si vous utilisez leAWS IoTDevice Client, votre appareil s'abonnera automatiquement aux rubriques de réponse. Cela signifie que le gestionnaire de messages publiera les sujets des messages de réponse à l'attention du client qui a publié le message de commande, que votre client soit abonné ou non aux sujets du message de réponse. Ces messages de réponse ne passent pas par l'intermédiaire du courtier de messages et ne peuvent pas être souscrits par d'autres clients ou règles.

Lorsque vous vous inscrivez à l'offre d'emploi etjobExecutionsujets relatifs aux événements pour votre solution de surveillance de flotte, commencez par activertâches et événements d'exécution des tâchespour recevoir tous les événements du côté cloud. Messages de progression des tâches qui sont traités par le biais du courtier de messages et peuvent être utilisés parAWS IoTles règles sont publiées sous la formeÉvénements Jobs. Étant donné que le courtier de messages publie des messages de réponse, même sans y être abonné explicitement, votre client doit être configuré pour recevoir et identifier les messages qu'il reçoit. Votre client doit également confirmer queNom de l'objetdans la rubrique du message entrant s'applique au nom de l'objet du client avant que celui-ci ne donne suite au message.

Note

Des messages quiAWS IoTenvoie en réponse aux messages de commande de l'API MQTT Jobs sont débités de votre compte, que vous y soyez abonné de manière explicite ou non.

Ce qui suit montre les opérations de l'API MQTT et leur syntaxe de demande et de réponse. Toutes les opérations de l'API MQTT possèdent les paramètres suivants :

clientToken: Un jeton client facultatif utilisé pour corréler les demandes et les réponses. Entrez une valeur arbitraire ici et elle sera reflétée dans la réponse.
timestamp: Temps écoulé, en secondes, depuis l'époque à laquelle le message a été envoyé.

Obtient la liste de toutes les tâches qui ne sont pas dans un état terminal, pour un objet spécifié.

Pour appeler cette API, publiez un message sur $aws/things/thingName/jobs/get.

Charge utile de la demande :


{ "clientToken": "string" }

Le courtier de messages publiera$aws/things/thingName/jobs/get/acceptedet$aws/things/thingName/jobs/get/rejectedmême sans y être abonné spécifiquement. Toutefois, pour que votre client reçoive les messages, il doit les écouter. Pour plus d'informations, voirla note concernant les messages de l'API Jobs.

Charge utile de la réponse :


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

OùinProgressJobsetqueuedJobsrenvoie une liste deJobExecutionSummaryobjets ayant le statut deIN_PROGRESSouQUEUED.

Récupère et démarre la prochaine exécution de tâche en attente pour un objet (état)IN_PROGRESSouQUEUED).

Toutes les exécutions de tâches avec statutIN_PROGRESSsont renvoyés en premier.
Les exécutions de tâches sont renvoyées dans l'ordre dans lequel elles ont été mises en file d'attente. Lorsqu'un élément est ajouté ou supprimé du groupe cible pour votre tâche, confirmez l'ordre de déploiement de toutes les nouvelles exécutions de tâches par rapport aux exécutions de tâches existantes.
Si la prochaine exécution de tâche en attente estQUEUED, son état passe àIN_PROGRESSet les détails de l'état d'exécution de la tâche sont définis comme spécifié.
Si la prochaine exécution de la tâche en attente est déjàIN_PROGRESS, les détails de son statut ne sont pas modifiés.
Si aucune exécution de tâche n'est en attente, la réponse n'inclut pasexecutionterrain.
Vous pouvez éventuellement créer un chronomètre en définissant une valeur pourstepTimeoutInMinutespropriété. Si vous ne mettez pas à jour la valeur de cette propriété en exécutant UpdateJobExecution, l'exécution de la tâche expire lorsque le minuteur d'étape expire.

Pour appeler cette API, publiez un message sur $aws/things/thingName/jobs/start-next.

Charge utile de la demande :


{ 
"statusDetails": {
    "string": "job-execution-state"
    ...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

statusDetails: Ensemble de paires nom-valeur décrivant le statut de l'exécution de la tâche. Si aucune valeur n'est spécifiée, les informations statusDetails demeurent inchangées.
stepTimeOutInMinutes: Spécifie la durée pendant laquelle cet appareil doit terminer l'exécution de la tâche. Si l'état d'exécution de la tâche n'est pas réglé sur un état terminal avant l'expiration de ce temporisateur ou avant que le temporisateur ne soit réinitialisé, (en appelantUpdateJobExecution, en réglant le statut surIN_PROGRESSet en spécifiant une nouvelle valeur de délai d'expiration dans le champstepTimeoutInMinutes) le statut d'exécution de la tâche est défini surTIMED_OUT. La définition du délai d'expiration n'a aucun effet sur le délai d'exécution de la tâche qui peut avoir été spécifié lorsque la tâche a été créée (CreateJob à l'aide du champ timeoutConfig).

Le courtier de messages publiera$aws/things/thingName/jobs/start-next/acceptedet$aws/things/thingName/jobs/start-next/rejectedmême sans y être abonné spécifiquement. Toutefois, pour que votre client reçoive les messages, il doit les écouter. Pour plus d'informations, voirla note concernant les messages de l'API Jobs.

Charge utile de la réponse :


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

Oùexecutionest unJobExecutionobjet. Par exemple :


{
"execution" : {
    "jobId" : "022",
    "thingName" : "MyThing",
    "jobDocument" : "< contents of job document >",
    "status" : "IN_PROGRESS",
    "queuedAt" : 1489096123309,
    "lastUpdatedAt" : 1489096123309,
    "versionNumber" : 1,
    "executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}

Permet d'obtenir des informations détaillées sur une exécution de tâche.

Vous pouvez définir lejobIdpour$nextpour renvoyer la prochaine exécution de tâche en attente pour un objet (avec un statut deIN_PROGRESSouQUEUED).

Pour appeler cette API, publiez un message sur $aws/things/thingName/jobs/jobId/get.

Charge utile de la demande :


{ 
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string" 
}

thingName

Nom de l'objet associé à l'appareil.

jobId

Identifiant unique attribué à cette tâche lors de sa création.

Ou utilisez$nextpour renvoyer la prochaine exécution de tâche en attente pour un objet (avec un statut deIN_PROGRESSouQUEUED). Dans ce cas, toutes les exécutions de tâches avec statutIN_PROGRESSsont renvoyés en premier. Les exécutions de tâche sont renvoyées dans l'ordre selon lequel elles ont été créées.

executionNumber

(Facultatif) Numéro identifiant l'exécution d'une tâche sur un appareil. S'il n'est pas indiqué, la dernière exécution de tâche est renvoyée.

includeJobDocument

(Facultatif) À moins qu'il ne soit réglé surfalse, la réponse contient le document de travail. La valeur par défaut est true.

Le courtier de messages publiera$aws/things/thingName/jobs/jobId/get/acceptedet$aws/things/thingName/jobs/jobId/get/rejectedmême sans y être abonné spécifiquement. Toutefois, pour que votre client reçoive les messages, il doit les écouter. Pour plus d'informations, voirla note concernant les messages de l'API Jobs.

Charge utile de la réponse :


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

Oùexecutionest unJobExecutionobjet.

Met à jour le statut d'une exécution de tâche. Le cas échéant, vous pouvez créer un minuteur d'étape en définissant une valeur pour la propriété stepTimeoutInMinutes. Si vous ne mettez pas à jour la valeur de cette propriété en exécutant à nouveau UpdateJobExecution, l'exécution de la tâche expire lorsque le minuteur d'étape expire.

Pour appeler cette API, publiez un message sur $aws/things/thingName/jobs/jobId/update.

Charge utile de la demande :


{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

status: Le nouveau statut de l'exécution de la tâche (IN_PROGRESS,FAILED,SUCCEEDED, ouREJECTED). Il doit être spécifié à chaque mise à jour.
statusDetails: Ensemble de paires nom-valeur décrivant le statut de l'exécution de la tâche. Si aucune valeur n'est spécifiée, les informations statusDetails demeurent inchangées.
expectedVersion: Version actuelle attendue de l'exécution de tâche. Sa version est incrémentée à chaque mise à jour de l'exécution de tâche. Si la version de l'exécution de la tâche est enregistrée dansAWS IoTLe service Jobs ne correspond pas, la mise à jour est rejetée avec unVersionMismatcherreur. UnErrorResponsequi contient les données d'état d'exécution de la tâche en cours est également renvoyée. (Il est donc inutile d'effectuer une demande DescribeJobExecution distincte pour obtenir les données du statut d'exécution de tâche.)
executionNumber: (Facultatif) Numéro identifiant l'exécution d'une tâche sur un appareil. S'il n'est pas indiqué, la dernière exécution de tâche est utilisée.
includeJobExecutionState: (Facultatif) Lorsqu'il est inclus et réglé surtrue, la réponse contient leJobExecutionStateterrain. La valeur par défaut est false.
includeJobDocument: (Facultatif) Lorsqu'il est inclus et réglé surtrue, la réponse contient leJobDocument. La valeur par défaut est false.
stepTimeoutInMinutes: Spécifie la durée pendant laquelle cet appareil doit terminer l'exécution de la tâche. Si l'état d'exécution de la tâche n'est pas défini sur un état terminal avant l'expiration de ce temporisateur ou avant que le temporisateur ne soit réinitialisé, l'état d'exécution de la tâche est défini surTIMED_OUT. La définition ou la réinitialisation de ce délai n'a aucun effet sur le délai d'exécution de la tâche qui aurait pu être spécifié lors de la création de la tâche.

Le courtier de messages publiera$aws/things/thingName/jobs/jobId/update/acceptedet$aws/things/thingName/jobs/jobId/update/rejectedmême sans y être abonné spécifiquement. Toutefois, pour que votre client reçoive les messages, il doit les écouter. Pour plus d'informations, voirla note concernant les messages de l'API Jobs.

Charge utile de la réponse :


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: Un objet JobExecutionState.
jobDocument: Objet de document de tâche.
timestamp: Temps écoulé, en secondes, depuis l'époque à laquelle le message a été envoyé.
clientToken: Jeton client utilisé pour établir une corrélation entre les demandes et les réponses.

Lorsque vous utilisez le protocole MQTT, vous pouvez également effectuer les mises à jour suivantes :

Envoyé chaque fois qu'une exécution de tâche est ajoutée à la liste des exécutions de tâche en attente pour un objet, ou en est supprimée.

Utilisez la rubrique :

$aws/things/thingName/jobs/notify

Charge utile du message :


{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

Envoyé chaque fois que l'exécution d'une tâche est modifiée sur la liste des exécutions de tâches en attente pour un objet, comme défini pourDescribeJobExecutionavecjobId $next. Ce message n'est pas envoyé lorsque les détails d'exécution de la tâche suivante changent, mais uniquement lorsque la tâche suivante qui serait renvoyée parDescribeJobExecutionavecjobId $nexta changé. Considérons les exécutions de tâches J1 et J2 avec un statut deQUEUED. J1 est l'exécution suivante sur la liste des exécutions de tâche en attente. Si le statut de J2 est modifié enIN_PROGRESStant que l'état de J1 reste inchangé, cette notification est envoyée et contient les détails de J2.

Utilisez la rubrique :

$aws/things/thingName/jobs/notify-next

Charge utile du message :


{
"execution" : JobExecution,
"timestamp": timestamp,
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Tâches, opérations de l'appareil, API MQTT et HTTPS et types de données

API HTTP de l'appareil Jobs