API REST Device Shadow - AWS IoT Core
GetThingShadowUpdateThingShadowDeleteThingShadowListNamedShadowsForThing

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.

API REST Device Shadow

Un shadow expose l'URI suivante pour mettre à jour les informations d'état :

https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow

Le point de terminaison est spécifique à votre Compte AWS. Pour trouver votre point de terminaison, vous pouvez :

  • Utilisez la commande describe-endpoint du AWS CLI.

  • Utilisez les paramètres AWS IoT de la console. Dans Paramètres, le point de terminaison est répertorié sous Point de terminaison personnalisé

  • Utilisez la page des détails de la AWS IoT console. Dans la console  :

    1. Ouvrez Gérer et sous Gérer, sélectionnez Objets.

    2. Dans la liste des éléments, choisissez l'élément pour lequel vous souhaitez obtenir l'URI du point de terminaison.

    3. Choisissez l'onglet Device Shadows et choisissez votre ombre. Vous pouvez consulter l'URI du point de terminaison dans la section Device Shadow URL de la page de détails du Device Shadow.

Le format du point de terminaison est le suivant :

identifier.iot.region.amazonaws.com

L'API REST Shadow suit les mêmes protocoles HTTPS/mappages de ports que ceux décrits dans Protocoles de communication des appareils.

Note

Pour utiliser les API, vous devez les utiliser iotdevicegateway comme nom de service pour l'authentification. Pour plus d'informations, consultez IoT DataPlane.

Vous pouvez également utiliser l'API pour créer une ombre nommée en la fournissant dans le name=shadowName cadre du paramètre de requête de l'API.

GetThingShadow

Obtient le shadow de l'objet spécifié.

Le document d'état de réponse comprend le delta entre les états desired et reported.

Demande

La demande comprend les en-têtes HTTP standard, plus l'URI suivante :

HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

Le paramètre de requête name n'est pas requis pour les shadows non nommés (classiques).

Réponse

En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :

HTTP 200
Response Body: response state document

Pour plus d'informations, consultez Exemple de document d'état de réponse.

Autorisation

La récupération d'un shadow nécessite une stratégie qui permet au mandataire de réaliser l'action iot:GetThingShadow. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.

Voici un exemple de stratégie qui permet à un mandataire de récupérer un shadow d'appareil :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:GetThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

UpdateThingShadow

Met à jour le shadow de l'objet spécifié.

Les mises à jour concernent uniquement les champs spécifiés dans le document d'état de la demande. Tout champ avec une valeur null est supprimé du shadow d'appareil.

Demande

La demande comprend les en-têtes HTTP standard, plus l'URI et le corps suivants :

HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document

Le paramètre de requête name n'est pas requis pour les shadows non nommés (classiques).

Pour plus d'informations, consultez Exemple de document d'état de la demande.

Réponse

En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :

HTTP 200
Response body: response state document

Pour plus d'informations, consultez Exemple de document d'état de réponse.

Autorisation

La mise à jour d'un shadow nécessite une stratégie qui permet au mandataire de réaliser l'action iot:UpdateThingShadow. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.

Voici un exemple de stratégie qui permet à un mandataire de mettre à jour un shadow d'appareil :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:UpdateThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

DeleteThingShadow

Supprime le shadow de l'objet spécifié.

Demande

La demande comprend les en-têtes HTTP standard, plus l'URI suivante :

HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)

Le paramètre de requête name n'est pas requis pour les shadows non nommés (classiques).

Réponse

En cas de réussite, la réponse comprend les en-têtes HTTP standard, plus le code et le corps suivants :

HTTP 200
Response body: Empty response state document

Notez que la suppression d'une ombre ne rétablit pas son numéro de version à 0.

Autorisation

La suppression d'un shadow d'appareil nécessite une stratégie qui permet au mandataire de réaliser l'action iot:DeleteThingShadow. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.

Voici un exemple de stratégie qui permet à un mandataire de supprimer un shadow d'appareil :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:DeleteThingShadow",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}

ListNamedShadowsForThing

Répertorie les shadows de l'objet spécifié.

Demande

La demande comprend les en-têtes HTTP standard, plus l'URI suivante :

HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
nextToken

Jeton permettant de récupérer l'ensemble suivant de résultats.

Cette valeur est renvoyée sur les résultats paginés et est utilisée dans l'appel qui renvoie la page suivante.

pageSize

Nombre de noms de shadows à renvoyer dans chaque appel. Voir aussi nextToken.

thingName

Nom de l'objet pour lequel répertorier les shadows nommés.

Réponse

En cas de succès, la réponse comprend les en-têtes HTTP standard ainsi que le code de réponse suivant et un message de type Document de réponse de liste de noms de shadows

Note

Le shadow non nommé (classique) n'apparaît pas dans cette liste. La réponse est une liste vide si vous n'avez qu'une ombre classique ou si celle thingName que vous spécifiez n'existe pas.

HTTP 200
Response body: Shadow name list document
Autorisation

L'énumération de l'ombre d'un appareil nécessite une politique permettant à l'appelant d'effectuer l'action iot:ListNamedShadowsForThing. Le service Device Shadow accepte deux formes d'authentification : Signature Version 4 avec des informations d'identification IAM ou authentification mutuelle TLS avec un certificat client.

Voici un exemple de stratégie qui permet à un mandataire de répertorier les shadows nommés d'un objet :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:ListNamedShadowsForThing",
      "Resource": [
        "arn:aws:iot:region:account:thing/thing"
      ]
    }
  ]
}