Device Shadow REST API - 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.

Device Shadow REST API

Une ombre expose les éléments suivants URI 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 de détails des éléments 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'objet pour lequel vous souhaitez obtenir le point de terminaisonURI.

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

Le format du point de terminaison est le suivant :

identifier.iot.region.amazonaws.com

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

Note

Pour utiliser leAPIs, vous devez l'utiliser iotdevicegateway comme nom de service pour l'authentification. Pour plus d'informations, consultez I oTData Plane.

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

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 inclut les HTTP en-têtes standard ainsi que les éléments suivants : URI

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 succès, la réponse inclut les HTTP en-têtes standard ainsi que 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 IAM informations d'identification ou authentification TLS mutuelle 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 inclut les HTTP en-têtes standard ainsi que les éléments suivants URI et le corps :

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 succès, la réponse inclut les HTTP en-têtes standard ainsi que 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 IAM informations d'identification ou authentification TLS mutuelle 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 inclut les HTTP en-têtes standard ainsi que les éléments suivants : URI

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 succès, la réponse inclut les HTTP en-têtes standard ainsi que 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 IAM informations d'identification ou authentification TLS mutuelle 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 inclut les HTTP en-têtes standard ainsi que les éléments suivants : URI

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 inclut les HTTP en-têtes standard ainsi que le code de réponse suivant et unDocument 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 IAM informations d'identification ou authentification TLS mutuelle 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"
      ]
    }
  ]
}