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 MQTT abbonati con la differenza tra lo stato desired e lo reported stato. 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 MQTTe una serie REST API di HTTPS protocolli per interagire con le ombre. AWS IoT fornisce una serie di argomenti riservati di richiesta e risposta per le azioni di MQTT pubblicazione e sottoscrizione. I dispositivi e le app devono sottoscrivere gli argomenti di risposta prima di pubblicare su un argomento di richiesta per informazioni sulla modalità di AWS IoT gestione della richiesta. Per ulteriori informazioni, consulta MQTTArgomenti Device Shadow e Device Shadow REST API.

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 un'ombra utilizzando UpdateThingShadow API o pubblicando sull'/updateargomento. 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 un cambio di stato in un'ombra utilizzando il MQTT protocollo

  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 MQTT argomenti:

    • $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 un cambiamento di stato in un'ombra utilizzando il API

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

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

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

  3. Se la richiesta non era valida, AWS IoT restituisce un codice HTTP di risposta all'errore 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 il suo stato attuale all'ombra utilizzando il MQTT protocollo

  1. Il dispositivo deve sottoscrivere questi MQTT argomenti prima di aggiornare lo 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 il suo stato attuale all'ombra utilizzando API

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

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

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

  3. Se la richiesta non era valida, AWS IoT restituisce un codice HTTP di risposta all'errore 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 si fornisce una versione con una richiesta di aggiornamento, il servizio rifiuta la richiesta con un codice di risposta ai conflitti HTTP 409 se la versione corrente del documento di stato non corrisponde alla versione fornita. Il codice di risposta ai conflitti può comparire anche su qualsiasi oggetto di modificaThingShadow, tra API cui. 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 ombra utilizzando GetThingShadow API o sottoscrivendo e pubblicando l'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 ombra utilizzando il protocollo MQTT

  1. Il dispositivo o il client devono sottoscrivere questi MQTT argomenti prima di aggiornare lo 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 sull'$aws/things/thingName/shadow/name/shadowName/get/acceptedargomento con un /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 ombra utilizzando un REST API

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

  2. Se la richiesta è valida, AWS IoT restituisce un codice di risposta HTTP riuscita 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 HTTP di risposta all'errore an 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 ombra, usa DeleteThingShadow API o pubblica sull'/deleteargomento.

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 un'ombra 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 MQTT argomenti:

    • $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 un'ombra utilizzando REST API

  1. Il dispositivo o il client chiama il comando UpdateThingShadow API with a Documento sullo stato della richiesta che assegna null valori alle proprietà dell'ombra 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 HTTP riuscita e un documento /accepted response state document ombra come corpo del messaggio di risposta.

  3. Se la richiesta non era valida, AWS IoT restituisce un codice HTTP di risposta all'errore 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 numero di versione su zero contemporaneamente. Verrà azzerato dopo 48 ore.

Per eliminare un'ombra utilizzando il protocollo MQTT

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

    • $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 lo shadow 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 un'ombra utilizzando il REST API

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

  2. Se la richiesta era valida, AWS IoT restituisce un codice di risposta HTTP riuscita /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 HTTP di risposta all'errore an Documenti sulla risposta di errore come corpo del messaggio di risposta.