API de gestion et de contrôle des tâches et types de données - AWS IoT Core

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.

API de gestion et de contrôle des tâches et types de données

Les commandes suivantes sont disponibles pour la gestion et le contrôle des tâches dans la CLI et via le protocole HTTPS.

Pour déterminer leURL du point de terminaisonparamètre pour vos commandes CLI, exécutez cette commande.

aws iot describe-endpoint --endpoint-type=iot:Jobs

Cette commande renvoie la sortie suivante.

{ "endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com" }
Note

Le terminal Jobs n'est pas compatible avec ALPNz-amzn-http-ca.

Types de données de gestion et de contrôle des tâches

Les types de données suivants sont utilisés par les applications de gestion et de contrôle pour communiquer avecAWS IoTEmplois.

L'objet Job contient des informations sur une tâche. L'exemple suivant montre la syntaxe :

{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|SUCCEEDED", "forceCanceled": boolean, "targetSelection": "CONTINUOUS|SNAPSHOT", "comment": "string", "targets": ["string"], "description": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp, "jobProcessDetails": { "processingTargets": ["string"], "numberOfCanceledThings": long, "numberOfSucceededThings": long, "numberOfFailedThings": long, "numberOfRejectedThings": long, "numberOfQueuedThings": long, "numberOfInProgressThings": long, "numberOfRemovedThings": long, "numberOfTimedOutThings": long }, "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "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 } ] }, "SchedulingConfig": { "startTime": string "endTime": string "timeZone": string "endTimeBehavior": string }, "timeoutConfig": { "inProgressTimeoutInMinutes": long } }

Pour plus d'informations, consultez Job ou job.

L'objet JobSummary contient un résumé de tâche. L'exemple suivant montre la syntaxe :

{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED", "targetSelection": "CONTINUOUS|SNAPSHOT", "thingGroupId": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp }

Pour plus d'informations, consultez JobSummary ou job-summary.

L'objet JobExecution représente l'exécution d'une tâche sur un appareil. L'exemple suivant montre la syntaxe :

Note

Lorsque vous utilisez les opérations de l'API du plan de contrôle,JobExecutionle type de données ne contient pas deJobDocumentterrain. Pour obtenir ces informations, vous pouvez utiliser leGetJobDocumentFonctionnement de l'API ouget-job-documentCommande CLI.

{ "approximateSecondsBeforeTimedOut": 50, "executionNumber": 1234567890, "forceCanceled": true|false, "jobId": "string", "lastUpdatedAt": timestamp, "queuedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED", "forceCanceled": boolean, "statusDetails": { "detailsMap": { "string": "string" ... }, "status": "string" }, "thingArn": "string", "versionNumber": 123 }

Pour plus d'informations, consultez JobExecution ou job-execution.

LeJobExecutionSummaryl'objet contient des informations récapitulatives sur l'exécution des tâches. L'exemple suivant montre la syntaxe :

{ "executionNumber": 1234567890, "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED" }

Pour plus d'informations, consultez JobExecutionSummary ou job-execution-summary.

L'objet JobExecutionSummaryForJob contient un récapitulatif des informations sur les exécutions de tâche d'une tâche spécifique. L'exemple suivant montre la syntaxe :

{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1549395301.389, "queuedAt": 1541526002.609, "executionNumber": 1 } }, ... ] }

Pour plus d'informations, consultez JobExecutionSummaryForJob ou job-execution-summary-for-job.

L'objet JobExecutionSummaryForThing contient un récapitulatif des informations sur une exécution de tâche sur un objet spécifique. L'exemple suivant montre la syntaxe :

{ "executionSummaries": [ { "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1549395301.389, "queuedAt": 1541526002.609, "executionNumber": 1 }, "jobId": "MyThingJob" }, ... ] }

Pour plus d'informations, consultez JobExecutionSummaryForThing ou job-execution-summary-for-thing.

Gestion des tâches et opérations de l'API de contrôle

Utilisez les opérations d'API ou les commandes CLI suivantes :

Associe un groupe à une tâche continue. Les critères suivants doivent être satisfaits :

  • Lors de la création de la tâche, le champ targetSelection doit être défini sur CONTINUOUS.

  • Le statut de la tâche doit actuellement être IN_PROGRESS.

  • Le nombre total de cibles associées à une tâche ne doit pas dépasser 100.

HTTPS request
POST /jobs/jobId/targets { "targets": [ "string" ], "comment": "string" }

Pour plus d'informations, veuillez consulter AssociateTargetsWithJob.

CLI syntax
aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "targets": [ "string" ], "jobId": "string", "comment": "string" }

Pour plus d'informations, veuillez consulter associate-targets-with-job.

Annule une tâche.

HTTPS request
PUT /jobs/jobId/cancel { "force": boolean, "comment": "string", "reasonCode": "string" }

Pour plus d'informations, veuillez consulter CancelJob.

CLI syntax
aws iot cancel-job \ --job-id <value> \ [--force <value>] \ [--comment <value>] \ [--reasonCode <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "force": boolean, "comment": "string" }

Pour plus d'informations, veuillez consulter cancel-job.

Annule une exécution de tâche sur un appareil.

HTTPS request
PUT /things/thingName/jobs/jobId/cancel { "force": boolean, "expectedVersion": "string", "statusDetails": { "string": "string" ... } }

Pour plus d'informations, veuillez consulter CancelJobExecution.

CLI syntax
aws iot cancel-job-execution \ --job-id <value> \ --thing-name <value> \ [--force | --no-force] \ [--expected-version <value>] \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "thingName": "string", "force": boolean, "expectedVersion": long, "statusDetails": { "string": "string" } }

Pour plus d'informations, veuillez consulter cancel-job-execution.

Crée une tâche. Vous pouvez fournir le document de travail sous forme de lien vers un fichier dans un compartiment Amazon S3 (documentSourceparamètre), ou dans le corps de la requête (documentparamètre).

Un travail peut être créécontinuen définissant le paramètre facultatiftargetSelectionparamètre pourCONTINUOUS(la valeur par défaut estSNAPSHOT). Une tâche continue peut être utilisée pour intégrer ou mettre à niveau des appareils au fur et à mesure qu'ils sont ajoutés à un groupe, car elle continue de s'exécuter et est lancée sur les éléments récemment ajoutés. Cela peut se produire même une fois que les éléments du groupe au moment de la création de la tâche ont terminé la tâche.

Un travail peut avoir une optionTimeoutConfig, qui définit la valeur du temporisateur en cours. Le minuteur d'avancement ne peut pas être mis à jour et s'applique à toutes les exécutions de la tâche.

Les validations suivantes sont effectuées sur les arguments de l'API CreateJob :

  • L'argument targets doit être une liste d'ARN d'objets ou de groupes d'objets valides. Toutes les choses et tous les groupes d'objets doivent se trouver dans votreCompte AWS.

  • LedocumentSourcel'argument doit être une URL Amazon S3 valide vers un document de travail. Les URL Amazon S3 se présentent sous la forme suivante :https://s3.amazonaws.com/bucketName/objectName.

  • Le document stocké dans l'URL spécifiée par l'argument documentSource doit être un document JSON codé en UTF-8.

  • La taille d'un document de travail est limitée à 32 Ko en raison de la limite de taille d'un message MQTT (128 Ko) et du chiffrement.

  • LejobIddoit être unique dans votreCompte AWS.

HTTPS request
PUT /jobs/jobId { "targets": [ "string" ], "document": "string", "documentSource": "string", "description": "string", "jobTemplateArn": "string", "presignedUrlConfigData": { "roleArn": "string", "expiresInSec": "integer" }, "targetSelection": "CONTINUOUS|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 } ] }, "SchedulingConfig": { "startTime": string "endTime": string "timeZone": string "endTimeBehavior": string } "timeoutConfig": { "inProgressTimeoutInMinutes": long } }

Pour plus d'informations, veuillez consulter CreateJob.

CLI syntax
aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--job-template-arn <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--abort-config <value>] \ [--timeout-config <value>] \ [--document-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "jobTemplateArn": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": long }, "targetSelection": "string", "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": long }, "documentParameters": { "string": "string" } }

Pour plus d'informations, veuillez consulter create-job.

Supprime une tâche et ses exécutions de tâche associées.

Selon le nombre d'exécutions de tâche créées pour la tâche et divers autres facteurs, la suppression d'une tâche peut prendre du temps. 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.

HTTPS request
DELETE /jobs/jobId?force=force

Pour plus d'informations, veuillez consulter DeleteJob.

CLI syntax
aws iot delete-job \ --job-id <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "force": boolean }

Pour plus d'informations, veuillez consulter delete-job.

Supprime une exécution de tâche.

HTTPS request
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force

Pour plus d'informations, veuillez consulter DeleteJobExecution.

CLI syntax
aws iot delete-job-execution \ --job-id <value> \ --thing-name <value> \ --execution-number <value> \ [--force | --no-force] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "thingName": "string", "executionNumber": long, "force": boolean }

Pour plus d'informations, veuillez consulter delete-job-execution.

Obtient les détails de l'exécution de la tâche.

HTTPS request
GET /jobs/jobId

Pour plus d'informations, veuillez consulter DescribeJob.

CLI syntax
aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string" }

Pour plus d'informations, veuillez consulter describe-job.

Obtient les détails d'une exécution de tâche. Le statut de l'exécution de tâche doit être SUCCEEDED ou FAILED.

HTTPS request
GET /things/thingName/jobs/jobId?executionNumber=executionNumber

Pour plus d'informations, veuillez consulter DescribeJobExecution.

CLI syntax
aws iot describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "thingName": "string", "executionNumber": long }

Pour plus d'informations, veuillez consulter describe-job-execution.

Obtient le document de tâche pour une tâche.

Note

Les URL d'espace réservé ne sont pas remplacées par des URL Amazon S3 présignées dans le document renvoyé. Les URL présignées sont générées uniquement lorsque le service AWS IoT Jobs reçoit une demande via MQTT.

HTTPS request
GET /jobs/jobId/job-document

Pour plus d'informations, veuillez consulter GetJobDocument.

CLI syntax
aws iot get-job-document \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string" }

Pour plus d'informations, veuillez consulter get-job-document.

Obtient la liste des exécutions de tâche d'une tâche.

HTTPS request
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken

Pour plus d'informations, veuillez consulter ListJobExecutionsForJob.

CLI syntax
aws iot list-job-executions-for-job \ --job-id <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "jobId": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

Pour plus d'informations, veuillez consulter list-job-executions-for-job.

Obtient la liste des exécutions de tâche d'un objet.

HTTPS request
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken

Pour plus d'informations, veuillez consulter ListJobExecutionsForThing.

CLI syntax
aws iot list-job-executions-for-thing \ --thing-name <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "thingName": "string", "status": "string", "maxResults": "integer", "nextToken": "string" }

Pour plus d'informations, veuillez consulter list-job-executions-for-thing.

Obtient la liste des tâches figurant dans votreCompte AWS.

HTTPS request
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken

Pour plus d'informations, veuillez consulter ListJobs.

CLI syntax
aws iot list-jobs \ [--status <value>] \ [--target-selection <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--thing-group-name <value>] \ [--thing-group-id <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "status": "string", "targetSelection": "string", "maxResults": "integer", "nextToken": "string", "thingGroupName": "string", "thingGroupId": "string" }

Pour plus d'informations, veuillez consulter list-jobs.

Met à jour les champs pris en charge de la tâche spécifiée. Valeurs mises à jour pourtimeoutConfigne prennent effet que pour les nouveaux lancements en cours. Actuellement, les lancements en cours continuent de se lancer avec la configuration de délai d'expiration précédente.

HTTPS request
PATCH /jobs/jobId { "description": "string", "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "jobExecutionsRolloutConfig": { "exponentialRate": { "baseRatePerMinute": number, "incrementFactor": number, "rateIncreaseCriteria": { "numberOfNotifiedThings": number, "numberOfSucceededThings": number }, "maximumPerMinute": number }, "abortConfig": { "criteriaList": [ { "action": "string", "failureType": "string", "minNumberOfExecutedThings": number, "thresholdPercentage": number } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } }

Pour plus d'informations, veuillez consulter UpdateJob.

CLI syntax
aws iot update-job \ --job-id <value> \ [--description <value>] \ [--presigned-url-config <value>] \ [--job-executions-rollout-config <value>] \ [--abort-config <value>] \ [--timeout-config <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

Format cli-input-json :

{ "description": "string", "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "jobExecutionsRolloutConfig": { "exponentialRate": { "baseRatePerMinute": number, "incrementFactor": number, "rateIncreaseCriteria": { "numberOfNotifiedThings": number, "numberOfSucceededThings": number } }, "maximumPerMinute": number }, "abortConfig": { "criteriaList": [ { "action": "string", "failureType": "string", "minNumberOfExecutedThings": number, "thresholdPercentage": number } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } }

Pour plus d'informations, veuillez consulter update-job.