Documents du service Device Shadow - AWS IoT Core
Exemples de documents shadowPropriétés du documentÉtat DeltaDocuments shadow de gestion des versionsJetons clients dans les documents shadowPropriétés de document shadow videsValeurs de tableau dans les documents shadow

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.

Documents du service Device Shadow

Le service Device Shadow respecte toutes les règles de la spécification JSON. Valeurs, objets et tableaux sont stockés dans le document shadow de l'appareil.

Exemples de documents shadow

Le service Device Shadow utilise les documents suivants dans les opérations UPDATE, GET et DELETE à l'aide de l'API REST ou des messages de publication/abonnement MQTT.

Document d'état de demande

Un document d'état de demande a le format suivant :

{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}

  • state — Les mises à jour affectent uniquement les champs spécifiés. Généralement, vous utiliserez la propriété reported ou la propriété desired, mais pas les deux dans la même demande.

    • desired — Les propriétés d'état et les valeurs dont la mise à jour est demandé dans l’appareil.

    • reported — Les propriétés d'état et les valeurs signalées par l’appareil.

  • clientToken — Si utilisé, vous pouvez faire correspondre la requête et la réponse correspondante par le jeton client.

  • version — Le service Device Shadow traite la mise à jour uniquement si la version spécifiée correspond à la dernière version qu'il a.

Documents d'état de la réponse

Les documents d'état de la réponse ont le format suivant, selon le type de réponse.

/document d'état de la réponse accepté

{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/documents d'état de la réponse delta

{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
    },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}

/documents d'état de la réponse documents

{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}

Propriétés du document d'état de réponse

  • state — Après une mise à jour réussie, il contient l’ de l'objet avant la mise à jour.

  • state — Après une mise à jour réussie, il contient l’ de l'objet après la mise à jour.

  • state

    • reported — Présent uniquement si un objet a déclaré des données dans la section et qu'il contient uniquement les champs qui se trouvaient dans le document d’état de la demande.

    • desired — Présente uniquement si un dispositif a communiqué des données dans la desired section et contient uniquement des champs qui figuraient dans le document d'état de la demande.

    • delta desired Présent uniquement si les données diffèrent des données actuelles du shadow.

  • metadata — Contient les horodatages pour chaque attribut dans le desired et reported sections et afin que vous puissiez déterminer quand l'état a été mis à jour.

  • timestamp— La date et l'heure d'époque auxquelles la réponse a été générée AWS IoT.

  • clientToken — Présent uniquement si un jeton client a été utilisé lors de la publication d'un JSON valide dans la rubrique .

  • version — Version actuelle du document du shadow de l'appareil partagé dans AWS IoT. Elle est augmentée d'une unité par rapport à la version précédente du document.

Document de réponse d'erreur

— Un document de réponse d'erreur a le format suivant :

{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

  • code — Code de réponse HTTP qui indique le type d'erreur.

  • message — Message texte qui fournit des informations supplémentaires.

  • timestamp— Date et heure auxquelles la réponse a été générée AWS IoT. Cette propriété n'est pas présente dans tous les documents de réponse d’erreur.

  • clientToken— Présent uniquement si un jeton client a été utilisé dans le message publié.

Pour de plus amples informations, veuillez consulter Messages d'erreur de Device Shadow.

Document de réponse de liste de noms de shadows

Un document de réponse de liste de noms de shadows a le format suivant :

{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}

  • results— Le tableau des noms des ombres.

  • nextToken— La valeur du jeton à utiliser dans les demandes paginées pour obtenir la page suivante de la séquence. Cette propriété n'est pas présente quand il ne reste plus de noms de shadows à renvoyer.

  • timestamp— Date et heure auxquelles la réponse a été générée AWS IoT.

Propriétés du document

Un document de shadow d'appareil possède les propriétés suivantes :

state
desired

État souhaité de l'appareil. Les applications peuvent écrire dans cette partie du document pour mettre à jour l'état d'un appareil directement sans avoir à s'y connecter.

reported

État rapporté de l'appareil. Les appareils écrivent dans cette partie du document pour rapporter leur nouvel état. Les applications lisent cette partie du document pour déterminer le dernier état rapporté de l'appareil.

metadata

Informations sur les données stockées dans la section state du document. Il s'agit notamment des horodatages, en heure Unix, de chaque attribut de la section state, qui vous permet de déterminer quand ils ont été mis à jour.

Note

Les métadonnées ne contribuent pas à la taille du document pour les limites de service ou la tarification. Pour plus d'informations, consultez AWS IoT Limites de service .

timestamp

Indique quand le message a été envoyé par AWS IoT. En utilisant l'horodatage dans le message et les horodatages pour les attributs individuels dans la section desired ou reported, un appareil peut déterminer l'âge d'une propriété, même si l'appareil n'a pas d'horloge interne.

clientToken

Chaîne unique du dispositif qui permet d'associer les réponses à des demandes dans un environnement MQTT.

version

Version du document. Chaque fois que le document est mis à jour, ce numéro de version est incrémenté. Permet de s'assurer que la version du document en cours de mise à jour est la plus récente.

Pour de plus amples informations, veuillez consulter Exemples de documents shadow.

État Delta

L'état Delta est un type virtuel d'état qui contient l'écart entre les états desired et reported. Les champs de la section desired qui ne figurent pas dans la section reported sont inclus dans le delta. Les champs qui figurent dans la section reported mais pas dans la section desired ne sont pas inclus dans le delta. Le delta contient des métadonnées et ses valeurs sont égales aux métadonnées contenues dans le champ desired. Par exemple :

{
  "state": {
    "desired": {
      "color": "RED",
      "state": "STOP"
    },
    "reported": {
      "color": "GREEN",
      "engine": "ON"
    },
    "delta": {
      "color": "RED",
      "state": "STOP"
    }
  },
  "metadata": {
    "desired": {
      "color": {
        "timestamp": 12345
      },
      "state": {
        "timestamp": 12345
      }
      },
      "reported": {
        "color": {
          "timestamp": 12345
        },
        "engine": {
          "timestamp": 12345
        }
      },
      "delta": {
        "color": {
          "timestamp": 12345
        },
        "state": {
          "timestamp": 12345
        }
      }
    },
    "version": 17,
    "timestamp": 123456789
  }
}

Lorsque des objets imbriqués diffèrent, le delta contient le chemin d'accès à la racine.

{
  "state": {
    "desired": {
      "lights": {
        "color": {
          "r": 255,
          "g": 255,
          "b": 255
        }
      }
    },
    "reported": {
      "lights": {
        "color": {
          "r": 255,
          "g": 0,
          "b": 255
        }
      }
    },
    "delta": {
      "lights": {
        "color": {
          "g": 255
        }
      }
    }
  },
  "version": 18,
  "timestamp": 123456789
}

Le service Device Shadow calcule le delta en itérant sur chaque champ de l'état desired et en le comparant à l'état reported.

Les tableaux sont traités comme des valeurs. Si un tableau de la section desired ne correspond pas au tableau de la section reported, l'intégralité du tableau souhaité est copiée dans le delta.

Documents shadow de gestion des versions

Le service Device Shadow prend en charge la gestion des versions sur chaque message de mise à jour, qu'il s'agisse de la demande ou de la réponse. Cela signifie qu'à chaque mise à jour d'un shadow, la version du document JSON est incrémentée. Cela permet de garantir deux choses :

  • Un client peut recevoir une erreur s'il tente de remplacer un shadow par un numéro de version plus ancien. Le client est informé qu'il doit effectuer une resynchronisation avant de mettre à jour un shadow d'appareil.

  • Un client peut décider de ne pas agir sur un message reçu si le message est d'une version inférieure à la version stockée par le client.

Un client peut contourner la mise en correspondance des versions en n'incluant pas de version dans le document shadow.

Jetons clients dans les documents shadow

Vous pouvez utiliser un jeton client avec la messagerie MQTT pour vérifier si une demande et une réponse contiennent le même jeton client. Cela garantit que la réponse et la demande sont associées.

Note

La longueur du jeton client ne peut pas dépasser 64 octets. Un jeton client d'une longueur supérieure à 64 octets génère une réponse 400 (Demande erronée) et un message d'erreur ClientToken non valide.

Propriétés de document shadow vides

Les propriétés reported et desired d'un document shadow peuvent être vides ou omises lorsqu'elles ne s'appliquent pas à l'état actuel du shadow. Par exemple, un document shadow contient une propriété desired uniquement s'il a un état souhaité. Voici un exemple valide d'un document d'état sans propriété desired :

{
    "reported" : { "temp": 55 }
}

La propriété reported peut également être vide, par exemple si le shadow n'a pas été mis à jour par l'appareil :

{
    "desired" : { "color" : "RED" }
}

Si une mise à jour entraîne l'affectation de la valeur null aux propriétés desired ou reported, elle est supprimée du document. Voici comment supprimer la propriété desired en la définissant sur null. Vous pouvez le faire lorsqu'un appareil met à jour son état, par exemple.

{ 
    "state": {
        "reported": {
            "color": "red" 
        }, 
        "desired": null 
    } 
}

Un document shadow peut également n'avoir aucune des propriétés desired et reported, auquel cas le document shadow est vide. Ceci est un exemple de document shadow vide, mais valide.

{
}

Valeurs de tableau dans les documents shadow

Les shadows prennent en charge les tableaux, mais les traitent comme des valeurs normales, dans la mesure où une mise à jour d'un tableau remplace l'intégralité du tableau. Il n'est pas possible de mettre à jour une partie d'un tableau.

État initial :

{
    "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}

Mise à jour:

{
    "desired" : { "colors" : ["RED"] }
}

État final :

{
    "desired" : { "colors" : ["RED"] }
}

Les tableaux ne peuvent pas avoir de valeurs null. Par exemple, le tableau suivant n'est pas valide et sera rejeté.

{
    "desired" : { 
        "colors" : [ null, "RED", "GREEN" ]
    }
}