Création et gestion de commandes - AWS IoT Core
Création d'une ressource de commandeRécupérer les informations relatives à une commandeRépertoriez les commandes dans votre Compte AWSMettre à jour une ressource de commandeDépréciation ou restauration d'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 pour 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 des 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 du 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 conditionnez éventuellement. AWS IoT Device Management Les commandes remplacent les espaces réservés lors de l'exécution. Les paramètres manquants utilisent leur DefaultValue. Toutes les valeurs doivent satisfaire à des conditions définies.

    Les types d'espaces réservés distinguant 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.

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

  • Pour application/json nos types de application/cbor contenu, utilisez ce sujet de demande :

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

  • Pour d'autres types de contenu ou un format non spécifié, utilisez cette rubrique de demande. 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 depuis 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 sûre et correcte de l'appareil.

Spécifiez le type de format de charge utile en utilisant le type/subtype 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 au 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 de charge utile 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 avec espaces réservés, les paramètres sont préremplis dans le tableau intégré pour être modifiés.

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

  7. Choisissez Créer une commande.

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

Charge utile de commande

Fournissez une charge utile ou un modèle de charge utile statique. 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 au moment de l'exécution à l'aide de valeurs de paramètres. Les appareils traitent la charge utile et exécutent les actions spécifiées. Spécifiez le type de contenu de 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 identifiant de AWS IoT commande, tel queLockDoor. Si vous souhaitez envoyer plusieurs commandes, vous pouvez les spécifier dans la section Ressource de la stratégie 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 commande statique

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 l'UUID. Vous pouvez également utiliser des 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, tels queLock 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é pour 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 sortie d'exécution de la commande.

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

Exemple de création de commande dynamique

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 de puissance de la lampe, vous pouvez spécifierLight_Power_Status. Nous vous recommandons d'utiliser l'UUID. Vous pouvez également utiliser des 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, tels queTurn 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é pour AWS IoT FleetWise, voir Commandes à distance

  • payloadTemplatecontient le modèle de charge de jeu 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 sortie 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 les informations relatives à une commande

Après avoir créé une commande, vous pouvez récupérer des 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 la ressource Amazon (ARN), tout nom d'affichage et toute 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 le périphérique 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 de la commande, vous pouvez consulter l'historique des commandes, qui fournit des informations sur l'exécution de la commande sur le périphérique 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 API du plan de contrôle GetCommandHTTP 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 CreateCommand d'API ou de la create-command CLI.

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-idavec 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 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, ainsi que l'heure à laquelle elle a été créée et mise à jour pour la dernière fois. Il fournit également des informations indiquant 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 dans votre Compte AWS

Après avoir créé des commandes, vous pouvez consulter celles 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 le périphérique cible ou si elles sont obsolètes.

    Note

    La liste des personnes en cours de suppression de votre compte ne s'affiche 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 ListCommandsAPI ou la list-commandsCLI.

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 dans 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 une 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 si elle est disponible pour ê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 Command Hub 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 en tant que balises pour votre commande.

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

Utilisez l'opération API du plan de UpdateCommandcontrôle ou le 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"
    }
}

Exemples de mise à jour des informations relatives à une commande (AWS CLI)

L'exemple suivant montre comment mettre à jour les informations relatives à une commande à l'aide de cette update-command AWS CLI commande. Pour plus d'informations sur la façon dont vous pouvez utiliser cette API pour déprécier 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 sur la commande et l'heure de sa dernière mise à jour. Le code suivant montre un exemple de demande et de réponse pour mettre à jour le nom d'affichage et la description d'une commande qui met le courant alternatif hors tension.

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éciation ou restauration d'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 le périphérique 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 à la machine cible, vous devez la restaurer.

Note

Vous ne pouvez pas modifier une commande obsolète, ni exécuter de nouvelles exécutions 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 associées, 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'a été pendant une durée inférieure au délai maximum, la commande 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 exécutions de commandes sont en attente. 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 Command Hub 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 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 aboutit, vous verrez un HTTP statusCode 204 ou 202, et la commande sera automatiquement supprimée de votre compte après le délai d'expiration maximal 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"
    }
}

Exemple de suppression d'une commande (AWS CLI)

Les exemples suivants 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 supprimez.

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.