Démarrage et surveillance des exécutions de commandes

Spécifiez le périphérique cible qui recevra et exécutera la commande. Utilisez un nom d'objet pour les appareils enregistrés ou un identifiant client pour les appareils non enregistrés. Après avoir reçu la charge utile, l'appareil exécute la commande et exécute les actions spécifiées.

AWS IoT chose

Les appareils cibles peuvent être des objets enregistrés dans le AWS IoT registre. Cela simplifie la recherche et la gestion des appareils.

Enregistrez les appareils en tant qu'objets depuis la page Connect device ou en utilisant CreateThing. Trouvez des objets existants depuis Thing Hub ou en utilisant DescribeThing. Voir Gérer les choses avec le registre pour les détails de l'enregistrement.

ID de client

Pour les appareils non enregistrés, utilisez l'ID client.

L'ID client est un identifiant unique que vous attribuez aux appareils. Défini dans le protocole MQTT, il contient des caractères alphanumériques, des traits de soulignement ou des tirets. Chaque appareil connecté AWS IoT a besoin d'un identifiant client unique.

L'ID client est l'ID client MQTT que les appareils utilisent pour se connecter à AWS IoT Core. AWS IoT utilise cet identifiant pour identifier les appareils et gérer les connexions et les abonnements.

Le délai d'expiration indique la durée (en secondes) pendant laquelle les appareils fournissent les résultats d'exécution.

Après avoir créé une exécution, un chronomètre démarre. Si l'appareil se déconnecte ou ne communique pas les résultats dans le délai imparti, le délai d'exécution expire avec le statutTIMED_OUT.

Par défaut : 10 secondes. Maximum : 12 heures

Valeur du délai d'expiration et statut TIMED_OUT d'exécution

Le cloud et l'appareil peuvent signaler un délai d'expiration.

Après avoir envoyé la commande, un chronomètre démarre. Si aucune réponse de l'appareil n'arrive dans le délai imparti, le cloud définit le statut d'exécution sur TIMED_OUT avec le code $NO_RESPONSE_FROM_DEVICE de raison.

Cela se produit lorsque :

Dans ce cas, lorsque l'état d'exécution de TIMED_OUT est signalé depuis le cloud, l'exécution de la commande n'est pas terminale. Votre appareil peut publier une réponse qui remplace le statut par l'un des états du terminal :SUCCEEDED,FAILED, ou. REJECTED L'exécution de la commande devient alors un terminal et n'accepte aucune autre mise à jour.

Votre appareil peut également mettre à jour un TIMED_OUT état initié par le cloud en signalant qu'un délai d'attente s'est produit lors de l'exécution de la commande. Dans ce cas, l'état d'exécution de la commande reste TIMED_OUT activé, mais l'statusReasonobjet est mis à jour en fonction des informations communiquées par le périphérique. L'exécution de la commande devient alors terminale et aucune autre mise à jour n'est acceptée.

Utilisation de sessions persistantes MQTT

Vous pouvez configurer des sessions persistantes MQTT à utiliser avec la fonction de AWS IoT Device Management commandes. Cette fonctionnalité est particulièrement utile lorsque votre appareil est hors ligne et que vous voulez vous assurer que l'appareil reçoit toujours la commande lorsqu'il revient en ligne avant le délai d'expiration, et qu'il exécute les instructions spécifiées.

Par défaut, l’expiration de la session persistante MQTT est définie sur 60 minutes. Si le délai d'exécution de vos commandes est configuré sur une valeur supérieure à cette durée, les exécutions de commandes de plus de 60 minutes peuvent être rejetées par le courtier de messages et échouer. Pour exécuter des commandes d’une durée supérieure à 60 minutes, vous pouvez demander une augmentation de la durée d’expiration de la session persistante.

Pour commencer à exécuter la commande depuis la console, rendez-vous sur la page Command Hub de la AWS IoT console et effectuez les étapes suivantes.

Utilisez l'opération d'API du plan de données StartCommandExecutionHTTP pour démarrer l'exécution d'une commande. La demande et la réponse de l'API sont corrélées par l'ID d'exécution de la commande. Une fois que l'appareil a terminé d'exécuter la commande, il peut signaler l'état et le résultat de l'exécution au cloud en publiant un message dans la rubrique de réponse aux commandes. Pour un code de réponse personnalisé, les codes d'application que vous possédez peuvent traiter le message de réponse et publier le résultat sur AWS IoT.

Si vos appareils se sont abonnés à la rubrique de demande de commandes, l'StartCommandExecutionAPI publiera le message de charge utile dans cette rubrique. La charge utile peut utiliser n'importe quel format de votre choix. Pour de plus amples informations, veuillez consulter Charge utile de commande.

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

Si le format de charge utile n'est pas JSON ou CBOR, le tableau suivant indique le format de la rubrique de demande de commandes.

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

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'StartCommandExecutionaction.

Dans cet exemple, remplacez :

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Pour consulter la liste des clés de condition prises en chargeStartCommandExecution, consultez la section Clés de condition pour AWS IoT dans le guide de l'utilisateur IAM.

Obtenir le point de terminaison du plan de données spécifique au compte

Avant d'exécuter la commande API, vous devez obtenir l'URL du point de terminaison spécifique au compte pour le point de terminaison. Si vous utilisez des points de terminaison à double pile (IPv4et IPv6), utilisez le. iot:Data-ATS Le iot:Jobs point de terminaison est destiné IPv4 uniquement. Par exemple, si vous exécutez la commande suivante :

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Il renvoie l'URL du point de terminaison spécifique au compte, comme indiqué dans l'exemple de réponse ci-dessous.

{
    "endpointAddress":
    "<account-specific-prefix>-ats.iot.<region>.api.com"
}

Démarrer un exemple d'exécution de commande (AWS CLI)

L'exemple suivant montre comment démarrer l'exécution d'une commande à l'aide de cette start-command-execution AWS CLI commande.

Dans cet exemple, remplacez :

L'exécution de cette commande renvoie un ID d'exécution de commande. Vous pouvez utiliser cet ID pour demander le statut, les détails et l'historique de l'exécution des commandes.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM autorise votre appareil à effectuer ces actions. Vous trouverez ci-dessous un exemple de politique qui autorise votre appareil à effectuer cette action. Pour d'autres exemples de politiques IAM autorisant l'utilisateur à effectuer l'action UpdateCommandExecution MQTT, consultez. Exemples de stratégies de connexion et de publication

Dans cet exemple, remplacez :

Exemple de politique IAM pour l'ID client MQTT

Le code suivant montre un exemple de politique de périphérique lors de l'utilisation de l'ID client MQTT.

Exemple de politique IAM pour l'IoT

Le code suivant montre un exemple de politique en matière d'appareil lors de l'utilisation d'un AWS IoT objet.

Une fois que l'exécution de la commande est reçue sur le sujet de la demande, le dispositif traite la commande. Il utilise ensuite l'UpdateCommandExecutionAPI pour mettre à jour l'état et le résultat de l'exécution de la commande en fonction de la rubrique de réponse suivante.

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

Dans cet exemple, <DeviceID> il s'agit de l'identifiant unique de votre équipement cible et <execution-id> de l'identifiant de l'exécution de la commande sur le périphérique cible. Il <PayloadFormat> peut s'agir de JSON ou de CBOR.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

L'appareil a signalé des mises à jour de l'état d'exécution

Vos appareils peuvent utiliser l'API pour signaler l'une des mises à jour de statut suivantes lors de l'exécution de la commande. Pour plus d'informations sur ces statuts, consultezStatut d’exécution de la commande.

Pour plus d'informations sur le TIMED_OUT statut, consultezValeur du délai d'expiration et statut TIMED_OUT d'exécution.

Considérations relatives à l'utilisation de l'UpdateCommandExecutionAPI

Voici quelques points importants à prendre en compte lors de l'utilisation de l'UpdateCommandExecutionAPI.

UpdateCommandExecutionExemple d'API

Le code suivant montre comment votre appareil peut utiliser l'UpdateCommandExecutionAPI pour signaler l'état d'exécution, le statusReason champ pour fournir des informations supplémentaires sur l'état et le champ de résultat pour fournir des informations sur le résultat de l'exécution, comme le pourcentage de batterie de la voiture dans ce cas.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

Vous pouvez récupérer une exécution de commande depuis la console à l'aide de l'une des méthodes suivantes.

Utilisez l'opération d'API HTTP du plan de GetCommandExecution AWS IoT Core contrôle pour récupérer les informations relatives à l'exécution d'une commande. Vous devez déjà avoir exécuté cette commande à l'aide de l'opération StartCommandExecution API.

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'GetCommandExecutionaction.

Dans cet exemple, remplacez :

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

Récupérer un exemple d'exécution de commande

L'exemple suivant montre comment récupérer des informations sur une commande exécutée à l'aide de cette start-command-execution AWS CLI commande. L'exemple suivant montre comment récupérer des informations sur une commande exécutée pour désactiver le mode volant.

Dans cet exemple, remplacez :

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

L'exécution de cette commande génère une réponse contenant des informations sur l'ARN de l'exécution de la commande, son état d'exécution, ainsi que l'heure à laquelle elle a commencé à s'exécuter et à laquelle elle s'est terminée. Il fournit également un statusReason objet contenant des informations supplémentaires sur le statut. Pour plus d'informations sur les différents statuts et la raison du statut, consultezStatut d’exécution de la commande.

Le code suivant montre un exemple de réponse à la demande d'API.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

Vous pouvez voir toutes les exécutions de commandes depuis la console à l'aide de l'une des méthodes suivantes.

Utilisez l'opération d'API HTTP du plan de ListCommandExecutions AWS IoT Core contrôle pour répertorier toutes les exécutions de commandes dans votre compte.

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'ListCommandExecutionsaction.

Dans cet exemple, remplacez :

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

Exemple d'exécution de commandes de liste

L'exemple suivant vous montre comment répertorier les exécutions de commandes dans votre Compte AWS.

Lorsque vous exécutez la commande, vous devez spécifier s'il faut filtrer la liste pour afficher uniquement les exécutions de commandes créées pour un appareil particulier à l'aide detargetArn, ou les exécutions pour une commande spécifique spécifiée à l'aide ducommandArn.

Dans cet exemple, remplacez :

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

L'exécution de cette commande génère une réponse qui contient une liste des exécutions de commandes que vous avez créées, ainsi que l'heure à laquelle les exécutions ont commencé à s'exécuter et à laquelle elles se sont terminées. Il fournit également des informations sur le statut, ainsi que l'statusReasonobjet qui contient des informations supplémentaires sur le statut.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

Pour plus d'informations sur les différents statuts et la raison du statut, consultezStatut d’exécution de la commande.

Avant d'utiliser cette opération d'API, assurez-vous que votre politique IAM autorise votre appareil à effectuer ces actions. Vous trouverez ci-dessous un exemple de politique qui autorise votre appareil à effectuer cette action.

Dans cet exemple, remplacez :

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

L'exemple suivant montre comment supprimer une commande à l'aide de cette delete-command AWS CLI commande. En fonction de votre application, remplacez-le <execution-id> par l'identifiant de l'exécution de la commande que vous supprimez, puis <target-arn> par l'ARN de votre appareil cible.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

Si la demande d'API aboutit, l'exécution de la commande génère un code d'état de 200. Vous pouvez utiliser l'GetCommandExecutionAPI pour vérifier que l'exécution de la commande n'existe plus dans votre compte.