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.
Créez et gérez des emplois à l'aide du AWS CLI
Cette section décrit comment créer et gérer des tâches.
Création de tâches
Pour créer une AWS IoT tâche, utilisez la CreateJob commande. La tâche est mise en file d'attente en vue de son exécution sur les cibles (objets ou groupes d'objets) que vous spécifiez. Pour créer une AWS IoT tâche, vous avez besoin d'un document de tâche qui peut être inclus dans le corps de la demande ou sous forme de lien vers un document Amazon S3. Si la tâche inclut le téléchargement de fichiers à l'aide d'Amazon S3 présignéURLs, vous avez besoin d'un IAM rôle Amazon Resource Name (ARN) autorisé à télécharger le fichier et autorisant le service AWS IoT Jobs à assumer ce rôle.
Pour plus d'informations sur la syntaxe lors de la saisie de la date et de l'heure à l'aide d'une API commande ou du AWS CLI, voir Horodatage.
Signature de code avec les tâches
Si vous utilisez la signature de code pour AWS IoT, vous devez démarrer une tâche de signature de code et inclure le résultat dans votre document de tâche. Cela remplacera l’espace réservé à la signature du signe de code dans votre document de tâche, qui est requis comme espace réservé jusqu’à ce qu’il soit remplacé par le chemin du fichier de code signé à l’aide de votre profil de signature de code. L’espace réservé pour la signature du code se présente comme suit :
${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}
Utilisez la start-signing-jobcommande pour créer une tâche de signature de code. start-signing-jobrenvoie un identifiant de tâche. Utilisez la commande describe-signing-job pour obtenir l’emplacement Amazon S3 dans lequel la signature est stockée. Vous pouvez alors télécharger la signature depuis Amazon S3. Pour en savoir plus sur les tâches de signature de code, consultez Signature de code pour AWS IoT.
Votre document de travail doit contenir un URL espace réservé présigné pour votre fichier de code et la sortie de JSON signature placée dans un compartiment Amazon S3 à l'aide de la start-signing-job commande :
{ "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", }
Créer une tâche avec un document de tâche
La commande suivante montre comment créer une tâche à l'aide d'un document de tâche (job-document.json) stocké dans un compartiment Amazon S3 (jobBucket), et un rôle autorisé à télécharger des fichiers depuis Amazon S3 (S3DownloadRole).
aws iot create-job \ --job-id 010 \ --targetsarn:aws:iot:us-east-1:123456789012:thing/thingOne\ --document-sourcehttps://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json\ --timeout-config inProgressTimeoutInMinutes=100\ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\":50, \"incrementFactor\":2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\":1000, \"numberOfSucceededThings\":1000}}, \"maximumPerMinute\":1000}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\":100, \"thresholdPercentage\":20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\":200, \"thresholdPercentage\":50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
La tâche est exécutée sur thingOne.
Le paramètre facultatif timeout-config spécifie la durée allouée à chaque appareil pour terminer l'exécution de la tâche. Le minuteur est démarré quand l'état de l'exécution de la tâche a la valeur IN_PROGRESS. Si l’état de l’exécution de la tâche n’est pas défini sur un autre état terminal avant l’expiration, il est défini avec la valeur TIMED_OUT.
Le minuteur en cours ne peut pas être mis à jour et s'applique à toutes les exécutions de tâche pour la tâche. Chaque fois qu'une exécution de tâche reste dans cet IN_PROGRESS état pendant plus longtemps que cet intervalle, elle échoue et passe à l'TIMED_OUTétat du terminal. AWS IoT publie également une MQTT notification.
Pour plus d’informations sur la création de configurations relatives aux déploiements et interruptions de tâche, consultez la section Configuration du déploiement et de l’interruption des tâches.
Note
Les documents de tâche qui sont spécifiés en tant que fichiers Amazon S3 sont extraits au moment de la création de la tâche. La modification du contenu du fichier Amazon S3 que vous avez utilisé comme source de votre document de tâche une fois que vous avez créé la tâche ne modifie pas ce qui est envoyé aux cibles de la tâche.
Mettre à jour une tâche
Vous utilisez la commande UpdateJob pour mettre à jour une tâche. Vous pouvez mettre à jour les champs description, presignedUrlConfig, jobExecutionsRolloutConfig, abortConfig et timeoutConfig d'une tâche.
aws iot update-job \ --job-id 010 \ --description "updated description" \ --timeout-config inProgressTimeoutInMinutes=100\ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\":50, \"incrementFactor\":2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\":1000, \"numberOfSucceededThings\":1000}, \"maximumPerMinute\":1000}}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\":100, \"thresholdPercentage\":20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\":200, \"thresholdPercentage\":50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
Pour en savoir plus, consultez Configuration du déploiement et de l’interruption des tâches.
Annuler une tâche
Vous utilisez la commande CancelJob pour annuler une tâche. L'annulation d'une tâche AWS IoT empêche le déploiement de toute nouvelle exécution de tâche pour la tâche. Il annule également toutes les exécutions de tâches effectuées dans un QUEUED État. AWS IoT conserve intacte toute exécution de tâche dans un état terminal car le périphérique a déjà terminé la tâche. Si une exécution de tâche a le statut IN_PROGRESS, elle reste aussi en l'état, à moins que vous utilisiez le paramètre facultatif --force.
La commande suivante montre comment annuler une tâche avec l'ID 010.
aws iot cancel-job --job-id 010
La commande affiche la sortie suivante :
{ "jobArn": "string", "jobId": "string", "description": "string" }
Lorsque vous annulez une tâche, les exécutions de tâche dont l'état est QUEUED sont annulées. Les exécutions de tâche dont l’état est IN_PROGRESS sont annulées si vous spécifiez le paramètre facultatif --force. Les exécutions de tâche qui se trouvent dans un état terminal ne sont pas annulées.
Avertissement
L’annulation d’une tâche dont l’état est IN_PROGRESS (en définissant le paramètre --force) a pour effet d’annuler les exécutions de tâche en cours et empêche l’appareil qui exécute la tâche de mettre à jour le statut d’exécution de la tâche. Soyez vigilant et vérifiez que chaque appareil exécutant une tâche annulée est en mesure de reprendre un état valide.
Le statut d'une tâche annulée ou de l'une de ses exécutions de tâches est finalement cohérent. AWS IoT arrête de planifier les nouvelles exécutions de QUEUED tâches et les exécutions de tâches pour cette tâche sur les appareils dès que possible. La modification de l'état de l'exécution d'une tâche en CANCELED peut prendre du temps, selon le nombre d'appareils et autres facteurs.
Si une tâche est annulée, car elle a satisfait les critères définis par un objet AbortConfig, le service ajoute les valeurs renseignées automatiquement pour les champs comment et reasonCode. Vous pouvez créer vos propres valeurs pour reasonCode lorsque la tâche d'annulation est orientée utilisateurs.
Annulation d'une exécution de tâche
La commande CancelJobExecution permet d’annuler une exécution de tâche sur un appareil déterminé. Elle annule l’exécution de la tâche qui se trouve dans un état QUEUED. Si vous souhaitez annuler une exécution de tâche dont le statut est en cours, vous devez utiliser le paramètre --force.
La commande suivante montre comment annuler l'exécution d'une tâche depuis la tâche 010 s'exécutant sur myThing.
aws iot cancel-job-execution --job-id 010 --thing-name myThing
La commande n'affiche aucune sortie.
Une exécution de tâche qui se trouve dans un état QUEUED est annulée. Une exécution de tâche dont l’état est IN_PROGRESS est annulée mais si vous spécifiez le paramètre facultatif --force. Les exécutions de tâche qui se trouvent dans un état terminal ne peuvent pas être annulées.
Avertissement
Lorsque vous annulez une exécution de tâche dont le statut est IN_PROGRESS, l’appareil ne peut pas mettre à jour le statut d’exécution de la tâche. Soyez vigilant et vérifiez que l'appareil est en mesure de reprendre un état valide.
Si l’exécution de tâche se trouve dans un état terminal ou si l’exécution de tâche présente le statut IN_PROGRESS et que le paramètre --force a la valeur true, cette commande entraîne une exception InvalidStateTransitionException.
Le statut d'une exécution de tâche annulée est cohérent à terme. La modification de l’état de l’exécution d’une tâche en CANCELED peut prendre du temps, selon différents facteurs.
Suppression d'une tâche
La commande DeleteJob permet de supprimer une tâche et les exécutions de tâche associées. Par défaut, vous pouvez uniquement supprimer une tâche qui se trouve dans un état terminal (SUCCEEDED ou CANCELED). Dans le cas contraire, une exception se produit. Vous ne pouvez supprimer une tâche qui se trouve dans l’état IN_PROGRESS que si le paramètre force a la valeur true.
Pour supprimer une tâche, exécutez la commande suivante :
aws iot delete-job --job-id 010 --force|--no-force
La commande n'affiche aucune sortie.
Avertissement
Lorsque vous supprimez une tâche qui est dans l’état IN_PROGRESS, le périphérique qui déploie la tâche ne peut pas accéder aux informations sur la tâche ou mettre à jour le statut d’exécution de la tâche. Soyez vigilant et vérifiez que chaque appareil déployant une tâche annulée est en mesure de reprendre un état valide.
La suppression d'une tâche peut prendre un certain temps qui varie en fonction du nombre d'exécutions de tâche créées pour la tâche et autres facteurs. Pendant la suppression de la tâche, l'état de celle-ci indique DELETION_IN_PROGRESS. Toute tentative de suppression ou d’annulation d’une tâche dont le statut est DELETION_IN_PROGRESS entraîne une erreur.
Seules 10 tâches peuvent avoir l'état DELETION_IN_PROGRESS en même temps. Sinon, une exception LimitExceededException se produit.
Obtention d'un document de tâche
Vous utilisez la commande GetJobDocument pour récupérer un document de tâche pour une tâche. Un document de tâche est une description des opérations distantes à exécuter par les appareils.
Exécutez la commande suivante pour obtenir un document de tâche.
aws iot get-job-document --job-id 010
La commande renvoie le document de tâche de la tâche spécifiée :
{ "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/amzn-s3-demo-bucket/datafile}\"\n}" }
Note
Lorsque vous utilisez cette commande pour récupérer un document de travail, l'espace réservé n'est URLs pas remplacé par Amazon S3 présigné. URLs Lorsqu'un appareil appelle l'GetPendingJobExecutionsAPIopération, l'espace réservé URLs est remplacé par Amazon S3 présigné URLs dans le document de travail.
Affichage des tâches
Pour obtenir la liste de toutes les tâches de votre Compte AWS choix, utilisez la ListJobs commande. Les données de travail et d'exécution de travail sont conservées pendant une durée limitée. Exécutez la commande suivante pour répertorier toutes les tâches de votre Compte AWS :
aws iot list-jobs
La commande répertorie toutes les tâches de votre compte, triées sur le statut de la tâche :
{ "jobs": [ { "status": "IN_PROGRESS", "lastUpdatedAt": 1486687079.743, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", "createdAt": 1486687079.743, "targetSelection": "SNAPSHOT", "jobId": "013" }, { "status": "SUCCEEDED", "lastUpdatedAt": 1486685868.444, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", "createdAt": 1486685868.444, "completedAt": 148668789.690, "targetSelection": "SNAPSHOT", "jobId": "012" }, { "status": "CANCELED", "lastUpdatedAt": 1486678850.575, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", "createdAt": 1486678850.575, "targetSelection": "SNAPSHOT", "jobId": "011" } ] }
Description d'une tâche
La commande DescribeJob permet d’obtenir le statut d’une tâche. La commande suivante explique comment décrire une tâche :
$ aws iot describe-job --job-id 010
La commande renvoie le statut de la tâche spécifiée. Par exemple :
{ "documentSource": "https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json", "job": { "status": "IN_PROGRESS", "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/myThing" ], "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfFailedThings": 0, "numberOfInProgressThings": 0, "numberOfQueuedThings": 0, "numberOfRejectedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 0, "numberOfTimedOutThings": 0, "processingTargets": [ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ] }, "presignedUrlConfig": { "expiresInSec": 60, "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole" }, "jobId": "010", "lastUpdatedAt": 1486593195.006, "createdAt": 1486593195.006, "targetSelection": "SNAPSHOT", "jobExecutionsRolloutConfig": { "exponentialRate": { "baseRatePerMinute": integer, "incrementFactor": integer, "rateIncreaseCriteria": { "numberOfNotifiedThings": integer, // Set one or the other "numberOfSucceededThings": integer // of these two values. }, "maximumPerMinute": integer } }, "abortConfig": { "criteriaList": [ { "action": "string", "failureType": "string", "minNumberOfExecutedThings": integer, "thresholdPercentage": integer } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } } }
Affichage des exécutions d'une tâche
Une tâche en cours d'exécution sur un appareil spécifique est représentée par un objet d'exécution de tâche. La commande ListJobExecutionsForJob permet d'afficher toutes les exécutions de tâche d'une tâche. L'exemple suivant montre comment afficher les exécutions d'une tâche :
aws iot list-job-executions-for-job --job-id 010
La commande renvoie une liste d'exécutions de tâche :
{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 1234567890 } }, { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1486593345.659, "queuedAt": 1486593196.378, "startedAt": 1486593345.659, "executionNumber": 4567890123 } } ] }
Affichage des exécutions de tâche pour un objet
La commande ListJobExecutionsForThing permet d'afficher toutes les exécutions de tâche s'exécutant sur un objet. L'exemple suivant montre comment afficher les exécutions de tâche d'un objet :
aws iot list-job-executions-for-thing --thing-name thingOne
La commande renvoie la liste des exécutions de tâche qui sont en cours d'exécution ou qui se sont exécutées sur l'objet spécifié :
{ "executionSummaries": [ { "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486687082.071, "queuedAt": 1486687082.071, "executionNumber": 9876543210 }, "jobId": "013" }, { "jobExecutionSummary": { "status": "IN_PROGRESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "SUCCEEDED", "startAt": 1486678853.415, "lastUpdatedAt": 1486678853.415, "queuedAt": 1486678853.415, "executionNumber": 4357680912 }, "jobId": "011" }, { "jobExecutionSummary": { "status": "CANCELED", "startAt": 1486593196.378, "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 2143174250 }, "jobId": "010" } ] }
Description d'une exécution de tâche
La commande DescribeJobExecution permet d'obtenir le statut d'une exécution de tâche. Pour identifier l'exécution de tâche, vous devez spécifier un ID de tâche, un nom d'objet et éventuellement un numéro d'exécution. La commande suivante explique comment décrire une exécution de tâche :
aws iot describe-job-execution --job-id 017 --thing-name thingOne
La commande renvoie la chaîne JobExecution. Par exemple :
{ "execution": { "jobId": "017", "executionNumber": 4516820379, "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "versionNumber": 123, "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "approximateSecondsBeforeTimedOut": 100, "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }
Suppression d'une exécution de tâche
Pour supprimer une exécution de tâche, exécutez la commande DeleteJobExecution. Pour identifier l'exécution de tâche, vous devez spécifier un ID de tâche, un nom d'objet et un numéro d'exécution. La commande suivante explique comment supprimer une exécution de tâche :
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force
La commande n'affiche aucune sortie.
Par défaut, le statut de l’exécution d’une tâche doit être QUEUED ou dans un état terminal (SUCCEEDED, FAILED, REJECTED, TIMED_OUT, REMOVED ou CANCELED). Dans le cas contraire, une erreur se produit. Pour supprimer une exécution de tâche avec le statut IN_PROGRESS, vous pouvez définir le paramètre force sur true.
Avertissement
Lorsque vous supprimez une exécution de tâche qui est dans l’état IN_PROGRESS, le périphérique qui exécute la tâche ne peut pas accéder aux informations sur la tâche ou mettre à jour le statut d’exécution de la tâche. Soyez vigilant et vérifiez que l'appareil est en mesure de reprendre un état valide.
