Démarrage et surveillance des exécutions de commandes

Spécifiez le périphérique cible pour recevoir et exécuter la commande. Utilisez un nom d'objet pour les appareils enregistrés ou un ID 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 thing

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

Enregistrez les appareils en tant qu'objets depuis la page Connecter les appareils ou en utilisant CreateThing. Trouvez des objets existants sur Thing Hub ou en utilisant DescribeThing. Consultez la section Gestion des données avec le registre pour plus de détails sur l'inscription.

ID 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 qui se connecte 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'attente spécifie la durée (en secondes) pendant laquelle les appareils fournissent les résultats d'exécution.

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

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

Valeur du délai d'attente et état d'exécution de TIMED_OUT

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

Après l'envoi de 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 l'état 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 : SUCCEEDEDFAILED, 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 statut 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 zéro, 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 des sessions persistantes MQTT

Vous pouvez configurer des sessions persistantes MQTT à utiliser avec la fonctionnalité de AWS IoT Device Management commandes. Cette fonctionnalité est particulièrement utile dans les cas où votre appareil est hors ligne et que vous voulez vous assurer que l'appareil reçoit toujours la commande lorsqu'il se reconnecte avant la durée du 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, accédez à 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 StartCommandExecution HTTP 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 fini 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 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 le 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, voici 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 (IPv4 et 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émarrez 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 interroger l'état d'exécution des commandes, les détails et l'historique des exécutions 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 qui autorisent 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 présente un exemple de politique d'appareil lors de l'utilisation de l'ID client MQTT.

Exemple de politique IAM pour les objets connectés

Le code suivant montre un exemple de politique d'appareil lors de l'utilisation de AWS IoT quelque chose.

Une fois que l'exécution de la commande a été reçue dans la rubrique de la demande, le périphérique 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 machine cible et <execution-id> de l'identifiant de l'exécution de la commande sur la machine 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 concernant 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'attente et état d'exécution de TIMED_OUT.

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

Voici quelques considérations importantes à 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 l'exécution d'une commande depuis la console à l'aide de l'une des méthodes suivantes.

Utilisez l'opération de l'API HTTP du plan de GetCommandExecution AWS IoT Core contrôle pour récupérer des informations sur 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érez un exemple d'exécution de commande

L'exemple suivant vous montre comment récupérer des informations concernant 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 concernant une commande qui a été 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, l'état de l'exécution et l'heure à laquelle elle a commencé à s'exécuter et à quelle date elle s'est terminée. Il fournit également un statusReason objet contenant des informations supplémentaires sur l'état. 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 de l'API HTTP du plan de ListCommandExecutions AWS IoT Core contrôle pour répertorier toutes les exécutions de commandes de 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 si vous souhaitez filtrer la liste afin d'afficher uniquement les exécutions de commandes créées pour un périphérique particulier à l'aide dutargetArn, ou les exécutions pour une commande particulière 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 contenant la 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 à quelle date elles se sont terminées. Il fournit également des informations d'état et l'statusReasonobjet qui contient des informations supplémentaires sur l'état.

{
    "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. Selon 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 machine 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.