Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Opérations de l’API MQTT de l’appareil des tâches
Vous pouvez émettre des commandes sur les appareils de tâches en publiant des messages MQTT dans les [rubriques réservées utilisées pour les commandes de tâches](reserved-topics.md#reserved-topics-job).
Le client côté appareil doit être abonné aux sujets des messages de réponse de ces commandes. Si vous utilisez le client de l' AWS IoT appareil, votre appareil s'abonne automatiquement aux sujets de réponse. Cela signifie que l’agent de messages publiera les sujets des messages de réponse à l’intention du client qui a publié le message de commande, que votre client soit abonné ou non aux sujets des messages de réponse. Ces messages de réponse ne passent pas par l’agent de messages et ne peuvent pas être souscrits par d’autres clients ou règles.
Lorsque vous vous abonnez aux rubriques relatives aux tâches et aux événements `jobExecution` de votre solution de surveillance de flotte, activez d’abord les événements relatifs aux tâches [ et à l’exécution des tâches ](iot-events.md) pour recevoir tous les événements du côté cloud. Les messages de progression des tâches traités par le biais de l’agent de messages et pouvant être utilisés par les règles AWS IoT sont publiés sous le format [Événements Jobs](events-jobs.md). Étant donné que l’agent de messages publie des messages de réponse, même sans abonnement explicite, votre client doit être configuré pour recevoir et identifier les messages qu’il reçoit. Votre client doit également confirmer que le *thingName* sujet du message entrant s'applique au nom de l'objet du client avant que celui-ci ne donne suite au message.
**Note**
Les messages envoyés AWS IoT en réponse aux messages de commande de l'API MQTT Jobs sont débités de votre compte, que vous y soyez abonné explicitement ou non.
Ce qui suit montre les opérations de l’API MQTT ainsi que leur syntaxe de demande et de réponse. Toutes les opérations de l’API MQTT sont dotées des paramètres suivants :
clientToken
Une jeton client facultatif utilisé pour établir une corrélation entre les demandes et les réponses. Saisissez une valeur arbitraire ici et elle sera reflétée dans la réponse.
`timestamp`
La durée écoulée, en secondes depuis la date epoch Unix où le message a été envoyé.
## GetPendingJobExecutions
Obtient la liste de tous les travaux qui ne sont pas dans un état terminal, pour une chose spécifiée.
Pour appeler cette API, publiez un message sur `$aws/things/thingName/jobs/get`.
Charge utile de la demande :
```
{ "clientToken": "string" }
```
L’agent de messages publiera `$aws/things/thingName/jobs/get/accepted` et `$aws/things/thingName/jobs/get/rejected` même sans abonnement spécifique. Toutefois, pour que votre client reçoive les messages, il doit être à leur écoute. Pour plus d’informations, veuillez consulter [la note sur les messages de l’API des tâches](#jobs-mqtt-note).
Charge utile de la réponse :
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Où `inProgressJobs` et `queuedJobs` renvoie une liste d’objets [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) dont le statut est `IN_PROGRESS` ou`QUEUED`.
## StartNextPendingJobExecution
Obtient et démarre l’exécution de tâche en attente suivante pour un objet (état `IN_PROGRESS` ou `QUEUED`).
+ Toutes les exécutions de tâche avec le statut `IN_PROGRESS` sont renvoyées en premier.
+ Les exécutions de tâches sont renvoyées dans l’ordre dans lequel ils ont été mis en file d’attente. Lorsqu’un élément est ajouté ou supprimé du groupe cible de 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 est `QUEUED`, son état est modifié en `IN_PROGRESS` et les détails du statut de l’exécution de la tâche sont définis comme indiqué.
+ Si la prochaine exécution de tâche en attente est déjà `IN_PROGRESS`, les informations détaillées de son statut ne sont pas modifiées.
+ Si aucune exécution de tâche n’est en attente, la réponse n’inclut pas le champ `execution`.
+ 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 `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 le statut d’exécution de tâche n’est pas défini sur un statut de terminal avant que ce minuteur n’expire, ou avant que le minuteur ne soit réinitialisé (en appelant `UpdateJobExecution`, en définissant le statut sur `IN_PROGRESS` et en spécifiant une nouvelle valeur dans le champ `stepTimeoutInMinutes`), l’état de l’exécution de la tâche est automatiquement défini avec la valeur `TIMED_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`).
Les valeurs valides pour ce paramètre varient de 1 à 10 080 (1 minute à 7 jours). Une valeur de -1 est également valide et annulera le chronomètre en cours (créé par une utilisation antérieure de UpdateJobExecutionRequest).
L’agent de messages publiera `$aws/things/thingName/jobs/start-next/accepted` et `$aws/things/thingName/jobs/start-next/rejected` même sans abonnement spécifique. Toutefois, pour que votre client reçoive les messages, il doit être à leur écoute. Pour plus d’informations, veuillez consulter [la note sur les messages de l’API des tâches](#jobs-mqtt-note).
Charge utile de la réponse :
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Où `execution` est un objet [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data). 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,
}
```
## DescribeJobExecution
Permet d'obtenir des informations détaillées sur une exécution de tâche.
Vous pouvez définir le `jobId` sur `$next` pour revenir à la prochaine exécution de tâche en attente (avec le statut `IN_PROGRESS` ou `QUEUED`) pour un objet.
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 `$next` pour revenir à la prochaine exécution de tâche en attente (avec le statut `IN_PROGRESS` ou `QUEUED`) pour un objet. Dans ce cas, toutes les exécutions de tâche avec le statut `IN_PROGRESS` sont renvoyées en premier. Les exécutions de tâche sont renvoyées dans l'ordre selon lequel elles ont été créées.
`executionNumber`
(Facultatif) Nombre qui identifie une exécution de tâche sur un appareil. S'il n'est pas indiqué, la dernière exécution de tâche est renvoyée.
`includeJobDocument`
(Facultatif) La réponse contient le document de tâche, sauf si la valeur est `false`. La valeur par défaut est `true`.
L’agent de messages publiera `$aws/things/thingName/jobs/jobId/get/accepted` et `$aws/things/thingName/jobs/jobId/get/rejected` même sans abonnement spécifique. Toutefois, pour que votre client reçoive les messages, il doit être à leur écoute. Pour plus d’informations, veuillez consulter [la note sur les messages de l’API des tâches](#jobs-mqtt-note).
Charge utile de la réponse :
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Où `execution` est un objet [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data).
## UpdateJobExecution
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` ou`REJECTED`). 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 des tâches stockée dans le service AWS IoT Jobs ne correspond pas, la mise à jour est rejetée avec une `VersionMismatch` erreur. Un fichier [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) contenant les données de statut d’exécution de la tâche en cours est également renvoyé. (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) Nombre qui identifie une exécution de tâche sur un appareil. S'il n'est pas indiqué, la dernière exécution de tâche est utilisée.
`includeJobExecutionState`
(Facultatif) Quand le champ est inclus et a la valeur `true`, la réponse contient le champ `JobExecutionState`. La valeur par défaut est `false`.
`includeJobDocument`
(Facultatif) Quand le champ est inclus et a la valeur `true`, la réponse contient `JobDocument`. 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 le statut d’exécution de la tâche n’est pas mis dans un statut terminal avant l’expiration de cette temporisation ou avant la réinitialisation de la temporisation, le statut d’exécution de la tâche est mis à `TIMED_OUT`. La définition ou la réinitialisation du délai d’expiration n’a aucun effet sur le délai d’expiration de l’exécution de la tâche qui peut avoir été spécifié lorsque la tâche a été créée.
L’agent de messages publiera `$aws/things/thingName/jobs/jobId/update/accepted` et `$aws/things/thingName/jobs/jobId/update/rejected` même sans abonnement spécifique. Toutefois, pour que votre client reçoive les messages, il doit être à leur écoute. Pour plus d’informations, veuillez consulter [la note sur les messages de l’API des tâches](#jobs-mqtt-note).
Charge utile de la réponse :
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
Un objet [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state).
`jobDocument`
Objet de [document de tâche](key-concepts-jobs.md).
Dans les réponses MQTT, le `jobDocument` champ est un objet JSON. Dans les réponses HTTP, il s'agit d'une représentation sous forme de chaîne de l'objet JSON.
`timestamp`
La durée écoulée, en secondes depuis la date epoch Unix où 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 :
## JobExecutionsChanged
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": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
Envoyé chaque fois qu’il y a une modification apportée à l’exécution de tâche définie comme exécution suivante dans la liste des exécutions de tâche en attente pour un objet, comme défini pour [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) avec `jobId``$next`. Le message n’est pas envoyé en cas de modification des détails de l’exécution de tâche suivante, mais uniquement lorsque la prochaine tâche qui sera renvoyée par `DescribeJobExecution` avec le `jobId` `$next` a changé. Considérons les exécutions de tâche J1 et J2 avec le statut `QUEUED`. J1 est l'exécution suivante sur la liste des exécutions de tâche en attente. Si le statut de J2 devient `IN_PROGRESS` tandis 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" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```