Interazione con le copia shadow - AWS IoT Core
Supporto dei protocolliStato di richiesta e segnalazioneAggiornamento di una copia shadowRecupero di un documento di una copia shadowEliminazione di dati shadow

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Interazione con le copia shadow

In questo argomento vengono descritti i messaggi associati a ciascuno dei tre metodi che AWS IoT offre per utilizzare le copie shadow. Questi metodi includono i seguenti:

UPDATE

Crea una copia shadow se non esiste o aggiorna il contenuto di una copia shadow esistente con le informazioni sullo stato fornite nel corpo del messaggio. AWS IoT registra un timestamp con ogni aggiornamento per indicare l'ultimo aggiornamento dello stato. Quando lo stato dell'ombra cambia, AWS IoT invia /delta messaggi a tutti gli abbonati MQTT con la differenza tra gli stati desired e. reported I dispositivi o le app che ricevono un messaggio /delta possono eseguire operazioni in base alla differenza. Un dispositivo, ad esempio, può aggiornare il proprio stato allo stato desiderato oppure un'app può aggiornare la propria interfaccia utente per visualizzare la modifica dello stato del dispositivo.

GET

Recupera un documento shadow corrente che contiene lo stato completo della copia shadow, inclusi i metadati.

DELETE

Elimina il Device Shadow e il suo contenuto.

Non è possibile ripristinare un documento del Device Shadow eliminato, ma è possibile creare un nuovo Device Shadow con il nome di un documento Device Shadow eliminato. Se si crea un documento del Device Shadow con lo stesso nome di quello eliminato nelle ultime 48 ore, il nuovo documento riporterà il numero di versione seguente rispetto al documento eliminato. Se un documento del Device Shadow è stato eliminato da più di 48 ore, il numero di versione del nuovo documento del Device Shadow, riportante lo stesso nome, sarà 0.

Supporto dei protocolli

AWS IoT supporta MQTT e un'API REST su protocolli HTTPS per interagire con le ombre. AWS IoT fornisce una serie di argomenti riservati di richiesta e risposta per le azioni di pubblicazione e sottoscrizione di MQTT. I dispositivi e le app devono sottoscrivere gli argomenti di risposta prima di pubblicare un argomento di richiesta di informazioni su come viene AWS IoT gestita la richiesta. Per ulteriori informazioni, consultare Argomenti MQTT di Device Shadow e API REST del servizio Device Shadow.

Stato di richiesta e segnalazione

Quando si progetta una soluzione IoT utilizzando AWS IoT e shadows, è necessario determinare le app o i dispositivi che richiederanno le modifiche e quelli che le implementeranno. In genere, un dispositivo implementa e segnala le modifiche alla copia shadow e le app e i servizi rispondono e richiedono modifiche nella copia shadow. La soluzione potrebbe essere diversa, ma gli esempi in questo argomento presuppongono che l'app client o il servizio richieda modifiche nella copia shadow e che il dispositivo esegua le modifiche e le riporti alla copia shadow.

Aggiornamento di una copia shadow

L'app o il servizio possono aggiornare lo stato di una copia shadow utilizzando l'API UpdateThingShadow o pubblicando sull'argomento /update. Gli aggiornamenti interessano solo i campi specificati nella richiesta.

Aggiornamento di una copia shadow quando un client richiede una modifica di stato

Quando un client richiede una modifica di stato in una copia shadow utilizzando il protocollo MQTT

  1. Il client deve disporre di un documento shadow corrente in modo che possa identificare le proprietà da modificare. Vedere l'operazione /get per capire come ottenere il documento shadow corrente.

  2. Il client sottoscrive questi argomenti MQTT:

    • $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. Il client pubblica un argomento di richiesta $aws/things/thingName/shadow/name/shadowName/update con un documento di stato che contiene lo stato desiderato della copia shadow. Solo le proprietà da modificare devono essere incluse nel documento. Questo è un esempio di documento con lo stato desiderato.

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

  4. Se la richiesta di aggiornamento è valida, AWS IoT aggiorna lo stato desiderato nell'ombra e pubblica messaggi sui seguenti argomenti:

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

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

    Il messaggio /update/accepted contiene un documento shadow /accepted response state document e il messaggio /update/delta contiene un documento shadow /delta response state document.

  5. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/update/rejectedargomento con un documento Documenti sulla risposta di errore ombra che descrive l'errore.

Quando un client richiede una modifica di stato in una copia shadow utilizzando l'API

  1. Il client chiama l'API UpdateThingShadow con un documento di stato Documento sullo stato della richiesta come corpo del messaggio.

  2. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP e un documento /accepted response state document shadow come corpo del messaggio di risposta.

    AWS IoT pubblicherà anche un messaggio MQTT sull'$aws/things/thingName/shadow/name/shadowName/update/deltaargomento con un documento /delta response state document shadow per tutti i dispositivi o i client che lo sottoscrivono.

  3. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e Documenti sulla risposta di errore come corpo del messaggio di risposta.

Quando il dispositivo riceve lo stato /desired sull'argomento /update/delta, apporta le modifiche desiderate nel dispositivo. Invia quindi un messaggio all'argomento /update per segnalare lo stato corrente alla copia shadow.

Aggiornamento di una copia shadow quando un dispositivo segnala lo stato corrente

Quando un dispositivo segnala lo stato corrente alla copia shadow utilizzando il protocollo MQTT

  1. Il dispositivo deve sottoscrivere questi argomenti MQTT prima di aggiornare la copia 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. Il dispositivo segnala lo stato corrente pubblicando un messaggio nell'argomento $aws/things/thingName/shadow/name/shadowName/update che segnala lo stato corrente, come in questo esempio.

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

  3. Se AWS IoT accetta l'aggiornamento, pubblica un messaggio $aws/things/thingName/shadow/name/shadowName/update/accepted sugli argomenti con un documento /accepted response state document ombra.

  4. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/update/rejectedargomento con un documento Documenti sulla risposta di errore ombra che descrive l'errore.

Quando un dispositivo segnala lo stato corrente alla copia shadow utilizzando l'API

  1. Il dispositivo chiama l'API UpdateThingShadow con un documento di stato Documento sullo stato della richiesta come corpo del messaggio.

  2. Se la richiesta era valida, AWS IoT aggiorna lo shadow e restituisce un codice di risposta di successo HTTP con un documento /accepted response state document shadow come corpo del messaggio di risposta.

    AWS IoT pubblicherà anche un messaggio MQTT sull'$aws/things/thingName/shadow/name/shadowName/update/deltaargomento con un documento /delta response state document shadow per tutti i dispositivi o i client che lo sottoscrivono.

  3. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e Documenti sulla risposta di errore come corpo del messaggio di risposta.

Blocco ottimistico

Puoi usare la versione del documento sullo stato per assicurarti di aggiornare la versione più recente di un documento di una copia shadow di un dispositivo. Quando fornisci una versione con una richiesta di aggiornamento, il servizio rifiuta la richiesta con un codice di risposta di conflitto HTTP 409 se la versione corrente del documento sullo stato non corrisponde alla versione fornita. Il codice di risposta ai conflitti può comparire anche su qualsiasi API che modifica ThingShadow, incluso DeleteThingShadow.

Per esempio:

Documento iniziale:

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

Aggiornamento: (la versione non corrisponde, questa richiesta verrà rifiutata)

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

Risultato:

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

Aggiornamento: (la versione corrisponde, la richiesta verrà accettata)

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

Stato finale:

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

Recupero di un documento di una copia shadow

È possibile recuperare un documento shadow utilizzando l'API GetThingShadow o effettuando la sottoscrizione o la pubblicazione sull'argomento /get. In questo modo viene recuperato un documento shadow completo, incluso qualsiasi delta tra gli stati desired e reported. La procedura per questa attività è la stessa se la richiesta viene effettuata da un dispositivo o da un client.

Per recuperare un documento shadow utilizzando il protocollo MQTT

  1. Il dispositivo o il client devono sottoscrivere questi argomenti MQTT prima di aggiornare la copia shadow:

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

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

  2. Il dispositivo o il client pubblica un messaggio nell'argomento $aws/things/thingName/shadow/name/shadowName/get con un corpo del messaggio vuoto.

  3. Se la richiesta ha esito positivo, AWS IoT pubblica un messaggio nell'$aws/things/thingName/shadow/name/shadowName/get/acceptedargomento con a /accepted response state document nel corpo del messaggio.

  4. Se la richiesta non era valida, AWS IoT pubblica un messaggio sull'$aws/things/thingName/shadow/name/shadowName/get/rejectedargomento con un Documenti sulla risposta di errore nel corpo del messaggio.

Per recuperare un documento shadow utilizzando un'API REST

  1. Il dispositivo o il client chiama l'API GetThingShadow con un corpo del messaggio vuoto.

  2. Se la richiesta è valida, AWS IoT restituisce un codice di risposta di successo HTTP con un documento /accepted response state document ombra come corpo del messaggio di risposta.

  3. Se la richiesta non è valida, AWS IoT restituisce un codice di risposta agli errori HTTP e Documenti sulla risposta di errore come corpo del messaggio di risposta.

Eliminazione di dati shadow

Esistono due modi per eliminare i dati shadow: è possibile eliminare proprietà specifiche nel documento shadow o eliminare completamente la copia shadow.

  • Per eliminare proprietà specifiche da una copia shadow, aggiornare la copia shadow. Impostare tuttavia il valore delle proprietà che si desidera eliminare su null. I campi con un valore pari a null vengono rimossi dal documento shadow.

  • Per eliminare l'intera copia shadow, utilizzare l'API DeleteThingShadow o pubblicare nell'argomento /delete.

Nota

L'eliminazione di un'ombra non comporta il ripristino del relativo numero di versione su zero in una sola volta. Verrà azzerato dopo 48 ore.

Eliminazione di una proprietà da un documento shadow

Per eliminare una proprietà da una copia shadow utilizzando il protocollo MQTT

  1. Il dispositivo o il client deve disporre di un documento shadow corrente in modo che possa identificare le proprietà da modificare. Consulta Recupero di un documento di una copia shadow per informazioni su come ottenere il documento shadow corrente.

  2. Il dispositivo o il client sottoscrive i seguenti argomenti MQTT:

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

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

  3. Il dispositivo o il client pubblica un argomento di richiesta $aws/things/thingName/shadow/name/shadowName/update con un documento di stato che assegna valori null alle proprietà della copia shadow da eliminare. Solo le proprietà da modificare devono essere incluse nel documento. Questo è un esempio di documento che elimina la proprietà engine.

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

  4. Se la richiesta di aggiornamento è valida, AWS IoT elimina le proprietà specificate nell'ombra e pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/update/acceptedargomento con un documento /accepted response state document ombra nel corpo del messaggio.

  5. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/update/rejectedargomento con un documento Documenti sulla risposta di errore shadow che descrive l'errore.

Per eliminare una proprietà da una copia shadow utilizzando l'API REST

  1. Il dispositivo o il client chiama l'API UpdateThingShadow con un Documento sullo stato della richiesta che assegna valori null alle proprietà della copia shadow da eliminare. Includere solo le proprietà che si desidera eliminare nel documento. Questo è un esempio di documento che elimina la proprietà engine.

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

  2. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP e un documento /accepted response state document shadow come corpo del messaggio di risposta.

  3. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e Documenti sulla risposta di errore come corpo del messaggio di risposta.

Eliminazione di una copia shadow

Di seguito sono riportate alcune considerazioni sull'eliminazione della copia shadow di un dispositivo.

  • L'impostazione dello stato shadow del dispositivo su null non elimina la copia shadow. La versione shadow verrà incrementata al successivo aggiornamento.

  • Eliminando una copia shadow di un dispositivo non si elimina l'oggetto. Eliminando un oggetto non si elimina la copia shadow del dispositivo corrispondente.

  • L'eliminazione di un'ombra non comporta il ripristino del relativo numero di versione su zero in una sola volta. Verrà azzerato dopo 48 ore.

Per eliminare una copia shadow utilizzando il protocollo MQTT

  1. Il dispositivo o il client sottoscrive i seguenti argomenti MQTT:

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

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

  2. Il dispositivo o il client pubblica un $aws/things/thingName/shadow/name/shadowName/delete con un buffer di messaggi vuoto.

  3. Se la richiesta di eliminazione è valida, AWS IoT elimina l'ombra e pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/delete/acceptedargomento e un documento /accepted response state document shadow abbreviato nel corpo del messaggio. Questo è un esempio del messaggio di eliminazione accettato:

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

  4. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'$aws/things/thingName/shadow/name/shadowName/delete/rejectedargomento con un documento Documenti sulla risposta di errore ombra che descrive l'errore.

Per eliminare una copia shadow utilizzando l'API REST

  1. Il dispositivo o il client chiama l'API DeleteThingShadow con un buffer di messaggi vuoto.

  2. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP /accepted response state document e un documento /accepted response state document shadow abbreviato nel corpo del messaggio. Questo è un esempio del messaggio di eliminazione accettato:

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

  3. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e Documenti sulla risposta di errore come corpo del messaggio di risposta.