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à.
Documenti del servizio Device Shadow
Il servizio Device Shadow rispetta tutte le regole della specifica JSON. Valori, oggetti e matrici sono archiviati nel documento della copia shadow del dispositivo.
Indice
Esempi di documenti shadow
Il servizio Device Shadow usa i documenti seguenti nelle operazioni UPDATE, GET e DELETE con l'API REST o i messaggi di pubblicazione/sottoscrizione MQTT.
Esempi
Documento sullo stato della richiesta
Un documento sullo stato della richiesta ha il seguente formato:
{ "state": { "desired": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "reported": { "attribute1":integer1, "attribute2": "string1", ... "attributeN":boolean1} }, "clientToken": "token", "version":version}
-
state– Gli aggiornamenti interessano solo i campi specificati. In genere, si utilizzerà la proprietàdesiredoreported, ma non entrambe nella stessa richiesta.-
desired– Le proprietà dello stato e i valori richiesti per essere aggiornati nel dispositivo. -
reported– Le proprietà dello stato e i valori riportati dal dispositivo.
-
-
clientToken– Se usato, consente di abbinare la richiesta e la risposta corrispondente dal token client. -
version– Se usato, il servizio Device Shadow elabora l'aggiornamento solo se la versione specificata corrisponde alla versione più recente.
Documenti sullo stato della risposta
I documenti relativi allo stato della risposta hanno il seguente formato a seconda del tipo di risposta.
/accepted response state document
{ "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}
/delta response state document
{ "state": { "attribute1":integer2, "attribute2": "string2", ... "attributeN":boolean2}, "metadata": { "attribute1": { "timestamp":timestamp}, "attribute2": { "timestamp":timestamp}, ... "attributeN": { "timestamp":timestamp} }, "timestamp":timestamp, "clientToken": "token", "version":version}
/documents response state document
{ "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" }
Proprietà del documento dello stato della risposta
-
previous– Dopo un aggiornamento riuscito, contiene ilstatedell'oggetto prima dell'aggiornamento. -
current– Dopo un aggiornamento riuscito, contiene ilstatedell'oggetto dopo l'aggiornamento. -
state-
reported– Presente solo se un oggetto ha segnalato dati nella sezionereportede contiene solo campi presenti nel documento sullo stato della richiesta. -
desired– Presente solo se un dispositivo ha segnalato dati nella sezionedesirede contiene solo campi che erano presenti nel documento sullo stato della richiesta. -
delta– Presente solo se i datidesireddifferiscono dai dati correnti della shadowreported.
-
-
metadata- Contiene i timestamp per ogni attributo nelle sezionidesiredereported, per permettere di determinare quando lo stato è stato aggiornato. -
timestamp— Data e ora dell'epoca in cui è stata generata la risposta. AWS IoT -
clientToken– Presente solo se è stato usato un token client in fase di pubblicazione di contenuto JSON valido nell'argomento/update. -
version– Versione corrente del documento per la copia shadow del dispositivo condivisa in AWS IoT. Il valore viene aumentato di uno rispetto alla versione precedente del documento.
Documenti sulla risposta di errore
Un documento sulla risposta agli errori ha il seguente formato:
{ "code":error-code, "message": "error-message", "timestamp":timestamp, "clientToken": "token" }
-
code– Codice di risposta HTTP che indica il tipo di errore. -
message– Messaggio di testo che fornisce ulteriori informazioni. -
timestamp— La data e l'ora in cui è stata generata AWS IoT la risposta. Questa proprietà non è presente in tutti i documenti di risposta agli errori. -
clientToken– Presente solo se è stato usato un token client in un messaggio pubblicato.
Per ulteriori informazioni, consulta Messaggi di errore Device Shadow.
Documento di risposta elenco nomi shadow
Un documento di risposta elenco nomi shadow ha il seguente formato:
{ "results": [ "shadowName-1", "shadowName-2", "shadowName-3", "shadowName-n" ], "nextToken": "nextToken", "timestamp":timestamp}
-
results– L'array di nomi shadow. -
nextToken– Il valore del token da utilizzare nelle richieste di paging per ottenere la pagina successiva nella sequenza. Questa proprietà non è presente quando non ci sono più nomi shadow da restituire. -
timestamp— La data e l'ora in cui è stata generata la risposta AWS IoT.
Proprietà del documento
Un documento di una copia shadow di un dispositivo ha le proprietà seguenti:
state-
desired-
Lo stato desiderato del dispositivo. Le applicazioni possono scrivere su questa parte del documento per aggiornare lo stato di un dispositivo senza doversi connettere direttamente a esso.
reported-
Lo stato segnalato del dispositivo. I dispositivi scrivono in questa parte del documento per segnalare il proprio nuovo stato. Le app leggono questa parte del documento per determinare l'ultimo stato segnalato del dispositivo.
metadata-
Informazioni sui dati archiviati nella sezione
statedel documento. Le informazioni includono i timestamp, in base all'epoca (Unix epoch), per ogni attributo nella sezionestate, che permettono di determinare quando gli attributi sono stati aggiornati.Nota
I metadati non contribuiscono alle dimensioni del documento per le restrizioni dei servizi o i prezzi. Per ulteriori informazioni, consulta la pagina relativa alle restrizioni dei servizi AWS IoT.
timestamp-
Indica da quando è stato inviato il messaggio AWS IoT. Utilizzando il timestamp nel messaggio e i timestamp per i singoli attributi della sezione
desiredoreported, un dispositivo può determinare l'età di una proprietà, anche se il dispositivo non dispone di un orologio interno. clientToken-
Stringa univoca del dispositivo che permette di associare le risposte alle richieste in un ambiente MQTT.
version-
Versione del documento. Ogni volta che il documento viene aggiornato, questo numero di versione viene incrementato. Questa proprietà viene usata per garantire che la versione del documento che viene aggiornata sia la più recente.
Per ulteriori informazioni, consulta Esempi di documenti shadow.
Stato delta
Lo stato delta è un tipo di stato virtuale che contiene la differenza tra gli stati desired e reported. I campi nella sezione desired che non sono presenti nella sezione reported sono inclusi nel delta. I campi nella sezione reported che non sono presenti nella sezione desired non sono inclusi nel delta. Il delta contiene i metadata e i relativi valori corrispondono ai metadata nel campo desired. Ad esempio:
{ "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 } }
Quando gli oggetti nidificati differiscono, il delta contiene il percorso fino alla root.
{ "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 }
Il servizio Device Shadow calcola il delta scorrendo ogni campo con stato desired e confrontandolo con lo stato reported.
Le matrici vengono trattate come valori. Se una matrice nella sezione desired non corrisponde alla matrice nella sezione reported, l'intera matrice della sezione desired viene copiata nel delta.
Controllo delle versioni documenti shadow
Il servizio Device Shadow supporta il controllo delle versioni su ogni messaggio di aggiornamento, sia richiesta che risposta. Ciò significa che con ogni aggiornamento di una copia shadow, la versione del documento JSON viene incrementata. Ciò offre due possibilità:
-
Un client può ricevere un errore se tenta di sovrascrivere una copia shadow usando un numero di versione precedente. Il client viene informato che è necessaria una nuova sincronizzazione prima dell'aggiornamento di una copia shadow di un dispositivo.
-
Un client può decidere di non agire su un messaggio ricevuto se il messaggio ha una versione più bassa rispetto a quella archiviata dal client.
Un client può ignorare la corrispondenza di versione non includendo una versione nel documento shadow.
I token client nei documenti shadow
È possibile usare un token client con la messaggistica basata su MQTT per verificare che lo stesso token client sia incluso in una richiesta e in una risposta a una richiesta. In questo modo la risposta e la richiesta vengono associate.
Nota
Il token client non può superare i 64 byte. Un token client di dimensioni superiori a 64 byte causerà una risposta 400 (Richiesta non valida) e un messaggio di errore Token client non valido.
Proprietà documento shadow vuote
Le proprietà reported e desired in un documento shadow possono essere vuote o omesse quando non si applicano allo stato shadow corrente. Ad esempio, un documento shadow contiene una proprietà desired solo se ha uno stato desiderato. Di seguito è riportato un esempio valido di documento di stato senza proprietà desired:
{ "reported" : { "temp": 55 } }
La proprietà reported può anche essere vuota, ad esempio se la copia shadow non è stata aggiornata dal dispositivo:
{ "desired" : { "color" : "RED" } }
Se un aggiornamento fa sì che le proprietà desired o reported diventino nulle, viene rimosso dal documento. Di seguito viene illustrato come rimuovere la proprietà desired impostandola su null. È possibile eseguire questa operazione quando un dispositivo aggiorna il suo stato, ad esempio.
{ "state": { "reported": { "color": "red" }, "desired": null } }
Un documento shadow può inoltre non avere proprietà desired o reported, rendendo il documento shadow vuoto. Questo è un esempio di documento shadow vuoto ma valido.
{ }
Valori di array nei documenti shadow
Le copie shadow supportano le matrici, ma le trattano come normali valori, pertanto un aggiornamento di una matrice sostituisce l'intera matrice. Non è possibile aggiornare una parte di una matrice.
Stato iniziale:
{ "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } }
Aggiornamento:
{ "desired" : { "colors" : ["RED"] } }
Stato finale:
{ "desired" : { "colors" : ["RED"] } }
Le matrici non possono contenere valori null. La matrice seguente, ad esempio, non è valida e verrà rifiutata.
{ "desired" : { "colors" : [ null, "RED", "GREEN" ] } }
