View a markdown version of this page

Création et gestion de commandes - AWS IoT Core
Création d'une ressource de commandeRécupérer des informations sur une commandeRépertoriez les commandes de votre Compte AWSMettre à jour une ressource de commandeDéprécier ou restaurer une ressource de commandeSupprimer une ressource de commande

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éation et gestion de commandes

Utilisez AWS IoT Device Management les commandes pour configurer des actions à distance réutilisables ou envoyer des instructions immédiates aux appareils. Créez et gérez des commandes depuis la AWS IoT console ou à l'aide du AWS CLI.

Création d'une ressource de commande

Fournissez les informations suivantes lors de la création d'une commande :

  • Informations générales

    Fournissez un ID de commande unique pour identifier la commande lorsque vous l'exécutez sur les machines cibles. Spécifiez éventuellement un nom d'affichage, une description et des balises pour la gestion.

  • Charge utile

    Pour les commandes statiques, fournissez une charge utile définissant les actions de l'appareil. Spécifiez le type de format de charge utile pour une interprétation correcte de l'appareil.

    Pour les commandes dynamiques, consultez l'attribut de modèle de charge utile.

  • Modèle de charge utile

    Pour les commandes dynamiques, fournissez un PayloadTemplate avec des espaces réservés et des paramètres. Fournissez defaultValue et conditions facultatives. AWS IoT Device Management Les commandes remplacent les espaces réservés lors de l'exécution. Les paramètres manquants utilisent leur valeur par défaut. Toutes les valeurs doivent satisfaire à des conditions définies.

    Les types d'espaces réservés sensibles aux majuscules et minuscules suivants sont pris en charge :

    • ${aws:iot:commandexecution::parameter:parameter1}— Un espace réservé pour la valeur d'un paramètre portant le nomparameter1.

    • ${aws:iot:commandexecution::executionTimeoutSec}— Un espace réservé pour le paramètre de délai d'exécution de la commande fourni lors de l'exécution.

Les rubriques réservées aux commandes utilisent un format basé sur le type de format de charge utile.

  • Pour application/json nos types de application/cbor contenu, utilisez cette requête Rubrique :

    $aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

  • Pour d'autres types de contenu ou un format non spécifié, utilisez cette requête Topic. Le format Payload apparaît dans l'en-tête du message MQTT.

    $aws/commands/<devices>/<DeviceID>/executions/+/request

La rubrique de réponse aux commandes utilise json ou met en cbor forme quel que soit le type de charge utile. <PayloadFormat>doit être json ou cbor :

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

Les sections suivantes décrivent les considérations relatives au format de charge utile et la création de commandes à partir de la console.

Format de charge utile des commandes statiques

La charge utile prend en charge tous les formats jusqu'à 32 Ko. Spécifiez le type de format de charge utile pour une interprétation correcte et sécurisée de l'appareil.

Spécifiez le type de format de charge utile à l'aide type/subtype du format (par exemple, application/json ouapplication/cbor). Valeur par défaut : application/octet-stream. Consultez la section Types MIME courants pour connaître les formats pris en charge.

Format de charge utile des commandes dynamiques

Le PayloadTemplate doit être un JSON valide avec au moins un espace réservé, jusqu'à 32 Ko.

Pour le AwsJsonSubstitution préprocesseur, AWS IoT Device Management Commands envoie des notifications au format JSON ou CBOR en fonction de la configuration du préprocesseur.

Comment créer une commande (console)

Pour créer une commande depuis la console, accédez à Command Hub et procédez comme suit :

  1. Choisissez Créer une commande.

  2. Spécifiez un ID de commande unique.

  3. (Facultatif) Spécifiez le nom d'affichage, la description et les balises.

  4. Téléchargez le fichier Payload contenant les actions de l'appareil. Spécifiez le type de format de charge utile pour une interprétation correcte de l'appareil.

  5. (Facultatif) Pour les modèles de charge utile JSON comportant des espaces réservés, les paramètres sont préremplis dans le tableau en ligne pour être modifiés.

  6. (Facultatif) Configurez le type de valeur de paramètre (obligatoire), la valeur par défaut et les conditions.

  7. Choisissez Créer une commande.

Utilisez l'CreateCommandAPI ou la commande create-command CLI pour créer une commande.

Charge utile de commande

Fournissez une charge utile statique ou un modèle de charge utile. Les charges utiles statiques sont codées en base64. Pour les modèles de charge utile, la charge utile finale est générée lors de l'exécution à l'aide de valeurs de paramètres. Les appareils traitent la charge utile et exécutent des actions spécifiques. Spécifiez le type de contenu de la charge utile pour une réception correcte de l'appareil.

Note

Les charges utiles ne peuvent pas être modifiées après la création de la commande. Créez une nouvelle commande pour modifier la charge utile.

Exemple de politique IAM

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM vous autorise à effectuer cette action sur l'appareil. L'exemple suivant montre une politique IAM qui autorise l'utilisateur à effectuer l'CreateCommandaction.

Dans cet exemple, remplacez :

  • regionavec votre Région AWS, par exempleus-east-1.

  • account-idavec votre Compte AWS numéro, par exemple123456789012.

  • command-idavec un identifiant unique pour votre ID de AWS IoT commande, tel queLockDoor. Si vous souhaitez envoyer plusieurs commandes, vous pouvez les spécifier dans la section Ressource de la politique IAM.

{
    "Version":"2012-10-17",
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Exemple de création de commandes statiques

L'exemple suivant montre comment créer une commande statique. En fonction de votre application, remplacez :

  • <command-id>avec un identifiant unique pour la commande. Par exemple, pour verrouiller la porte de votre maison, vous pouvez spécifierLockDoor. Nous vous recommandons d'utiliser un UUID. Vous pouvez également utiliser les caractères alphanumériques « - » et « _ ».

  • (Facultatif) <display-name> et<description>, qui sont des champs facultatifs que vous pouvez utiliser pour fournir un nom convivial et une description significative à la commande, par exempleLock the doors of my home.

  • namespace, que vous pouvez utiliser pour spécifier l'espace de noms de la commande. Ça doit l'êtreAWS-IoT. Pour plus d'informations sur l'utilisation de cette fonctionnalité AWS IoT FleetWise, voir Commandes à distance

  • payloadcontient des informations sur la charge utile que vous souhaitez utiliser lors de l'exécution de la commande et son type de contenu.

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

L'exécution de cette commande génère une réponse contenant l'ID et l'ARN (nom de ressource Amazon) de la commande. Par exemple, si vous avez spécifié la LockDoor commande lors de sa création, voici un exemple de résultat d'exécution de la commande.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}

Exemple de création de commandes dynamiques

L'exemple suivant montre comment créer une commande dynamique. En fonction de votre application, remplacez :

  • <command-id>avec un identifiant unique pour la commande. Par exemple, pour définir l'état d'alimentation de la lampe, vous pouvez spécifierLight_Power_Status. Nous vous recommandons d'utiliser un UUID. Vous pouvez également utiliser les caractères alphanumériques « - » et « _ ».

  • (Facultatif) <display-name> et<description>, qui sont des champs facultatifs que vous pouvez utiliser pour fournir un nom convivial et une description significative à la commande, par exempleTurn a light ON or OFF.

  • namespace, que vous pouvez utiliser pour spécifier l'espace de noms de la commande. Ça doit l'êtreAWS-IoT. Pour plus d'informations sur l'utilisation de cette fonctionnalité AWS IoT FleetWise, voir Commandes à distance

  • payloadTemplatecontient le modèle de charge de lecture au format JSON avec des espaces réservés.

  • preprocessorcontient la configuration du préprocesseur qui détermine la manière dont le PayloadTemplate doit être traité.

  • mandatoryParametercontient les paramètres correspondant aux espaces réservés du PayloadTemplate, leur type, leurs valeurs par défaut et leurs conditions.

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

L'exécution de cette commande génère une réponse contenant l'ID et l'ARN (nom de ressource Amazon) de la commande. Par exemple, si vous avez spécifié la Light_Power_Status commande lors de sa création, voici un exemple de résultat d'exécution de la commande.

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

Récupérer des informations sur une commande

Après avoir créé une commande, vous pouvez récupérer les informations la concernant depuis la AWS IoT console et en utilisant le AWS CLI. Vous pouvez obtenir les informations suivantes.

  • L'ID de commande, le nom de ressource Amazon (ARN), le nom d'affichage et la description que vous avez spécifiés pour la commande.

  • L'état de la commande, qui indique si une commande est disponible pour être exécutée sur la machine cible, ou si elle est obsolète ou supprimée.

  • La charge utile ou le modèle de charge utile que vous avez fourni.

  • Le préprocesseur que vous avez fourni.

  • Les paramètres obligatoires que vous avez fournis.

  • Heure à laquelle la commande a été créée et mise à jour pour la dernière fois.

Pour récupérer une commande depuis la console, accédez au hub de commande de la AWS IoT console, puis choisissez la commande que vous avez créée pour en afficher les détails.

Outre les détails des commandes, vous pouvez consulter l'historique des commandes, qui fournit des informations sur les exécutions de la commande sur l'appareil cible. Après avoir exécuté cette commande sur l'appareil, vous trouverez des informations sur les exécutions dans cet onglet.

Utilisez l'opération d'API du plan de contrôle GetCommand HTTP ou la get-command AWS CLI commande pour récupérer des informations sur une ressource de commande. Vous devez déjà avoir créé la commande à l'aide de la demande d'CreateCommandAPI ou de l'create-commandinterface de ligne de commande.

Exemple de politique IAM

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM vous autorise à effectuer cette action sur l'appareil. L'exemple suivant montre une politique IAM qui autorise l'utilisateur à effectuer l'GetCommandaction.

Dans cet exemple, remplacez :

  • regionavec votre Région AWS, par exempleus-east-1.

  • account-idavec votre Compte AWS numéro, par exemple123456789023.

  • command-idà l'aide de votre identifiant de commande AWS IoT unique, tel que LockDoor ouLight_Power_Status. Si vous souhaitez récupérer plusieurs commandes, vous pouvez les spécifier dans la section Ressource de la politique IAM.

{
    "Version":"2012-10-17",
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Récupérez un exemple de commande (AWS CLI)

L'exemple suivant vous montre comment récupérer des informations sur une commande à l'aide du get-command AWS CLI. En fonction de votre application, <command-id> remplacez-le par l'identifiant de la commande pour laquelle vous souhaitez récupérer des informations. Vous pouvez obtenir ces informations à partir de la réponse de la create-command CLI.

aws iot get-command --command-id <command-id>

L'exécution de cette commande génère une réponse contenant des informations sur la commande, la charge utile et l'heure de sa création et de sa dernière mise à jour. Il fournit également des informations qui indiquent si une commande est obsolète ou en cours de suppression.

Par exemple, le code suivant montre un exemple de réponse. 

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

Répertoriez les commandes de votre Compte AWS

Après avoir créé des commandes, vous pouvez consulter les commandes que vous avez créées dans votre compte. Dans la liste, vous trouverez des informations sur :

  • L'ID de commande et tout nom d'affichage que vous avez spécifié pour les commandes.

  • Le nom de ressource Amazon (ARN) des commandes.

  • État de la commande qui indique si les commandes peuvent être exécutées sur la machine cible ou si elles sont obsolètes.

    Note

    La liste des personnes en cours de suppression de votre compte n'apparaît pas. Si les commandes sont en attente de suppression, vous pouvez toujours consulter les détails de ces commandes à l'aide de leur ID de commande.

  • Heure à laquelle les commandes ont été créées et mises à jour pour la dernière fois.

Dans la AWS IoT console, vous pouvez trouver la liste des commandes que vous avez créées et leurs détails en accédant au Command Hub.

Pour répertorier les commandes que vous avez créées, utilisez l'opération ListCommands API ou l'list-commandsinterface de ligne de commande.

Exemple de politique IAM

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM vous autorise à effectuer cette action sur l'appareil. L'exemple suivant montre une politique IAM qui autorise l'utilisateur à effectuer l'ListCommandsaction.

Dans cet exemple, remplacez :

  • regionavec votre Région AWS, par exempleus-east-1.

  • account-idavec votre Compte AWS numéro, par exemple123456789012.

{
    "Version":"2012-10-17",
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

Exemple de liste des commandes de votre compte

La commande suivante indique comment répertorier les commandes de votre compte.

aws iot list-commands --namespace "AWS-IoT"

L'exécution de cette commande génère une réponse contenant la liste des commandes que vous avez créées, l'heure à laquelle les commandes ont été créées et la date de leur dernière mise à jour. Il fournit également des informations sur l'état de la commande, qui indiquent si une commande est obsolète ou peut être exécutée sur le périphérique cible. Pour plus d'informations sur les différents statuts et la raison du statut, consultezStatut d’exécution de la commande.

Mettre à jour une ressource de commande

Après avoir créé une commande, vous pouvez mettre à jour le nom d'affichage et la description de la commande.

Note

La charge utile de la commande ne peut pas être mise à jour. Pour mettre à jour ces informations ou utiliser une charge utile modifiée, vous devez créer une nouvelle commande.

Pour mettre à jour une commande depuis la console, accédez au hub de commande de la AWS IoT console et effectuez les étapes suivantes.

  1. Pour mettre à jour une ressource de commande existante, choisissez la commande que vous souhaitez mettre à jour, puis sous Actions, choisissez Modifier.

  2. Spécifiez le nom d'affichage et la description que vous souhaitez utiliser, ainsi que toutes les paires nom-valeur comme balises pour votre commande.

  3. Choisissez Modifier pour enregistrer la commande avec les nouveaux paramètres.

Utilisez l'opération API du plan de UpdateCommand contrôle ou update-command AWS CLI pour mettre à jour une ressource de commande. Grâce à cette API, vous pouvez :

  • Modifiez le nom d'affichage et la description d'une commande que vous avez créée.

  • Dépréciez une ressource de commande ou restaurez une commande déjà obsolète.

Exemple de politique IAM

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM vous autorise à effectuer cette action sur l'appareil. L'exemple suivant montre une politique IAM qui autorise l'utilisateur à effectuer l'UpdateCommandaction.

Dans cet exemple, remplacez :

  • regionavec votre Région AWS, par exempleus-east-1.

  • account-idavec votre Compte AWS numéro, par exemple123456789012.

  • command-idavec votre identifiant de commande AWS IoT unique, tel queLockDoor. Si vous souhaitez récupérer plusieurs commandes, vous pouvez les spécifier dans la section Ressource de la politique IAM.

{
    "Version":"2012-10-17",
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Mettre à jour les informations relatives à une commande, exemples (AWS CLI)

L'exemple suivant montre comment mettre à jour les informations relatives à une commande à l'aide de cette update-command AWS CLI dernière. Pour plus d'informations sur la façon dont vous pouvez utiliser cette API pour rendre obsolète ou restaurer une ressource de commande, consultez. Mettre à jour une ressource de commande (CLI)

L'exemple montre comment mettre à jour le nom d'affichage et la description d'une commande. En fonction de votre application, <command-id> remplacez-le par l'identifiant de la commande pour laquelle vous souhaitez récupérer des informations.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

L'exécution de cette commande génère une réponse contenant les informations mises à jour concernant la commande et l'heure de sa dernière mise à jour. Le code suivant présente un exemple de demande et de réponse pour la mise à jour du nom d'affichage et de la description d'une commande qui éteint l'AC.

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

L'exécution de cette commande génère la réponse suivante.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

Déprécier ou restaurer une ressource de commande

Après avoir créé une commande, si vous ne souhaitez plus continuer à l'utiliser, vous pouvez la marquer comme obsolète. Lorsque vous désapprouvez une commande, toutes les exécutions de commandes en attente continuent de s'exécuter sur l'appareil cible jusqu'à ce qu'elles atteignent le statut de terminal. Une fois qu'une commande est devenue obsolète, si vous souhaitez l'utiliser, par exemple pour envoyer une nouvelle exécution de commande à l'appareil cible, vous devez la restaurer.

Note

Vous ne pouvez pas modifier une commande obsolète ni exécuter de nouvelles commandes pour celle-ci. Pour exécuter de nouvelles commandes sur l'appareil, vous devez le restaurer afin que l'état de la commande passe à Disponible.

Pour plus d'informations sur la dépréciation et la restauration d'une commande, ainsi que sur les considérations connexes, consultez. Obsolescence d’une ressource de commande

Supprimer une ressource de commande

Si vous ne souhaitez plus utiliser une commande, vous pouvez la supprimer définitivement de votre compte. Si l'action de suppression est réussie :

  • Si la commande est devenue obsolète pendant une durée supérieure au délai maximum de 12 heures, elle sera immédiatement supprimée.

  • Si la commande n'est pas obsolète, ou si elle l'est depuis moins longtemps que le délai d'expiration maximal, elle sera dans un état. pending deletion Il sera automatiquement supprimé de votre compte après le délai maximum de 12 heures.

Note

La commande peut être supprimée même si des commandes sont en attente d'exécution. La commande sera en attente de suppression et sera automatiquement supprimée de votre compte.

Pour supprimer une commande de la console, accédez au hub de commande de la AWS IoT console et effectuez les étapes suivantes.

  1. Choisissez la commande que vous souhaitez supprimer, puis sous Actions, choisissez Supprimer.

  2. Confirmez que vous souhaitez supprimer la commande, puis choisissez Supprimer.

La commande sera marquée pour suppression et sera définitivement supprimée de votre compte au bout de 12 heures.

Utilisez l'opération d'API du plan de contrôle DeleteCommand HTTP ou la delete-command AWS CLI commande pour supprimer une ressource de commande. Si l'action de suppression est réussie, vous verrez apparaître un HTTP statusCode de 204 ou 202, et la commande sera automatiquement supprimée de votre compte après la durée maximale de 12 heures. Dans le cas du statut 204, cela indique que la commande a été supprimée.

Exemple de politique IAM

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM vous autorise à effectuer cette action sur l'appareil. L'exemple suivant montre une politique IAM qui autorise l'utilisateur à effectuer l'DeleteCommandaction.

Dans cet exemple, remplacez :

  • regionavec votre Région AWS, par exempleus-east-1.

  • account-idavec votre Compte AWS numéro, par exemple123456789012.

  • command-idavec votre identifiant de commande AWS IoT unique, tel queLockDoor. Si vous souhaitez récupérer plusieurs commandes, vous pouvez les spécifier dans la section Ressource de la politique IAM.

{
    "Version":"2012-10-17",
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

Supprimer un exemple de commande (AWS CLI)

Les exemples suivants vous montrent comment supprimer une commande à l'aide de cette delete-command AWS CLI commande. En fonction de votre application, <command-id> remplacez-le par l'identifiant de la commande que vous souhaitez supprimer.

aws iot delete-command --command-id <command-id>

Si la demande d'API aboutit, la commande génère un code d'état 202 ou 204. Vous pouvez utiliser l'GetCommandAPI pour vérifier que la commande n'existe plus dans votre compte.