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 tâches à l'aide duAWS CLI
Cette section décrit comment créer et gérer des tâches.
Création de tâches
Pour créer unAWS IoTjob, utilisez leCreateJobcommande. 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 unAWS IoTtâche, vous avez besoin d'un document de travail 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'URL Amazon S3 présignées, vous avez besoin d'un rôle IAM Amazon Resource Name (ARN) autorisé à télécharger le fichier et à accorder l'autorisation auAWS IoTService de l'emploi pour assumer le rôle.
Pour plus d'informations sur la syntaxe lors de la saisie de la date et de l'heure à l'aide d'une commande API ou duAWS CLI, voirHorodatage.
Signature de code avec des tâches
Si vous utilisez la signature de code pourAWS IoT, vous devez démarrer une tâche de signature de code et inclure le résultat dans votre document de travail. Cela remplacera l'espace réservé à la signature du code dans votre document de travail, qui est requis en tant qu'espace réservé jusqu'à ce qu'il soit remplacé par le chemin du fichier de code signé à l'aide de votreProfil de signature de code. L'espace réservé à la signature du signe de code ressemblera à ce qui suit :
${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}
Utilisez lestart-signing-jobcommande pour créer une tâche de signature de code.start-signing-jobrenvoie un identifiant de tâche. Pour obtenir l'emplacement Amazon S3 où la signature est stockée, utilisezdescribe-signing-jobcommande. Vous pouvez ensuite télécharger la signature depuis Amazon S3. Pour plus d'informations sur les tâches de signature de code, voirSignature de code pourAWS IoT.
Votre document de travail doit contenir un espace réservé d'URL présigné pour votre fichier de code et la sortie de signature JSON placée dans un compartiment Amazon S3 à l'aide dustart-signing-jobcommande :
{ "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", }
Création d'une tâche à l'aide d'un document de travail
La commande suivante montre comment créer une tâche à l'aide d'un document de travail (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/my-s3-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 surChose numéro un.
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 d'exécution de la tâche n'est pas défini sur un autre état du terminal avant l'expiration du délai, il est défini surTIMED_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 que l'exécution d'une tâche reste dansIN_PROGRESSétat plus long que cet intervalle, il échoue et bascule vers le terminalTIMED_OUTstatut.AWS IoTpublie également une notification MQTT.
Pour plus d'informations sur la création de configurations pour les déploiements et les abandons de tâches, voirConfiguration du déploiement et de l'abandon des tâches.
Note
Les documents de travail spécifiés sous forme de fichiers Amazon S3 sont récupérés au moment où vous créez le travail. Si vous modifiez le contenu du fichier Amazon S3 que vous avez utilisé comme source de votre document de travail après avoir créé le document de travail, le contenu envoyé aux cibles de travail ne change pas.
Mettre à jour une tâche
Pour mettre à jour une tâche, utilisezUpdateJobcommande. 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
Pour annuler une tâche, utilisezCancelJobcommande. L'annulation d'une tâche conduit AWS IoT à interrompre le lancement de toute nouvelle exécution pour la tâche. Il annule également toutes les exécutions de tâches qui se trouvent dans unQUEUEDétat.AWS IoTconserve toutes les exécutions de tâches dans un état de terminal intactes car l'appareil 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. Exécutions de tâches qui se trouvent dans unIN_PROGRESSles états sont annulés, mais uniquement si vous spécifiez le facultatif--forceparamètre. Les exécutions de tâches dans un état terminal ne sont pas annulées.
Avertissement
Annulation d'une tâche figurant dansIN_PROGRESSétat (en définissant le--forceparamètre) annule toute exécution de tâche en cours et empêche l'appareil qui exécute la tâche de mettre à jour l'état 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âche est cohérent à terme : AWS IoT cesse de planifier de nouvelles exécutions de tâche et les exécutions de tâche QUEUED pour cette tâche aux 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 parce qu'elle répond aux critères définis parAbortConfigobjet, le service ajoute des valeurs renseignées automatiquement pourcommentetreasonCodechamps. 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
Pour annuler l'exécution d'une tâche sur un appareil, utilisezCancelJobExecutioncommande. Cela annule l'exécution d'une tâche qui se trouve dans unQUEUEDétat. Si vous souhaitez annuler l'exécution d'une tâche en cours, vous devez utiliser--forceparamètre.
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 travail qui se trouve dans unQUEUEDl'état est annulé. Une exécution de tâche qui se trouve dans unIN_PROGRESSl'état est annulé, mais uniquement si vous spécifiez le facultatif--forceparamètre. Les exécutions de tâches dans un état terminal ne peuvent pas être annulées.
Avertissement
Lorsque vous annulez l'exécution d'une tâche qui se trouve dansIN_PROGRESSétat, l'appareil ne peut pas mettre à jour l'état 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 la tâche se fait dans un état terminal, ou si l'exécution de la tâche se fait dans unIN_PROGRESSl'État et le--forcele paramètre n'est pas défini surtrue, cette commande provoque uneInvalidStateTransitionException.
Le statut d'une exécution de tâche annulée est cohérent à terme. Changer le statut de l'exécution d'une tâche enCANCELEDpeut prendre un certain temps, en fonction de divers facteurs.
Suppression d'une tâche
Pour supprimer une tâche et ses exécutions, utilisezDeleteJobcommande. Par défaut, vous ne pouvez supprimer qu'une tâche qui se trouve dans un état terminal (SUCCEEDEDouCANCELED). Dans le cas contraire, une exception se produit. Vous pouvez supprimer une tâche dansIN_PROGRESSprécisez, toutefois, uniquement siforcele paramètre est défini surtrue.
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 figurant dansIN_PROGRESSétat, l'appareil qui déploie la tâche ne peut pas accéder aux informations de la tâche ni mettre à jour l'état d'exécution de la tâche. Faites preuve de prudence et assurez-vous que chaque appareil déployant une tâche supprimée peut revenir à un état correct.
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. Une erreur se produit si vous tentez de supprimer ou d'annuler une tâche dont le statut est déjàDELETION_IN_PROGRESS.
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
Pour récupérer un document de travail relatif à une tâche, utilisezGetJobDocumentcommande. Un document de tâche est une description des opérations distantes à exécuter par les appareils.
Pour obtenir un document de travail, exécutez la commande suivante :
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/job-test-bucket/datafile}\"\n}" }
Note
Lorsque vous utilisez cette commande pour récupérer un document de travail, les URL de remplacement ne sont pas remplacées par des URL Amazon S3 présignées. Lorsqu'un appareil appelleGetPendingJobExecutionsFonctionnement de l'API, les URL d'espace réservé sont remplacées par des URL Amazon S3 présignées dans le document de travail.
Affichage des tâches
Pour obtenir la liste de tous les emplois de votreCompte AWS, utilisez leListJobscommande. 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 votreCompte 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
Pour obtenir le statut d'une tâche, exécutezDescribeJobcommande. 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/job-test-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 de la tâche doit êtreQUEUEDou dans un état terminal (SUCCEEDED,FAILED,REJECTED,TIMED_OUT,REMOVED, ouCANCELED). 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 l'exécution d'une tâche dont le statut estIN_PROGRESS, l'appareil qui exécute la tâche ne peut pas accéder aux informations de la tâche ni mettre à jour l'état d'exécution de la tâche. Soyez vigilant et vérifiez que l'appareil est en mesure de reprendre un état valide.
