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.
# Démarrage et surveillance des exécutions de commandes
Après avoir créé une commande, lancez une exécution sur le périphérique cible. L'appareil met à jour les résultats et publie le statut dans les rubriques réservées au MQTT. Récupérez et surveillez l'état d'exécution depuis votre compte.
Démarrez et surveillez les commandes à l'aide de AWS IoT la console ou AWS CLI.
**Topics**
+ [Lancer l'exécution d'une commande](#iot-remote-command-execution-start)
+ [Mise à jour du résultat de l’exécution d’une commande](#iot-remote-command-execution-update)
+ [Récupérer l'exécution d'une commande](#iot-remote-command-execution-get)
+ [Affichage des mises à jour des commandes à l'aide du client de test MQTT](#iot-remote-command-execution-update-mqtt)
+ [Répertoriez les exécutions de commandes dans votre Compte AWS](#iot-remote-command-execution-list)
+ [Supprimer l'exécution d'une commande](#iot-remote-command-execution-delete)
## Lancer l'exécution d'une commande
**Important**
Vous êtes seul responsable du déploiement des commandes d'une manière sûre et conforme aux lois applicables.
Avant de commencer une exécution, assurez-vous que :
+ Vous avez créé une commande dans l'espace de AWS IoT noms avec des informations de charge utile. Au démarrage de l'exécution, l'appareil traite les instructions de charge utile et exécute les actions spécifiées. Voir [Création d'une ressource de commande](iot-remote-command-create-manage.md#iot-remote-command-create) pour la création de commandes.
+ Votre appareil s'est abonné aux rubriques réservées aux commandes du MQTT. Au démarrage de l'exécution, les informations de charge utile sont publiées sur cette requête MQTT réservée. Rubrique :
**peuvent être des clients Things ou MQTT. **est le nom de l'objet ou l'ID client. **Valeurs prises en charge : JSON et CBOR. Pour de plus amples informations, veuillez consulter [Rubriques relatives aux commandes](reserved-topics.md#reserved-topics-commands).
```
$aws/commands///executions/+/request/
```
Pour les applications autres que JSON/CBOR**, utilisez ce format de rubrique de commandes :
```
$aws/commands///executions/+/request
```
### Considérations relatives à l'appareil cible
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](https://console.aws.amazon.com/iot/home#/connect-overview) ou en utilisant [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateThing.html). Trouvez des objets existants depuis [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) ou en utilisant [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThing.html). Voir [Gérer les choses avec le registre](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry) 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.
**Note**
Pour les objets enregistrés, l'ID client peut correspondre au nom de l'objet.
Lorsque vous ciblez un ID client spécifique, les appareils doivent se connecter à AWS IoT l'aide de cet ID client pour recevoir la charge utile.
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.
### Considérations relatives au délai d'exécution des commandes
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 statut`TIMED_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 :
+ L'appareil s'est déconnecté pendant l'exécution.
+ Le périphérique n'a pas réussi à terminer l'exécution dans le délai imparti.
+ L'appareil n'a pas pu signaler l'état dans le délai imparti.
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'`statusReason`objet 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.
**Note**
Pour vous assurer que vous utilisez correctement la fonctionnalité de sessions persistantes MQTT, réglez l'indicateur Clean Start sur zéro. Pour plus d’informations, consultez [Sessions persistantes MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-persistent-sessions).
### Lancer l'exécution d'une commande (console)
Pour commencer à exécuter la commande depuis la console, rendez-vous sur la page [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT console et effectuez les étapes suivantes.
1. Pour exécuter la commande que vous avez créée, choisissez **Exécuter la commande**.
1. Passez en revue les informations relatives à la commande que vous avez créée, y compris les rubriques réservées au MQTT et les paramètres, le cas échéant.
Pour les commandes dynamiques, entrez les valeurs des paramètres ou conservez-les par défaut. Pour les paramètres qui n'ont pas de valeur par défaut, vous devez fournir une valeur à envoyer dans le cadre de cette exécution.
1. Spécifiez le périphérique cible qui recevra et exécutera la commande. L'appareil peut être spécifié comme n'importe AWS IoT quel objet s'il a été enregistré AWS IoT, ou en utilisant l'ID client si votre appareil n'a pas encore été enregistré. Pour de plus amples informations, consultez [Considérations relatives à l'appareil cible](#iot-command-execution-target).
1. (Facultatif) Configurez une valeur de délai d'expiration pour la commande qui détermine la durée pendant laquelle vous souhaitez que la commande s'exécute avant son expiration. Si votre commande doit s'exécuter pendant plus de 60 minutes, vous devrez peut-être augmenter le délai d'expiration des sessions persistantes MQTT. Pour de plus amples informations, veuillez consulter [Considérations relatives au délai d'exécution des commandes](#iot-command-execution-timeout).
1. Sélectionnez **Run Command (Exécuter la commande)**.
### Lancer l'exécution d'une commande (AWS CLI)
Utilisez l'opération d'API du plan de données [https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_StartCommandExecution.html)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 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'`StartCommandExecution`API 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](iot-remote-command-create-manage.md#iot-commands-payload).
```
$aws/commands///executions/+/request/
```
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///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'`StartCommandExecution`action.
Dans cet exemple, remplacez :
+ `region`avec votre Région AWS, par exemple`us-east-1`.
+ `account-id`avec votre Compte AWS numéro, par exemple`123456789012`.
+ `command-id`avec un identifiant unique pour votre AWS IoT commande, tel que`LockDoor`. Si vous souhaitez envoyer plusieurs commandes, vous pouvez les spécifier dans la politique IAM.
+ `devices`avec l'un `thing` ou l'autre ou `client` selon que vos appareils ont été enregistrés en tant qu' AWS IoT objets ou sont spécifiés en tant que clients MQTT.
+ `device-id`avec votre AWS IoT `thing-name` or`client-id`.
```
{
"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 charge`StartCommandExecution`, consultez la section [Clés de condition pour AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-policy-keys) 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":
"-ats.iot..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 :
+ *``*avec l'ARN de la commande que vous souhaitez exécuter. Vous pouvez obtenir ces informations à partir de la réponse de la commande `create-command` CLI. Par exemple, si vous exécutez la commande pour changer le mode volant, utilisez`arn:aws:iot:region:account-id:command/SetComfortSteeringMode`.
+ *``*avec le Thing ARN de l'appareil cible, qui peut être un objet IoT ou un client MQTT, pour lequel vous souhaitez exécuter la commande. Par exemple, si vous exécutez la commande pour le périphérique cible`myRegisteredThing`, utilisez`arn:aws:iot:region:account-id:thing/myRegisteredThing`.
+ *``*avec le point de terminaison spécifique au compte dans lequel vous l'avez obtenu[Obtenir le point de terminaison du plan de données spécifique au compte](#iot-remote-command-execution-start-endpoint), préfixé par. `https://` Par exemple, `https://123456789012abcd.jobs.iot.us-east-1.amazonaws.com`.
+ (Facultatif) Vous pouvez également spécifier un paramètre supplémentaire lors de l'exécution de l'opération `StartCommandExecution` d'API. `executionTimeoutSeconds` Ce champ facultatif indique le délai en secondes pendant lequel le périphérique doit terminer l'exécution de la commande. Par défaut, la valeur est de 10 secondes. Lorsque le statut d'exécution de la commande est `CREATED` défini, un temporisateur démarre. Si le résultat de l'exécution de la commande n'est pas reçu avant l'expiration du délai, le statut passe automatiquement à`TIMED_OUT`.
+
```
aws iot-jobs-data start-command-execution \
--command-arn \
--target-arn \
--endpoint \
--execution-timeout-seconds 900
```
+ (Facultatif) Pour les commandes dynamiques, spécifiez les paramètres et leurs valeurs à utiliser pour la substitution. Vous devez fournir une valeur pour les paramètres pour lesquels aucune DefaultValue n'est définie lors de la création de la commande. Si un paramètre possède une DefaultValue, la valeur du paramètre fournie ici est prioritaire. Pour les paramètres pour lesquels ValueConditions est définie, la valeur du paramètre fournie ici doit satisfaire à la condition.
Sur la base d'`Light_Power_Status`un exemple de commande dynamique :
+
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status \
--target-arn arn:aws:iot:us-east-1:123456789012:thing/exampleThing \
--endpoint \
--execution-timeout-seconds 900 \
--parameters "powerStatus={S=ON}"
```
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.
**Note**
Si la commande est obsolète, la demande d'`StartCommandExecution`API échouera avec une exception de validation. Pour corriger cette erreur, restaurez d'abord la commande à l'aide de l'`UpdateCommand`API, puis exécutez la `StartCommandExecution` demande.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
## Mise à jour du résultat de l’exécution d’une commande
Utilisez l'opération d'API du plan de données `UpdateCommandExecution` MQTT pour mettre à jour le statut ou le résultat d'une exécution de commande.
**Note**
Avant d'utiliser cette API :
Votre appareil doit avoir établi une connexion MQTT et être abonné aux rubriques de demande et de réponse des commandes. Pour de plus amples informations, veuillez consulter [Workflow de commandes de haut niveau](iot-remote-command-workflow.md).
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 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](connect-and-pub.md)
Dans cet exemple, remplacez :
+ `Region`avec votre Région AWS, par exemple`us-east-1`.
+ `AccountID`avec votre Compte AWS numéro, par exemple*`123456789012`*.
+ `ThingName`avec le nom de l' AWS IoT objet pour lequel vous ciblez l'exécution de la commande, par exemple*`myRegisteredThing`*.
+ `commands-request-topic`et `commands-response-topic` avec les noms des sujets de demande et de réponse de vos AWS IoT commandes. Pour de plus amples informations, veuillez consulter [Workflow de commandes de haut niveau](iot-remote-command-workflow.md).
#### 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.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/clients/${iot:ClientId}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/clients/${iot:ClientId}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
#### 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.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Publish",
"Resource": "arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response"
},
{
"Effect": "Allow",
"Action": "iot:Receive",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/request/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/*/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/request/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/accepted/json",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/commands/things/${iot:Connection.Thing.ThingName}/executions/+/response/rejected/json"
]
},
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
}
]
}
```
### Comment utiliser l'`UpdateCommandExecution`API
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'`UpdateCommandExecution`API 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///executions//response/
```
Dans cet exemple, *``* il s'agit de l'identifiant unique de votre équipement cible et *``* de l'identifiant de l'exécution de la commande sur le périphérique cible. Il ** peut s'agir de JSON ou de CBOR.
**Note**
Si vous n'avez pas enregistré votre appareil AWS IoT, vous pouvez utiliser l'identifiant client comme identifiant au lieu d'un nom d'objet.
```
$aws/commands/clients//executions//response/
```
#### 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, consultez[Statut d’exécution de la commande](iot-remote-command-concepts.md#iot-command-execution-status).
+ `IN_PROGRESS`: Lorsque l'appareil commence à exécuter la commande, il peut mettre à jour l'état à`IN_PROGRESS`.
+ `SUCCEEDED`: Lorsque l'appareil traite avec succès la commande et termine son exécution, il peut publier un message dans le sujet de réponse sous le nom de`SUCCEEDED`.
+ `FAILED`: Si l'appareil n'a pas réussi à exécuter la commande, il peut publier un message dans le sujet de réponse sous le nom`FAILED`.
+ `REJECTED`: Si l'appareil n'accepte pas la commande, il peut publier un message dans le sujet de réponse en tant que`REJECTED`.
+ `TIMED_OUT`: L'état d'exécution de la commande peut changer pour `TIMED_OUT` l'une des raisons suivantes.
+ Le résultat de l'exécution de la commande n'a pas été reçu. Cela peut se produire parce que l'exécution n'a pas été terminée dans le délai spécifié ou si l'appareil n'a pas publié les informations d'état dans le sujet de réponse.
+ L'appareil signale qu'un délai d'attente s'est produit lors de la tentative d'exécution de la commande.
Pour plus d'informations sur le `TIMED_OUT` statut, consultez[Valeur du délai d'expiration et statut `TIMED_OUT` d'exécution](#iot-command-execution-timeout-status).
#### Considérations relatives à l'utilisation de l'`UpdateCommandExecution`API
Voici quelques points importants à prendre en compte lors de l'utilisation de l'`UpdateCommandExecution`API.
+ Vos appareils peuvent utiliser un `statusReason` objet facultatif pour fournir des informations supplémentaires sur l'exécution. Si vos appareils fournissent cet objet, le `reasonCode` champ de l'objet est obligatoire, mais le `reasonDescription` champ est facultatif.
+ Lorsque vos appareils utilisent l'`statusReason`objet, ils `reasonCode` doivent utiliser le modèle `[A-Z0-9_-]+` et ne pas dépasser 64 caractères. Si vous fournissez le`reasonDescription`, assurez-vous qu'il ne dépasse pas 1 024 caractères. Il peut utiliser n'importe quel caractère à l'exception des caractères de contrôle tels que les nouvelles lignes.
+ Vos appareils peuvent utiliser un `result` objet facultatif pour fournir des informations sur le résultat de l'exécution de la commande, telles que la valeur de retour d'un appel de fonction à distance. Si vous le fournissez`result`, il doit nécessiter au moins une entrée.
+ Dans le `result` champ, vous spécifiez les entrées sous forme de paires clé-valeur. Pour chaque entrée, vous devez spécifier les informations de type de données sous forme de chaîne, de booléen ou de binaire. Un type de données chaîne doit utiliser la clé`s`, un type de données booléen utilise la clé `b` et un type de données binaire doit utiliser la clé. `bin` Assurez-vous que ces touches sont en minuscules.
+ Si vous rencontrez une erreur lors de l'exécution de l'`UpdateCommandExecution`API, vous pouvez consulter l'erreur dans le groupe de `AWSIoTLogsV2` journaux d'Amazon CloudWatch. Pour plus d'informations sur l'activation de la journalisation et l'affichage des journaux, consultez[Configuration de la AWS IoT journalisation](configure-logging.md).
#### `UpdateCommandExecution`Exemple d'API
Le code suivant montre comment votre appareil peut utiliser l'`UpdateCommandExecution`API 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"
}
}
}
```
## Récupérer l'exécution d'une commande
Après avoir exécuté une commande, vous pouvez récupérer des informations sur l'exécution de la commande à partir de la AWS IoT console et à l'aide du AWS CLI. Vous pouvez obtenir les informations suivantes.
**Note**
Pour récupérer le dernier statut d'exécution des commandes, votre appareil doit publier les informations d'état dans la rubrique de réponse à l'aide de l'API `UpdateCommandExecution` MQTT, comme décrit ci-dessous. Jusqu'à ce que l'appareil publie sur cette rubrique, l'`GetCommandExecution`API signalera l'état sous la forme `CREATED` ou`TIMED_OUT`.
Chaque exécution de commande que vous créez a :
+ Un **ID d’exécution**, qui est l’identifiant unique d’exécution de la commande.
+ Le **statut** de l’exécution de la commande. Lorsque vous exécutez la commande sur l’appareil cible, elle passe à l’état `CREATED`. EIle peut ensuite passer à d’autres statuts d’exécution de commande, comme décrit ci-dessous.
+ Le **résultat** de l'exécution de la commande.
+ L’**ID de commande** unique et l’appareil cible pour lequel les exécutions ont été créées.
+ La **Date de début**, qui indique l’heure à laquelle l’exécution de la commande a été créée.
### Récupérer une exécution de commande (console)
Vous pouvez récupérer une exécution de commande depuis la console à l'aide de l'une des méthodes suivantes.
+
**Depuis la page Command Hub**
Accédez à la page [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT console et effectuez ces étapes.
1. Choisissez la commande pour laquelle vous avez créé une exécution sur le périphérique cible.
1. Sur la page des détails des commandes, sous l'onglet **Historique des commandes**, vous pouvez voir les exécutions que vous avez créées. Choisissez l'exécution pour laquelle vous souhaitez récupérer des informations.
1. Si vos appareils ont utilisé l'`UpdateCommandExecution`API pour fournir les informations relatives aux résultats, vous pouvez les trouver dans l'onglet **Résultats** de cette page.
+
**Depuis la page du hub Thing**
Si vous avez choisi un AWS IoT objet comme équipement cible lors de l'exécution de la commande, vous pouvez consulter les détails de l'exécution sur la page du hub d'objets.
1. Accédez à la page [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT console et choisissez l'objet pour lequel vous avez créé l'exécution de la commande.
1. Dans la page des détails de l'objet, dans **l'historique des commandes**, vous pouvez voir les exécutions que vous avez créées. Choisissez l'exécution pour laquelle vous souhaitez récupérer des informations.
1. Si vos appareils ont utilisé l'`UpdateCommandExecution`API pour fournir les informations relatives aux résultats, vous pouvez les trouver dans l'onglet **Résultats** de cette page.
### Récupérer une exécution de commande (CLI)
Utilisez l'opération d'API HTTP du plan de [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) 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'`GetCommandExecution`action.
Dans cet exemple, remplacez :
+ `region`avec votre Région AWS, par exemple`us-east-1`.
+ `account-id`avec votre Compte AWS numéro, par exemple`123456789012`.
+ `command-id`avec votre identifiant de AWS IoT commande unique, tel que`LockDoor`.
+ `devices`avec l'un `thing` ou l'autre ou `client` selon que vos appareils ont été enregistrés en tant qu' AWS IoT objets ou sont spécifiés en tant que clients MQTT.
+ `device-id`avec votre AWS IoT `thing-name` or`client-id`.
```
{
"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 :
+ *``*avec l'identifiant de l'exécution de la commande pour laquelle vous souhaitez récupérer des informations.
+ *``*avec le numéro de ressource Amazon (ARN) de l'appareil pour lequel vous ciblez l'exécution. Vous pouvez obtenir ces informations à partir de la réponse de la commande `start-command-execution` CLI.
+ Facultativement, si vos appareils ont utilisé l'`UpdateCommandExection`API pour fournir le résultat de l'exécution, vous pouvez spécifier s'il convient d'inclure le résultat de l'exécution de la commande dans la réponse de l'`GetCommandExecution`API à l'aide de l'`GetCommandExecution`API.
```
aws iot get-command-execution
--execution-id \
--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, consultez[Statut d’exécution de la commande](iot-remote-command-concepts.md#iot-command-execution-status).
Le code suivant montre un exemple de réponse à la demande d'API.
**Note**
Le `completedAt` champ de la réponse d'exécution correspond au moment où l'appareil signale l'état du terminal au cloud. En cas d'`TIMED_OUT`état, ce champ ne sera défini que lorsque l'appareil signalera un délai d'expiration. Lorsque le `TIMED_OUT` statut est défini par le cloud, il n'est pas mis à jour. `TIMED_OUT` Pour plus d'informations sur le comportement en cas de temporisation, consultez[Considérations relatives au délai d'exécution des commandes](#iot-command-execution-timeout).
```
{
"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"
}
```
## Affichage des mises à jour des commandes à l'aide du client de test MQTT
Vous pouvez utiliser le client de test MQTT pour visualiser l'échange de messages via MQTT lorsque vous utilisez la fonction de commandes. Une fois que votre appareil a établi une connexion MQTT avec AWS IoT, vous pouvez créer une commande, spécifier la charge utile, puis l'exécuter sur l'appareil. Lorsque vous exécutez la commande, si votre appareil est abonné à la rubrique des requêtes réservées MQTT pour les commandes, il voit le message de charge utile publié dans cette rubrique.
Le dispositif reçoit ensuite les instructions de charge utile et exécute les opérations spécifiées sur le AWS IoT dispositif. Il utilise ensuite l'`UpdateCommandExecution`API pour publier le résultat de l'exécution des commandes et les informations d'état dans les rubriques de réponse réservées aux commandes du MQTT. AWS IoT Device Management écoute les mises à jour sur les sujets de réponse, stocke les informations mises à jour et publie des journaux sur Amazon AWS CloudTrail et sur Amazon CloudWatch. Vous pouvez ensuite récupérer les dernières informations d'exécution des commandes depuis la console ou à l'aide de l'`GetCommandExecution`API.
Les étapes suivantes montrent comment utiliser le client de test MQTT pour observer les messages.
1. Ouvrez le [client de test MQTT](https://console.aws.amazon.com/iot/home#/test) dans la AWS IoT console.
1. Dans l'onglet **S'abonner**, entrez le sujet suivant, puis choisissez **S'abonner**, où se ** trouve le nom de l'appareil avec lequel vous vous êtes enregistré AWS IoT.
**Note**
Vous trouverez le nom de votre appareil sur la page [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT console. Si vous n'avez pas enregistré votre appareil en tant qu'objet, vous pouvez l'enregistrer lors de la connexion AWS IoT depuis la [page Connect device](https://console.aws.amazon.com/iot/home#/connect-overview).
```
$aws/commands/things//executions/+/request
```
1. (Facultatif) Dans l'onglet **S'abonner**, vous pouvez également saisir les sujets suivants et choisir **S'abonner**.
```
$aws/commands/things/+/executions/+/response/accepted/json
$aws/commands/things/+/executions/+/response/rejected/json
```
1. Lorsque vous lancez l'exécution d'une commande, la charge utile du message est envoyée à l'appareil en utilisant le sujet de demande auquel l'appareil s'est abonné,`$aws/commands/things//executions/+/request`. Dans le client de test MQTT, vous devriez voir la charge utile de commande contenant les instructions permettant au périphérique de traiter la commande.
1. Une fois que le périphérique a commencé à exécuter la commande, il peut publier des mises à jour de statut dans la rubrique de réponse réservée MQTT suivante pour les commandes.
```
$aws/commands///executions//response/json
```
Par exemple, considérez une commande que vous avez exécutée pour allumer le climatiseur de votre voiture afin de réduire la température à la valeur souhaitée. Le JSON suivant montre un exemple de message publié par le véhicule dans le sujet de réponse qui indique qu'il n'a pas réussi à exécuter la commande.
```
{
"deviceId": "My_Car",
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"status": "FAILED",
"statusReason": {
"reasonCode": "CAR_LOW_ON_BATTERY",
"reasonDescription": "Car battery is lower than 5 percent"
}
}
```
Dans ce cas, vous pouvez charger la batterie de votre voiture, puis exécuter à nouveau la commande.
## Répertoriez les exécutions de commandes dans votre Compte AWS
Après avoir exécuté une commande, vous pouvez récupérer des informations sur l'exécution de la commande à partir de la AWS IoT console et à l'aide du AWS CLI. Vous pouvez obtenir les informations suivantes.
+ Un **ID d’exécution**, qui est l’identifiant unique d’exécution de la commande.
+ Le **statut** de l’exécution de la commande. Lorsque vous exécutez la commande sur l’appareil cible, elle passe à l’état `CREATED`. EIle peut ensuite passer à d’autres statuts d’exécution de commande, comme décrit ci-dessous.
+ L’**ID de commande** unique et l’appareil cible pour lequel les exécutions ont été créées.
+ La **Date de début**, qui indique l’heure à laquelle l’exécution de la commande a été créée.
### Répertorier les exécutions de commandes dans votre compte (console)
Vous pouvez voir toutes les exécutions de commandes depuis la console à l'aide de l'une des méthodes suivantes.
+
**Depuis la page Command Hub**
Accédez à la page [Command Hub](https://console.aws.amazon.com/iot/home#/commandHub) de la AWS IoT console et effectuez ces étapes.
1. Choisissez la commande pour laquelle vous avez créé une exécution sur le périphérique cible.
1. Sur la page des détails de la **commande, accédez à l'onglet Historique** des commandes et vous verrez la liste des exécutions que vous avez créées.
+
**Depuis la page du hub Thing**
Si vous avez choisi un AWS IoT objet comme équipement cible lors de l'exécution de la commande et que vous avez créé plusieurs exécutions de commandes pour un seul appareil, vous pouvez consulter les exécutions de cet appareil sur la page du hub d'objets.
1. Accédez à la page [Thing Hub](https://console.aws.amazon.com/iot/home#/thinghub) de la AWS IoT console et choisissez l'objet pour lequel vous avez créé les exécutions.
1. Sur la page des détails de l'objet, dans **l'historique des commandes**, vous pouvez voir la liste des exécutions que vous avez créées pour l'appareil.
### Répertorier les exécutions de commandes dans votre compte (CLI)
Utilisez l'opération d'API HTTP du plan de [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) 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'`ListCommandExecutions`action.
Dans cet exemple, remplacez :
+ `region`avec votre Région AWS, par exemple`us-east-1`.
+ `account-id`avec votre Compte AWS numéro, par exemple`123456789012`.
+ `command-id`avec votre identifiant de AWS IoT commande unique, tel que`LockDoor`.
```
{
"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 de`targetArn`, ou les exécutions pour une commande spécifique spécifiée à l'aide du`commandArn`.
Dans cet exemple, remplacez :
+ *``*avec le numéro de ressource Amazon (ARN) de l'appareil pour lequel vous ciblez l'exécution, tel que`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``*avec le numéro de ressource Amazon (ARN) de l'appareil pour lequel vous ciblez l'exécution, tel que`arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``*avec le délai après lequel vous souhaitez répertorier les exécutions créées, par exemple,`2024-11-01T03:00`.
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{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'`statusReason`objet 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, consultez[Statut d’exécution de la commande](iot-remote-command-concepts.md#iot-command-execution-status).
## Supprimer l'exécution d'une commande
Si vous ne souhaitez plus utiliser l'exécution d'une commande, vous pouvez la supprimer définitivement de votre compte.
**Note**
L'exécution d'une commande ne peut être supprimée que si elle est entrée dans un statut de terminal`SUCCEEDED`, tel que`FAILED`, ou`REJECTED`.
Cette opération ne peut être effectuée qu'à l'aide de l' AWS IoT Core API ou du AWS CLI. Il n'est pas disponible depuis la console.
### Exemple de politique IAM
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 :
+ `Region`avec votre Région AWS, par exemple`us-east-1`.
+ `AccountID`avec votre Compte AWS numéro, par exemple*`123456789012`*.
+ `CommandID`avec l'identifiant de la commande dont vous souhaitez supprimer l'exécution.
+ `devices`avec l'un `thing` ou l'autre ou `client` selon que vos appareils ont été enregistrés en tant qu' AWS IoT objets ou sont spécifiés en tant que clients MQTT.
+ `device-id`avec votre AWS IoT `thing-name` or`client-id`.
```
{
"Effect": "Allow",
"Action": [
"iot:DeleteCommandExecution"
],
"Resource": [
"arn:aws:iot:region:account-id:command/command-id",
"arn:aws:iot:region:account-id:devices/device-id"
]
}
```
### Supprimer un exemple d'exécution de commande
L'exemple suivant montre comment supprimer une commande à l'aide de cette `delete-command` AWS CLI commande. En fonction de votre application, remplacez-le *``* par l'identifiant de l'exécution de la commande que vous supprimez, puis *``* par l'ARN de votre appareil cible.
```
aws iot delete-command-execution \
--execution-id \
--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'`GetCommandExecution`API pour vérifier que l'exécution de la commande n'existe plus dans votre compte.