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 abonnés MQTT 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 prend en charge le MQTT et une API REST via les protocoles HTTPS 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 publication et d'abonnement MQTT. 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 Rubriques MQTT de Device Shadow et API REST Device Shadow.

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 à l'aide de l'API UpdateThingShadow ou en publiant dans la rubrique /update. 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

Quand un client demande un changement d'état dans un shadow à l'aide du protocole MQTT

  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 rubriques MQTT 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.

Quand un client demande un changement d'état dans un shadow à l'aide de l'API

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

  2. Si la demande était valide, AWS IoT renvoie un code de réponse de réussite HTTP 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 message MQTT 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 d'erreur HTTP 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

Quand un appareil rapporte son état actuel au shadow à l'aide du protocole MQTT

  1. L'appareil doit s'abonner aux rubriques MQTT suivantes 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.

Quand un appareil rapporte son état actuel au shadow à l'aide de l'API

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

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

    AWS IoT publiera également un message MQTT 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 d'erreur HTTP 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 dans 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 n'importe quelle API modifiéeThingShadow, notammentDeleteThingShadow.

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 shadow à l'aide de l'API GetThingShadow ou en vous abonnant et en publiant dans la rubrique /get. 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 shadow à l'aide du protocole MQTT

  1. L'appareil ou le client doit s'abonner à ces rubriques MQTT 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 shadow à l'aide d'une API REST

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

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

  3. Si la demande n'est pas valide, AWS IoT renvoie un code de réponse d'erreur HTTP 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 le shadow entier, utilisez l'API DeleteThingShadow ou publiez dans la rubrique /delete.

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é dans un shadow à l'aide du protocole MQTT

  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 rubriques MQTT 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'un shadow à l'aide de l'API REST

  1. L'appareil ou le client appelle l'API UpdateThingShadow avec un Document d'état de demande qui attribue des valeurs null aux propriétés du shadow à 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 de réponse de réussite HTTP 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 d'erreur HTTP 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 un shadow à l'aide du protocole MQTT

  1. L'appareil ou le client s'abonne aux rubriques MQTT 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 un shadow à l'aide de l'API REST

  1. L'appareil ou le client appelle l'API DeleteThingShadow avec un tampon de messages vide.

  2. Si la demande était valide, AWS IoT renvoie un code de réponse de réussite HTTP /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 d'erreur HTTP an Document de réponse d'erreur comme corps du message de réponse.