Interaction avec les shadows - AWS IoT Core
Support du protocoleDemande d'état et génération de rapport d'étatMise à jour d'un shadowRécupération d'un document ShadowSuppression de données 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.

Interaction avec les shadows

Cette rubrique décrit les messages associés à chacune des trois méthodes fournies par AWS IoT qui permettent de travailler avec les shadows. Il s'agit notamment des méthodes suivantes :

UPDATE

Crée un shadow s'il n'existe pas ou met à jour le contenu d'un shadow existant avec les informations d'état fournies dans le corps de message. AWS IoT enregistre un horodatage avec chaque mise à jour pour indiquer quand l'état a été mis à jour pour la dernière fois. Lorsque l'état de l'ombre change, AWS IoT envoie /delta des messages à tous les MQTT abonnés avec la différence entre les reported états desired et. Les appareils ou les applications qui reçoivent un message /delta peuvent effectuer des actions en fonction de cette différence. Par exemple, un appareil peut mettre à jour son état à l'état souhaité, ou une application peut mettre à jour son interface utilisateur pour refléter le changement d'état de l'appareil.

GET

Récupère un document shadow actuel qui contient l'état complet du shadow, y compris les métadonnées.

DELETE

Supprime l'ombre de l'appareil et son contenu.

Vous ne pouvez pas restaurer un document fantôme supprimé sur un appareil, mais vous pouvez en créer un nouveau avec le nom d'un document fantôme supprimé sur un appareil. Si vous créez un document fantôme de terminal portant le même nom qu'un document supprimé au cours des dernières 48 heures, le numéro de version du nouveau document fantôme de terminal suivra celui du document supprimé. Si le document fantôme d'un appareil a été supprimé pendant plus de 48 heures, le numéro de version d'un nouveau document fantôme de l'appareil portant le même nom sera 0.

Support du protocole

AWS IoT supports MQTTet HTTPS protocoles REST API supplémentaires pour interagir avec les ombres. AWS IoT fournit un ensemble de sujets de demande et de réponse réservés pour les actions de MQTT publication et d'abonnement. Les appareils et les applications doivent s'abonner aux sujets de réponse avant de publier un sujet de demande pour obtenir des informations sur le AWS IoT traitement de la demande. Pour plus d’informations, consultez MQTTSujets relatifs à Device Shadow et Device Shadow REST API.

Demande d'état et génération de rapport d'état

Lorsque vous concevez votre solution IoT à l'aide de AWS IoT et d'ombres, vous devez déterminer les applications ou les appareils qui demanderont des modifications et ceux qui les mettront en œuvre. Généralement, un appareil implémente les modifications et les rapporte au shadow, et les applications et services y répondent et demandent les modifications dans le shadow. Votre solution peut être différente, mais les exemples de cette rubrique supposent que l'application ou le service client demande les modifications dans le shadow et que l'appareil effectue ces modifications et les rapporte en retour au shadow.

Mise à jour d'un shadow

Votre application ou service peut mettre à jour l'état d'un shadow en utilisant le /update sujet UpdateThingShadow API ou en le publiant sur celui-ci. Les mises à jour concernent uniquement les champs spécifiés dans la demande.

Mise à jour d'un shadow lorsqu'un client demande un changement d'état

Lorsqu'un client demande un changement d'état dans un shadow en utilisant le MQTT protocole

  1. Le client doit disposer d'un document shadow actuel pour pouvoir identifier les propriétés à modifier. Veuillez consulter l'action /get pour voir comment obtenir le document shadow actuel.

  2. Le client s'abonne aux MQTT rubriques suivantes :

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  3. Le client publie une rubrique de demande $aws/things/thingName/shadow/name/shadowName/update avec un document d'état qui contient l'état souhaité du shadow. Seules les propriétés à modifier doivent être incluses dans ce document. Ceci est un exemple de document avec l'état souhaité.

    {
  "state": {
    "desired": {
      "color": {
        "r": 10
      },
      "engine": "ON"
    }
  }
}

  4. Si la demande de mise à jour est valide, AWS IoT met à jour l'état souhaité dans l'ombre et publie des messages sur les sujets suivants :

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    Le message /update/accepted contient un document shadow /document d'état de la réponse accepté et le message /update/delta contient un document shadow /documents d'état de la réponse delta.

  5. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le $aws/things/thingName/shadow/name/shadowName/update/rejected sujet avec un document Document de réponse d'erreur fantôme décrivant l'erreur.

Lorsqu'un client demande un changement d'état dans un environnement parallèle à l'aide du API

  1. Le client appelle le UpdateThingShadow API avec un document d'Document d'état de demandeétat comme corps de message.

  2. Si la demande était valide, AWS IoT renvoie un code HTTP de réponse positive et un document /document d'état de la réponse accepté fantôme dans le corps du message de réponse.

    AWS IoT publiera également un MQTT message sur le $aws/things/thingName/shadow/name/shadowName/update/delta sujet avec un document /documents d'état de la réponse delta fantôme pour tous les appareils ou clients qui s'y abonnent.

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse HTTP d'erreur an Document de réponse d'erreur comme corps du message de réponse.

Lorsque l'appareil reçoit l'état /desired sur la rubrique /update/delta, il effectue les modifications souhaitées sur l'appareil. Il envoie ensuite un message à la rubrique /update pour rapporter son état actuel au shadow.

Mise à jour d'un shadow lorsqu'un appareil rapporte son état actuel

Lorsqu'un appareil signale son état actuel à l'ombre en utilisant le MQTT protocole

  1. L'appareil doit s'abonner à ces MQTT rubriques avant de mettre à jour le shadow :

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

    • $aws/things/thingName/shadow/name/shadowName/update/delta

    • $aws/things/thingName/shadow/name/shadowName/update/documents

  2. L'appareil rapporte son état actuel en publiant un message dans la rubrique $aws/things/thingName/shadow/name/shadowName/update qui rapporte l'état actuel, comme dans cet exemple.

    {
    "state": {
        "reported" : {
            "color" : { "r" : 10 },
            "engine" : "ON"
        }
    }
}

  3. S'il AWS IoT accepte la mise à jour, il publie un message aux $aws/things/thingName/shadow/name/shadowName/update/accepted rubriques avec un document /document d'état de la réponse accepté fantôme.

  4. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le $aws/things/thingName/shadow/name/shadowName/update/rejected sujet avec un document Document de réponse d'erreur fantôme décrivant l'erreur.

Lorsqu'un appareil signale son état actuel à l'ombre à l'aide du API

  1. L'appareil appelle le UpdateThingShadow API avec un document d'Document d'état de demandeétat comme corps de message.

  2. Si la demande était valide, AWS IoT met à jour le fantôme et renvoie un HTTP code de réponse positive avec un document /document d'état de la réponse accepté fantôme comme corps du message de réponse.

    AWS IoT publiera également un MQTT message sur le $aws/things/thingName/shadow/name/shadowName/update/delta sujet avec un document /documents d'état de la réponse delta fantôme pour tous les appareils ou clients qui s'y abonnent.

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse HTTP d'erreur an Document de réponse d'erreur comme corps du message de réponse.

Verrouillage optimiste

Vous pouvez utiliser la version du document d'état pour vous assurer que vous mettez à jour la version la plus récente d'un document shadow d'appareil. Lorsque vous fournissez une version avec une demande de mise à jour, le service rejette la demande avec un code de réponse de conflit HTTP 409 si la version actuelle du document d'état ne correspond pas à la version fournie. Le code de réponse au conflit peut également apparaître sur tout API ce qui est modifiéThingShadow, y comprisDeleteThingShadow.

Par exemple :

Document initial :

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

Mise à jour : (la version ne correspond pas ; cette demande est rejetée)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 9
}

Résultat:

{
  "code": 409,
  "message": "Version conflict",
  "clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}

Mise à jour : (la version correspond ; cette demande est acceptée)

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 10
}

État final :

{
  "state": {
    "desired": {
      "colors": [
        "BLUE"
      ]
    }
  },
  "version": 11
}

Récupération d'un document Shadow

Vous pouvez récupérer un document fantôme en utilisant le GetThingShadow API ou en vous abonnant et en publiant sur le /get sujet. Ceci récupère un document shadow complet, y compris tout delta entre les états desired et reported. La procédure pour cette tâche est la même que l'appareil ou un client effectue la demande.

Pour récupérer un document fantôme à l'aide du MQTT protocole

  1. L'appareil ou le client doit s'abonner à ces MQTT rubriques avant de mettre à jour le shadow :

    • $aws/things/thingName/shadow/name/shadowName/get/accepted

    • $aws/things/thingName/shadow/name/shadowName/get/rejected

  2. L'appareil ou le client publie un message dans la rubrique $aws/things/thingName/shadow/name/shadowName/get avec un corps de message vide.

  3. Si la demande aboutit, AWS IoT publie un message dans le $aws/things/thingName/shadow/name/shadowName/get/accepted sujet avec un /document d'état de la réponse accepté dans le corps du message.

  4. Si la demande n'est pas valide, AWS IoT publie un message dans le $aws/things/thingName/shadow/name/shadowName/get/rejected sujet avec un Document de réponse d'erreur dans le corps du message.

Pour récupérer un document fictif à l'aide d'un REST API

  1. L'appareil ou le client appelle le GetThingShadow API avec un corps de message vide.

  2. Si la demande est valide, AWS IoT renvoie un code de réponse de HTTP réussite avec un document /document d'état de la réponse accepté fantôme comme corps du message de réponse.

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse HTTP d'erreur an Document de réponse d'erreur comme corps du message de réponse.

Suppression de données shadow

Il existe deux façons de supprimer des données shadow : vous pouvez supprimer les propriétés spécifiques dans le document shadow et vous pouvez supprimer complètement le shadow.

  • Pour supprimer des propriétés spécifiques d'un shadow, mettez à jour le shadow. Toutefois, définissez la valeur des propriétés à supprimer sur null. Les champs dotés d'une valeur null sont supprimés du document shadow.

  • Pour supprimer l'ombre dans son intégralité, utilisez le DeleteThingShadow API ou publiez sur le /delete sujet.

Note

La suppression d'une ombre ne remet pas immédiatement son numéro de version à zéro. Il sera remis à zéro au bout de 48 heures.

Suppression d'une propriété dans un document shadow

Pour supprimer une propriété d'une ombre à l'aide du MQTT protocole

  1. L'appareil ou le client doit disposer d'un document shadow actuel pour pouvoir identifier les propriétés à modifier. Veuillez consulter Récupération d'un document Shadow pour obtenir des informations sur la façon d'obtenir le document shadow actuel.

  2. L'appareil ou le client s'abonne aux MQTT rubriques suivantes :

    • $aws/things/thingName/shadow/name/shadowName/update/accepted

    • $aws/things/thingName/shadow/name/shadowName/update/rejected

  3. L'appareil ou le client publie une rubrique de demande $aws/things/thingName/shadow/name/shadowName/update avec un document d'état qui attribue des valeurs null aux propriétés du shadow à supprimer. Seules les propriétés à modifier doivent être incluses dans ce document. Voici un exemple de document qui supprime la propriété engine.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  4. Si la demande de mise à jour est valide, AWS IoT supprime les propriétés spécifiées dans l'ombre et publie un message avec le $aws/things/thingName/shadow/name/shadowName/update/accepted sujet avec un document /document d'état de la réponse accepté fantôme dans le corps du message.

  5. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le $aws/things/thingName/shadow/name/shadowName/update/rejected sujet avec un document Document de réponse d'erreur fantôme décrivant l'erreur.

Pour supprimer une propriété d'une ombre à l'aide du REST API

  1. L'appareil ou le client appelle le UpdateThingShadow API with a Document d'état de demande qui attribue des null valeurs aux propriétés de l'ombre à supprimer. Incluez uniquement les propriétés que vous souhaitez supprimer dans le document. Voici un exemple de document qui supprime la propriété engine.

    {
  "state": {
    "desired": {
      "engine": null
    }
  }
}

  2. Si la demande était valide, AWS IoT renvoie un code HTTP de réponse positive et un document /document d'état de la réponse accepté fantôme dans le corps du message de réponse.

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse HTTP d'erreur an Document de réponse d'erreur comme corps du message de réponse.

Suppression d'un shadow

Vous trouverez ci-après quelques considérations relatives à la suppression de l'ombre d'un appareil.

  • La définition de l'état de shadow de l'appareil sur null ne supprime pas le shadow. La version de shadow sera incrémentée lors de la prochaine mise à jour.

  • La suppression d'un shadow d'appareil ne supprime pas l'objet d'objet. La suppression d'un objet d'objet ne supprime pas le shadow d'appareil correspondant.

  • La suppression d'une ombre ne remet pas immédiatement son numéro de version à zéro. Il sera remis à zéro au bout de 48 heures.

Pour supprimer une ombre à l'aide du MQTT protocole

  1. L'appareil ou le client s'abonne aux MQTT rubriques suivantes :

    • $aws/things/thingName/shadow/name/shadowName/delete/accepted

    • $aws/things/thingName/shadow/name/shadowName/delete/rejected

  2. L'appareil ou le client publie un $aws/things/thingName/shadow/name/shadowName/delete avec un tampon de messages vide.

  3. Si la demande de suppression est valide, AWS IoT supprime l'ombre et publie un message avec le $aws/things/thingName/shadow/name/shadowName/delete/accepted sujet et un document /document d'état de la réponse accepté fantôme abrégé dans le corps du message. Voici un exemple du message de suppression accepté :

    {
  "version": 4,
  "timestamp": 1591057529
}

  4. Si la demande de mise à jour n'est pas valide, AWS IoT publie un message avec le $aws/things/thingName/shadow/name/shadowName/delete/rejected sujet avec un document Document de réponse d'erreur fantôme décrivant l'erreur.

Pour supprimer une ombre à l'aide du REST API

  1. L'appareil ou le client appelle le DeleteThingShadow API avec une mémoire tampon de messages vide.

  2. Si la demande était valide, AWS IoT renvoie un HTTP code de réponse positive /document d'état de la réponse accepté et un document /document d'état de la réponse accepté fantôme abrégé dans le corps du message. Voici un exemple du message de suppression accepté :

    {
  "version": 4,
  "timestamp": 1591057529
}

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse HTTP d'erreur an Document de réponse d'erreur comme corps du message de réponse.