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à.
# AWS IoT Servizio Device Shadow
Il servizio AWS IoT Device Shadow aggiunge ombre agli oggetti AWS IoT oggetto. Le ombre possono rendere disponibile lo stato di un dispositivo ad app e altri servizi, indipendentemente dal fatto che il dispositivo sia connesso AWS IoT o meno. AWS IoT gli oggetti thing possono avere più ombre denominate in modo che la soluzione IoT abbia più opzioni per connettere i dispositivi ad altre app e servizi.
AWS IoT gli oggetti thing non hanno ombre finché non vengono creati esplicitamente. Le ombre possono essere create, aggiornate ed eliminate utilizzando la console. AWS IoT Dispositivi, altri client web e servizi possono creare, aggiornare ed eliminare copie shadow utilizzando MQTT e gli [argomenti MQTT riservati](reserved-topics.md#reserved-topics-shadow), HTTP utilizzando l'[API REST Device Shadow](device-shadow-rest-api.md) e [AWS CLI per AWS IoT](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/index.html). Poiché le ombre vengono archiviate AWS nel cloud, possono raccogliere e segnalare dati sullo stato del dispositivo da app e altri servizi cloud, indipendentemente dal fatto che il dispositivo sia connesso o meno.
## Uso delle copie shadow
Le copie shadow forniscono uno store dati affidabile per dispositivi, app e altri servizi cloud per condividere i dati. Consentono a dispositivi, app e altri servizi cloud di connettersi e disconnettersi senza perdere lo stato di un dispositivo.
Mentre i dispositivi, le app e gli altri servizi cloud sono connessi AWS IoT, possono accedere e controllare lo stato corrente di un dispositivo attraverso le sue ombre. Ad esempio, un'app può richiedere una modifica dello stato di un dispositivo aggiornando un'ombra. AWS IoT pubblica un messaggio che indica la modifica apportata al dispositivo. Il dispositivo riceve questo messaggio, aggiorna lo stato in modo che corrisponda e pubblica un messaggio con lo stato aggiornato. Il servizio Device Shadow riflette questo stato aggiornato nella copia shadow corrispondente. L'app può sottoscrivere l'aggiornamento della copia shadow oppure può interrogare la copia shadow per il suo stato corrente.
Quando un dispositivo va offline, un'app può continuare a comunicare con le ombre del dispositivo AWS IoT e con le ombre del dispositivo. Quando il dispositivo si riconnette, riceve lo stato corrente delle sue copie shadow in modo che possa aggiornarne lo stato affinché corrisponda a quello delle sue copie shadow, quindi pubblicare un messaggio con il relativo stato aggiornato. Allo stesso modo, quando un'app non è in linea e lo stato del dispositivo cambia mentre è offline, il dispositivo mantiene aggiornata la copia shadow in modo che l'app possa interrogare le copie shadow per il suo stato corrente quando si riconnette.
Se i tuoi dispositivi sono spesso offline e desideri configurarli in modo che ricevano messaggi delta dopo la riconnessione, puoi utilizzare la funzione di sessione persistente. Per ulteriori informazioni sul periodo di scadenza della sessione persistente, consulta la sezione [Periodo di scadenza della sessione persistente](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits).
### Scelta di utilizzare copie shadow con nome o senza nome
Il servizio Device Shadow supporta le copie shadow con nome e senza nome o classiche. Un oggetto può avere più copie shadow con nome e non più di una copia shadow senza nome. L'oggetto può anche avere una copia shadow con nome riservata, che funziona in modo simile a una copia shadow con nome, tranne che non è possibile aggiornare il nome. Per ulteriori informazioni, consulta [Copia shadow con nome riservata](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
Un oggetto può avere copie shadow con nome e senza nome allo stesso tempo; tuttavia, l'API utilizzata per accedere a ciascuna è leggermente diversa, quindi sarebbe opportuno stabilire quale tipo di copia shadow funzionerebbe meglio per la soluzione e utilizzare solo quel tipo. Per ulteriori informazioni sull'API per accedere alle copie shadow, consulta [Argomenti copie shadow](reserved-topics.md#reserved-topics-shadow).
Con le copie shadow con nome, è possibile creare diverse viste dello stato di un oggetto. Ad esempio, è possibile dividere un oggetto con molte proprietà in copie shadow con gruppi logici di proprietà, ognuno identificato dal nome shadow. È inoltre possibile limitare l'accesso alle proprietà raggruppandole in copie shadow diverse e utilizzando le policy per controllare l'accesso. Per ulteriori informazioni sulle policy da utilizzare con le device shadow, consulta [Operazioni, risorse e chiavi di condizione per AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html) e [Policy AWS IoT Core](https://docs.aws.amazon.com//iot/latest/developerguide/iot-policies.html).
Le copie shadow classiche senza nome sono più semplici, ma un po' più limitate rispetto alle copie shadow con nome. Ogni AWS IoT oggetto può avere solo un'ombra senza nome. Se si prevede che la soluzione IoT abbia una necessità limitata di dati di copie shadow, questo potrebbe essere il modo in cui iniziare a utilizzare le copie shadow. Tuttavia, se si pensa di voler aggiungere altre copie shadow in futuro, prendere in considerazione l'utilizzo di copie shadow con nome fin dall'inizio.
L'indicizzazione del parco istanze supporta copie shadow senza nome e con nome in modo diverso. Per ulteriori informazioni, consulta [Gestione dell'indicizzazione del parco istanze](managing-fleet-index.md).
### Accesso alle copie shadow
Ogni copia shadow dispone di un [argomento MQTT](reserved-topics.md#reserved-topics-shadow) e di un [URL HTTP](device-shadow-rest-api.md) riservato che supporta le operazioni `get`, `update` e `delete` sulla copia shadow.
Le copie shadow utilizzano i [documenti shadow JSON](device-shadow-document.md) per archiviare e recuperare i dati. Il documento di una copia shadow contiene una proprietà di stato che descrive questi aspetti dello stato del dispositivo:
+ `desired`
Le app specificano gli stati desiderati delle proprietà del dispositivo aggiornando l'oggetto `desired`.
+ `reported`
I dispositivi segnalano il loro stato corrente nell'oggetto `reported`.
+ `delta`
AWS IoT riporta le differenze tra lo stato desiderato e quello riportato nell'`delta`oggetto.
I dati archiviati in una copia shadow sono determinati dalla proprietà stato del corpo del messaggio dell'operazione di aggiornamento. Le operazioni di aggiornamento successive possono modificare i valori di un oggetto dati esistente, nonché aggiungere ed eliminare chiavi e altri elementi nell'oggetto stato della copia shadow. Per ulteriori informazioni sull'accesso alle copie shadow, consulta [Utilizzo delle copie shadow nei dispositivi](device-shadow-comms-device.md) e [Utilizzo delle copie shadow in app e servizi](device-shadow-comms-app.md).
**Importante**
L'autorizzazione a effettuare richieste di aggiornamento deve essere limitata alle app e ai dispositivi attendibili. Ciò impedisce che la proprietà stato della copia shadow venga modificata in modo imprevisto; in caso contrario, i dispositivi e le app che utilizzano la copia shadow devono essere progettati in modo che le chiavi nella proprietà stato vengano modificate.
### Utilizzo delle copie shadow in dispositivi, app e altri servizi cloud
L'utilizzo delle copie shadow in dispositivi, app e altri servizi cloud richiede coerenza e coordinamento. Il servizio AWS IoT Device Shadow memorizza lo stato shadow, invia messaggi quando lo stato shadow cambia e risponde ai messaggi che ne modificano lo stato. I dispositivi, le app e altri servizi cloud nella soluzione IoT devono gestirne lo stato e mantenerlo coerente con lo stato della copia shadow del dispositivo.
I dati dello stato della copia shadow sono dinamici e possono essere modificati da dispositivi, app e altri servizi cloud con autorizzazione per accedere alla copia shadow. Per questo motivo, è importante considerare come ogni dispositivo, app e altro servizio cloud interagiranno con la copia shadow. Ad esempio:
+ *I dispositivi* devono scrivere solo sulla proprietà `reported` dello stato shadow quando comunicano i dati di stato alla copia shadow.
+ *Le app e gli altri servizi cloud* devono scrivere solo nella proprietà `desired` quando comunicano le richieste di modifica dello stato al dispositivo tramite la copia shadow.
**Importante**
I dati contenuti in un oggetto dati shadow sono indipendenti da quelli di altre copie shadow e altre proprietà oggetto, ad esempio gli attributi di un oggetto e il contenuto dei messaggi MQTT che il dispositivo di un oggetto potrebbe pubblicare. Un dispositivo può, tuttavia, segnalare gli stessi dati in diversi argomenti MQTT e copie shadow, se necessario.
Un dispositivo che supporta più copie shadow deve mantenere la coerenza dei dati segnalati nelle diverse copie shadow.
### Ordine dei messaggi
Non è garantito che i messaggi del AWS IoT servizio arrivino al dispositivo in un ordine specifico. Lo scenario seguente mostra ciò che accade in questo caso.
Documento sullo stato iniziale:
```
{
"state": {
"reported": {
"color": "blue"
}
},
"version": 9,
"timestamp": 123456776
}
```
Aggiornamento 1:
```
{
"state": {
"desired": {
"color": "RED"
}
},
"version": 10,
"timestamp": 123456777
}
```
Aggiornamento 2:
```
{
"state": {
"desired": {
"color": "GREEN"
}
},
"version": 11,
"timestamp": 123456778
}
```
Documento sullo stato finale:
```
{
"state": {
"reported": {
"color": "GREEN"
}
},
"version": 12,
"timestamp": 123456779
}
```
Il risultato è costituito da due messaggi delta:
```
{
"state": {
"color": "RED"
},
"version": 11,
"timestamp": 123456778
}
```
```
{
"state": {
"color": "GREEN"
},
"version": 12,
"timestamp": 123456779
}
```
Il dispositivo potrebbe ricevere questi messaggi non in ordine. Poiché lo stato nei messaggi è cumulativo, un dispositivo può scartare senza problemi qualsiasi messaggio contenente un numero di versione precedente a quello monitorato. Se il dispositivo riceve il delta per la versione 12 prima della versione 11, può scartare senza problemi il messaggio con la versione 11.
### Taglio dei messaggi delle copie shadow
Per ridurre le dimensioni dei messaggi delle copie shadow inviati al dispositivo, definisci una regola che seleziona solo i campi necessari per il dispositivo, quindi ripubblica il messaggio in un argomento MQTT in cui il dispositivo è in ascolto.
La regola viene specificata in formato JSON e dovrebbe essere simile a quanto segue:
```
{
"sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'",
"ruleDisabled": false,
"actions": [
{
"republish": {
"topic": "${topic(3)}/delta",
"roleArn": "arn:aws:iam:123456789012:role/my-iot-role"
}
}
]
}
```
L'istruzione SELECT determina i campi del messaggio che verranno ripubblicati nell'argomento specificato. Il carattere jolly "\$1" permette di trovare la corrispondenza con tutti i nomi delle copie shadow. La regola specifica che tutti i messaggi corrispondenti devono essere ripubblicati nell'argomento specificato. In questo caso, la funzione `"topic()"` viene usata per specificare l'argomento su cui ripetere la pubblicazione. `topic(3)` restituisce il nome nell'oggetto nell'argomento originale. Per ulteriori informazioni sulla creazione di regole, consulta [Regole per AWS IoT](iot-rules.md).
# Utilizzo delle copie shadow nei dispositivi
Questa sezione descrive le comunicazioni dei dispositivi con le ombre utilizzando i messaggi MQTT, il metodo preferito dai dispositivi per comunicare con il servizio AWS IoT Device Shadow.
Le comunicazioni shadow emulano un request/response modello che utilizza il modello di comunicazione pubblica/sottoscrizione di MQTT. Ogni operazione copia shadow è costituita da un argomento di richiesta, un argomento di risposta riuscita (`accepted`) e un argomento di risposta agli errori (`rejected`).
Se si desidera che app e servizi siano in grado di determinare se un dispositivo è connesso, consulta [Rilevamento della connessione di un dispositivo](device-shadow-comms-app.md#thing-connection).
**Importante**
Poiché MQTT utilizza un modello di publish/subscribe comunicazione, è necessario sottoscrivere gli argomenti di risposta *prima* di pubblicare un argomento di richiesta. In caso contrario, non riceverai la risposta alla richiesta pubblicata.
Se usi un [SDK per dispositivi AWS IoT](iot-sdks.md)per chiamare il servizio Device Shadow APIs, questo viene gestito automaticamente.
Gli esempi di questa sezione utilizzano una forma abbreviata dell'argomento in cui *ShadowTopicPrefix* possono fare riferimento a un'ombra con nome o senza nome, come descritto in questa tabella.
Le copie shadow possono essere con nome o senza nome (classiche). Gli argomenti utilizzati da ciascuno differiscono solo nel prefisso dell'argomento. Questa tabella mostra il prefisso dell'argomento utilizzato da ogni tipo di copia shadow.
| *ShadowTopicPrefix* value | Tipo di copia shadow |
| --- | --- |
| \$1aws/things/thingName/shadow | Copia shadow senza nome (classica) |
| \$1aws/things/thingName/shadow/name/shadowName | Copia shadow con nome |
**Importante**
Assicurati che l'uso delle copie shadow da parte dell'app o del servizio sia coerente e supportato dalle implementazioni corrispondenti nei tuoi dispositivi. Considera ad esempio, come vengono create, aggiornate ed eliminate le copie shadow. Considera inoltre come vengono gestiti gli aggiornamenti nel dispositivo e nelle app o nei servizi che accedono al dispositivo tramite una copia shadow. La progettazione dovrebbe chiarire il modo in cui lo stato del dispositivo viene aggiornato e segnalato e il modo in cui le app e i servizi interagiscono con il dispositivo e le relative copie shadow.
Per creare un argomento completo, selezionare `ShadowTopicPrefix` per il tipo di copia shadow a cui si desidera fare riferimento, sostituire `thingName` e `shadowName` se applicabile, con i relativi valori corrispondenti, quindi aggiungerlo con lo stub dell'argomento, come illustrato nella tabella seguente. Ricorda che gli argomenti prevedono una distinzione tra lettere maiuscole e minuscole.
Consulta [Argomenti copie shadow](reserved-topics.md#reserved-topics-shadow) per ulteriori informazioni sugli argomenti riservati per le copie shadow.
## Inizializzazione del dispositivo alla prima connessione a AWS IoT
Una volta effettuata la registrazione con AWS IoT, il dispositivo dovrebbe sottoscrivere questi messaggi MQTT per gli shadows che supporta.
| Topic | Significato | Operazione che un dispositivo dovrebbe intraprendere quando riceve questo argomento |
| --- | --- | --- |
| `ShadowTopicPrefix/delete/accepted` | La `delete` richiesta è stata accettata e l'ombra è stata AWS IoT eliminata. | Le operazioni necessarie per gestire la copia shadow eliminata, ad esempio interrompere la pubblicazione degli aggiornamenti. |
| `ShadowTopicPrefix/delete/rejected` | La `delete` richiesta è stata rifiutata AWS IoT e l'ombra non è stata eliminata. Il corpo del messaggio contiene le informazioni sull'errore. | Rispondere al messaggio di errore nel corpo del messaggio. |
| `ShadowTopicPrefix/get/accepted` | La `get` richiesta è stata accettata da AWS IoT e il corpo del messaggio contiene il documento shadow corrente. | Le operazioni necessarie per elaborare il documento di stato nel corpo del messaggio. |
| `ShadowTopicPrefix/get/rejected` | La `get` richiesta è stata rifiutata da AWS IoT e il corpo del messaggio contiene le informazioni sull'errore. | Rispondere al messaggio di errore nel corpo del messaggio. |
| `ShadowTopicPrefix/update/accepted` | La `update` richiesta è stata accettata da AWS IoT e il corpo del messaggio contiene il documento shadow corrente. | Verificare che i dati aggiornati nel corpo del messaggio corrispondano allo stato del dispositivo. |
| `ShadowTopicPrefix/update/rejected` | La `update` richiesta è stata rifiutata da AWS IoT e il corpo del messaggio contiene le informazioni sull'errore. | Rispondere al messaggio di errore nel corpo del messaggio. |
| `ShadowTopicPrefix/update/delta` | Il documento ombra è stato aggiornato tramite una richiesta a AWS IoT e il corpo del messaggio contiene le modifiche richieste. | Aggiornare lo stato del dispositivo in modo che corrisponda allo stato desiderato nel corpo del messaggio. |
| `ShadowTopicPrefix/update/documents` | Recentemente è stato completato un aggiornamento alla copia shadow e il corpo del messaggio contiene il documento shadow corrente. | Verificare che lo stato aggiornato nel corpo del messaggio corrisponda allo stato del dispositivo. |
Dopo aver sottoscritto i messaggi nella tabella precedente per ogni copia shadow, il dispositivo deve verificare se le copie shadow supportate sono già state create pubblicando un argomento `/get` per ogni copia shadow. Se viene ricevuto un messaggio `/get/accepted`, il corpo del messaggio contiene il documento shadow, che il dispositivo può utilizzare per inizializzare il suo stato. Se viene ricevuto un messaggio `/get/rejected`, la copia shadow deve essere creata pubblicando un messaggio `/update` con lo stato corrente del dispositivo.
Supponiamo ad esempio che tu abbia un oggetto `My_IoT_Thing` che non ha copie shadow classiche o con nome. Se ora pubblichi una richiesta `/get` sull'argomento riservato `$aws/things/My_IoT_Thing/shadow/get`, restituisce un errore sull'argomento `$aws/things/My_IoT_Thing/shadow/get/rejected` perché l'oggetto non ha copie shadow. Per risolvere questo errore, prima pubblica un messaggio `/update` utilizzando l'argomento `$aws/things/My_IoT_Thing/shadow/update` con lo stato attuale del dispositivo, ad esempio il seguente payload.
```
{
"state": {
"reported": {
"welcome": "aws-iot",
"color": "yellow"
}
}
}
```
Ora viene creata una copia shadow classica per l'oggetto e il messaggio viene pubblicato sull'argomento `$aws/things/My_IoT_Thing/shadow/update/accepted`. Se pubblichi sull'argomento `$aws/things/My_IoT_Thing/shadow/get`, restituisce una risposta all'argomento `$aws/things/My_IoT_Thing/shadow/get/accepted` con lo stato del dispositivo.
Per le copie shadow con nome, innanzitutto devi creare la copia shadow con nome o pubblicare un aggiornamento con il nome della copia shadow prima di utilizzare la richiesta get. Ad esempio, per creare una copia shadow con nome `namedShadow1`, prima pubblica le informazioni sullo stato del dispositivo sull'argomento `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/update`. Per recuperare le informazioni sullo stato, utilizza la richiesta `/get` per la copia shadow con nome `$aws/things/My_IoT_Thing/shadow/name/namedShadow1/get`.
## Elaborazione dei messaggi mentre il dispositivo è connesso a AWS IoT
Mentre un dispositivo è connesso AWS IoT, può ricevere messaggi **/update/delta** e dovrebbe mantenere lo stato del dispositivo corrispondente ai cambiamenti nelle sue ombre mediante:
1. Lettura di tutti i messaggi **/update/delta** ricevuti e sincronizzazione dello stato del dispositivo in modo che corrisponda.
1. Pubblicazione di un messaggio **/update** con un corpo del messaggio `reported` con lo stato corrente del dispositivo, ogni volta che lo stato del dispositivo cambia.
Quando un dispositivo è connesso, dovrebbe pubblicare questi messaggi quando indicato.
| Indicazione | Topic | Carico utile |
| --- | --- | --- |
| Lo stato del dispositivo è cambiato. | `ShadowTopicPrefix/update` | Un documento shadow con la proprietà `reported`. |
| Il dispositivo potrebbe non essere sincronizzato con la copia shadow. | `ShadowTopicPrefix/get` | (vuoto) |
| Un'operazione sul dispositivo indica che una copia shadow non sarà più supportata dal dispositivo, ad esempio quando il dispositivo viene rimosso o sostituito. | `ShadowTopicPrefix/delete` | (vuoto) |
## Elaborazione dei messaggi quando il dispositivo si riconnette a AWS IoT
Quando un dispositivo con una o più ombre si connette AWS IoT, dovrebbe sincronizzare il suo stato con quello di tutte le ombre supportate mediante:
1. Lettura di tutti i messaggi **/update/delta** ricevuti e sincronizzazione dello stato del dispositivo in modo che corrisponda.
1. Pubblicazione di un messaggio **/update** con un corpo del messaggio `reported` con lo stato corrente del dispositivo.
# Utilizzo delle copie shadow in app e servizi
Questa sezione descrive come un'app o un servizio interagisce con il servizio AWS IoT Device Shadow. Questo esempio presuppone che l'app o il servizio interagisca solo con la copia shadow e, attraverso la copia shadow, con il dispositivo. Questo esempio non include alcuna operazione di gestione, ad esempio la creazione o l'eliminazione di copie shadow.
Questo esempio utilizza l'API REST del servizio AWS IoT Device Shadow per interagire con le ombre. A differenza dell'esempio utilizzato in[Utilizzo delle copie shadow nei dispositivi](device-shadow-comms-device.md), che utilizza un modello di publish/subscribe communications model, this example uses the request/response comunicazione dell'API REST. Ciò significa che l'app o il servizio devono effettuare una richiesta prima di poter ricevere una risposta da AWS IoT. Uno svantaggio di questo modello, tuttavia, è che non supporta le notifiche. Se l'app o il servizio richiedono notifiche tempestive sulle modifiche dello stato del dispositivo, prendi in considerazione i protocolli MQTT o MQTT su WSS, che supportano il modello di publish/subscribe comunicazione, come descritto in. [Utilizzo delle copie shadow nei dispositivi](device-shadow-comms-device.md)
**Importante**
Assicurati che l'uso delle copie shadow da parte dell'app o del servizio sia coerente e supportato dalle implementazioni corrispondenti nei tuoi dispositivi. Considera, ad esempio, come vengono create, aggiornate ed eliminate le copie shadow e come vengono gestiti gli aggiornamenti nel dispositivo e nelle app o nei servizi che accedono alla copia shadow. Il progetto deve specificare chiaramente come lo stato del dispositivo viene aggiornato e segnalato e come le app e i servizi interagiscono con il dispositivo e le relative copie shadow.
L'URL dell'API REST per una copia shadow denominata è:
```
https://endpoint/things/thingName/shadow?name=shadowName
```
e per una copia shadow senza nome è:
```
https://endpoint/things/thingName/shadow
```
dove:
endpoint
L'endpoint restituito dal comando CLI è:
```
aws iot describe-endpoint --endpoint-type IOT:Data-ATS
```
thingName
Il nome dell'oggetto a cui appartiene la copia shadow è:
shadowName
Il nome della copia shadow con nome. Questo parametro non viene utilizzato con copie shadow senza nome.
## Inizializzazione dell'app o del servizio durante la connessione a AWS IoT
Quando l'app si connette per la prima volta AWS IoT, dovrebbe inviare una richiesta HTTP GET alle URLs ombre che utilizza per ottenere lo stato attuale delle ombre che sta utilizzando. Ciò consente di sincronizzare l'app o il servizio con la copia shadow.
## Lo stato di elaborazione cambia mentre l'app o il servizio sono connessi a AWS IoT
Mentre l'app o il servizio è connesso AWS IoT, può interrogare periodicamente lo stato corrente inviando una richiesta HTTP GET sulle URLs ombre che utilizza.
Quando un utente finale interagisce con l'app o il servizio per modificare lo stato del dispositivo, l'app o il servizio può inviare una richiesta HTTP POST alle URLs ombre che utilizza per aggiornare lo `desired` stato dell'ombra. Questa richiesta restituisce la modifica accettata, ma potrebbe essere necessario eseguire il polling della copia shadow effettuando richieste HTTP GET fino a quando il dispositivo non ha aggiornato la cop0ia shadow con il suo nuovo stato.
## Rilevamento della connessione di un dispositivo
Per stabilire se un dispositivo è attualmente connesso, includere una proprietà `connected` nel documento shadow e utilizzare un messaggio LWT (Last Will and Testament) MQTT per impostare la proprietà `connected` su `false` se un dispositivo viene disconnesso a causa di un errore.
**Nota**
I messaggi MQTT LWT inviati ad argomenti AWS IoT riservati (argomenti che iniziano con \$1) vengono ignorati dal servizio AWS IoT Device Shadow. Tuttavia, vengono elaborati dai client sottoscritti e dal motore delle AWS IoT regole, pertanto sarà necessario creare un messaggio LWT da inviare a un argomento non riservato e una regola che ripubblichi il messaggio MQTT LWT come messaggio di aggiornamento shadow nell'argomento di aggiornamento riservato dello shadow,. `ShadowTopicPrefix/update`
**Per inviare un messaggio LWT al servizio Device Shadow**
1. Creare una regola che ripubblica il messaggio LWT MQTT sull'argomento riservato. L'esempio seguente è una regola che ascolta i messaggi sull'argomento `my/things/myLightBulb/update` e li ripubblica su `$aws/things/myLightBulb/shadow/update`.
```
{
"rule": {
"ruleDisabled": false,
"sql": "SELECT * FROM 'my/things/myLightBulb/update'",
"description": "Turn my/things/ into $aws/things/",
"actions": [
{
"republish": {
"topic": "$$aws/things/myLightBulb/shadow/update",
"roleArn": "arn:aws:iam:123456789012:role/aws_iot_republish"
}
}
]
}
}
```
1. Quando il dispositivo si connette AWS IoT, registra un messaggio LWT su un argomento non riservato affinché la regola di ripubblicazione lo riconosca. In questo esempio, tale argomento è `my/things/myLightBulb/update` e imposta la proprietà connessa su `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Dopo la connessione, il dispositivo pubblica un messaggio sul relativo argomento di aggiornamento shadow, `$aws/things/myLightBulb/shadow/update`, per segnalare lo stato corrente, che include l'impostazione della proprietà `connected` su `true`.
```
{
"state": {
"reported": {
"connected":"true"
}
}
}
```
1. Prima della disconnessione, il dispositivo pubblica un messaggio sul relativo argomento di aggiornamento shadow, `$aws/things/myLightBulb/shadow/update`, per segnalare lo stato più recente, che include l'impostazione della proprietà `connected` su `false`.
```
{
"state": {
"reported": {
"connected":"false"
}
}
}
```
1. Se il dispositivo si disconnette a causa di un errore, il broker di messaggi pubblica il AWS IoT messaggio LWT del dispositivo per conto del dispositivo. La regola di ripubblicazione rileva questo messaggio e pubblica il messaggio di aggiornamento shadow per aggiornare la proprietà `connected` del Device Shadow.
**Nota**
A causa della natura asincrona dell'elaborazione della disconnessione, non è garantito che i messaggi LWT vengano inviati in ordine durante la riconnessione. Si consiglia di utilizzare gli eventi del [ciclo di vita per migliorare l'accuratezza del rilevamento dello stato di connettività, poiché questi eventi](life-cycle-events.md) forniscono gli attributi per la gestione degli eventi. out-of-order
# Simulazione delle comunicazioni del servizio Device Shadow
In questo argomento viene illustrato come il servizio Device Shadow funge da intermediario e consente a dispositivi e app di utilizzare una copia shadow per aggiornare, archiviare e recuperare lo stato di un dispositivo.
Per dimostrare l'interazione descritta in questo argomento e per approfondirla ulteriormente, avrai bisogno di un sistema Account AWS e di un sistema su cui eseguire. AWS CLI Se non si dispone di questi, è ancora possibile vedere l'interazione negli esempi di codice.
In questo esempio, la AWS IoT console rappresenta il dispositivo. AWS CLI Rappresenta l'app o il servizio che accede al dispositivo tramite l'ombra. L' AWS CLI interfaccia è molto simile all'API con cui un'app potrebbe utilizzare per comunicare AWS IoT. Il dispositivo in questo esempio è una lampadina intelligente e l'app visualizza lo stato della lampadina e può cambiare lo stato della lampadina.
## Impostazione della simulazione
Queste procedure inizializzano la simulazione aprendo la [console AWS IoT](https://console.aws.amazon.com/iot/home), che simula il dispositivo, e la finestra della riga di comando che simula l'app.
**Per configurare l'ambiente di simulazione**
1. Avrai bisogno Account AWS di un per eseguire autonomamente gli esempi di questo argomento. Se non ne hai uno Account AWS, creane uno, come descritto in[Configurare Account AWS](setting-up.md).
1. Aprire la [console AWS IoT](https://console.aws.amazon.com/iot/home) e, nel menu a sinistra, scegliere **Test** per aprire il **Client MQTT**.
1. In un'altra finestra, aprire una finestra di terminale su un sistema su cui sia installata l' AWS CLI .
Dovrebbero essere aperte due finestre: una con la AWS IoT console nella pagina **Test** e l'altra con il prompt della riga di comando.
## Inizializzare il dispositivo
*In questa simulazione, lavoreremo con un oggetto chiamato oggetto e la sua ombra denominata SimShadow1. *mySimulatedThing**
**Creazione di un oggetto e della relativa policy IoT**
Per creare un oggetto, nella **console AWS IoT **:
1. Scegli **Gestisci**, quindi seleziona **Oggetti**.
1. Fai clic sul pulsante **Crea** se gli elementi sono elencati, altrimenti fai clic su **Registra una singola cosa per creare una singola cosa**. AWS IoT
1. Inserisci il nome `mySimulatedThing`, lascia le altre impostazioni predefinite e quindi fai clic su **Successivo**.
1. Utilizza la creazione di certificati con un solo clic per generare i certificati che autenticheranno la connessione del dispositivo a AWS IoT. Fare clic su **Attiva** per attivare il certificato.
1. È possibile allegare la policy `My_IoT_Policy` che darebbe al dispositivo l'autorizzazione per pubblicare e sottoscrivere gli argomenti riservati MQTT. Per passaggi più dettagliati su come creare un AWS IoT oggetto e su come creare questa politica, consulta[Crea un oggetto](create-iot-resources.md#create-aws-thing).
**Creazione di una copia shadow con nome per un oggetto**
Puoi creare una copia shadow con nome per un oggetto pubblicando una richiesta di aggiornamento sull'argomento `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` come descritto di seguito.
Oppure, per creare un'ombra con nome:
1. Nella **console AWS IoT **, scegli l'oggetto dall'elenco degli oggetti visualizzato e quindi scegli **Shadows** (Copie shadow).
1. Scegli **Aggiungi una copia shadow**, inserisci il nome `simShadow1`, quindi scegli **Crea** per aggiungere la copia shadow.
**Effettua la sottoscrizione e pubblica gli argomenti riservati MQTT**
Nella console, effettua la sottoscrizione a questi argomenti MQTT. Questi argomenti sono le risposte alle operazioni `get`, `update` e `delete`, in modo che il dispositivo sia pronto a ricevere le risposte dopo la pubblicazione di un'operazione.
**Per sottoscrivere un argomento MQTT nel **client MQTT****
1. In **MQTT client** (Client MQTT), scegli **Subscribe to a topic** (Sottoscrivi un argomento).
1. Inserisci gli argomenti `get`, `update` e `delete` a cui vuoi effettuare la sottoscrizione. Copia un argomento alla volta dall'elenco seguente, incollalo nel campo **Filtro di argomenti**, quindi clicca su **Sottoscrivi**. Verranno visualizzati gli argomenti sotto **Sottoscrizioni**.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/delete/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta`
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/documents`
A questo punto, il dispositivo simulato è pronto a ricevere gli argomenti pubblicati da AWS IoT.
**Per pubblicare in un argomento MQTT nel **client MQTT****
Dopo l'inizializzazione e la sottoscrizione agli argomenti di risposta, il dispositivo deve interrogare le copie shadow supportate. Questa simulazione supporta solo un'ombra, l'ombra che supporta un oggetto denominato *SimShadow1*. *mySimulatedThing*
**Per ottenere lo stato shadow corrente dal **client MQTT****
1. Nel **client MQTT**, scegliere **Pubblica in un argomento**.
1. Sotto **Pubblica**, inserisci l'argomento seguente ed elimina qualsiasi contenuto dalla finestra del corpo del messaggio sottostante in cui è stato inserito l'argomento da ottenere. È quindi possibile scegliere **Pubblicazione nell'argomento** per pubblicare la richiesta. `$aws/things/mySimulatedThing/shadow/name/simShadow1/get`.
Se non hai creato un nome shadow `simShadow1`, riceverai un messaggio nell'argomento `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/rejected`, e il `code` sarà `404`, come in questo esempio in cui la copia shadow non è stata creata, quindi verrà creata in seguito.
```
{
"code": 404,
"message": "No shadow exists with name: 'simShadow1'"
}
```
**Per creare una copia shadow con lo stato corrente del dispositivo**
1. Nel **Client MQTT**, scegli **Pubblica in un argomento** e inserisci questo argomento:
```
$aws/things/mySimulatedThing/shadow/name/simShadow1/update
```
1. Nella finestra del corpo del messaggio qui sotto, dove è stato inserito l'argomento, inserire questo documento shadow per mostrare che il dispositivo sta segnalando il suo ID e il suo colore corrente in valori RGB. Scegli **Pubblica** per pubblicare la richiesta.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
Se viene visualizzato un messaggio nell'argomento:
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted`: significa che la copia shadow è stata creata e che il corpo del messaggio contiene il documento shadow corrente.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/update/rejected`: esamina l'errore nel corpo del messaggio.
+ `$aws/things/mySimulatedThing/shadow/name/simShadow1/get/accepted`: la copia shadow esiste già e il corpo del messaggio ha lo stato shadow corrente, come in questo esempio. Con questo, è possibile impostare il dispositivo o confermare che corrisponda allo stato della copia shadow.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591140517,
"clientToken": "426bfd96-e720-46d3-95cd-014e3ef12bb6"
}
```
## Inviare un aggiornamento dall'app
Questa sezione utilizza il AWS CLI per dimostrare come un'app può interagire con un'ombra.
**Per ottenere lo stato attuale dell'ombra, utilizzare AWS CLI**
Nella riga di comando, immettere questo comando:
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Sulle piattaforme Windows è possibile usare `con` al posto di `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
Poiché la copia shadow esiste ed è stata inizializzata dal dispositivo per riflettere lo stato corrente, deve restituire il seguente documento shadow.
```
{
"state": {
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 3,
"timestamp": 1591141111
}
```
L'app può utilizzare questa risposta per inizializzare la sua rappresentazione dello stato del dispositivo.
Se l'app aggiorna lo stato, ad esempio quando un utente finale cambia il colore della lampadina intelligente in giallo, l'app invierà un comando **update-thing-shadow**. Questo comando corrisponde all'API REST `UpdateThingShadow`.
**Per aggiornare una copia shadow da un'app**
Nella riga di comando, immettere questo comando:
------
#### [ AWS CLI v2.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
#### [ AWS CLI v1.x ]
```
aws iot-data update-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 \
--payload '{"state":{"desired":{"ColorRGB":[255,255,0]}},"clientToken":"21b21b21-bfd2-4279-8c65-e2f697ff4fab"}' /dev/stdout
```
------
In caso di esito positivo, questo comando deve restituire il seguente documento shadow.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
}
},
"version": 4,
"timestamp": 1591141596,
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
## Rispondere all'aggiornamento nel dispositivo
Tornando al **client MQTT** nella AWS console, dovreste vedere i messaggi AWS IoT pubblicati in base al comando di aggiornamento emesso nella sezione precedente.
**Per visualizzare i messaggi di aggiornamento nel **client MQTT****
Nel **client MQTT**, scegli **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/delta nella colonna** **Abbonamenti**. Se il nome dell'argomento viene troncato, è possibile metterlo in pausa per visualizzare l'argomento completo. Nel registro degli argomenti di questo argomento, dovresti vedere un messaggio `/delta` simile a questo.
```
{
"version": 4,
"timestamp": 1591141596,
"state": {
"ColorRGB": [
255,
255,
0
]
},
"metadata": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"clientToken": "21b21b21-bfd2-4279-8c65-e2f697ff4fab"
}
```
Il dispositivo elaborerà il contenuto di questo messaggio per impostare lo stato del dispositivo in modo che corrisponda allo stato `desired` del messaggio.
Dopo che il dispositivo ha aggiornato lo stato in modo che corrisponda allo `desired` stato del messaggio, deve inviare nuovamente il nuovo stato segnalato AWS IoT pubblicando un messaggio di aggiornamento. Questa procedura simula questo nel **client MQTT**.
**Per aggiornare la copia shadow dal dispositivo**
1. Nel **client MQTT**, scegliere **Pubblica in un argomento**.
1. Nella finestra del corpo del messaggio, nel campo dell'argomento sopra la finestra del corpo del messaggio, inserisci l'argomento della copia shadow seguito dall'operazione `/update`: `$aws/things/mySimulatedThing/shadow/name/simShadow1/update` e nel corpo del messaggio, inserisci questo documento shadow aggiornato, che descrive lo stato corrente del dispositivo. Scegli **Pubblica** per pubblicare lo stato aggiornato del dispositivo.
```
{
"state": {
"reported": {
"ColorRGB": [255,255,0]
}
},
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Se il messaggio è stato ricevuto correttamente da AWS IoT, dovresti vedere una nuova risposta nel registro **\$1 aws/things/mySimulatedThing/shadow/name/simShadow1/update/accepted** message del **client MQTT** con lo stato attuale dello shadow, come in questo esempio.
```
{
"state": {
"reported": {
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"reported": {
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
Un aggiornamento riuscito allo stato segnalato del dispositivo comporta AWS IoT anche l'invio di una descrizione completa dello stato shadow in un messaggio all'`update/documents`argomento, ad esempio questo corpo del messaggio risultante dall'aggiornamento shadow eseguito dal dispositivo nella procedura precedente.
```
{
"previous": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
128,
128,
128
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
},
{
"timestamp": 1591140517
}
]
}
},
"version": 4
},
"current": {
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5
},
"timestamp": 1591142747,
"clientToken": "a4dc2227-9213-4c6a-a6a5-053304f60258"
}
```
## Osservare l'aggiornamento nell'app
L'app può ora interrogare la copia shadow per lo stato corrente come riportato dal dispositivo.
**Per ottenere lo stato attuale dell'ombra, utilizzare il AWS CLI**
1. Nella riga di comando, immettere questo comando:
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 /dev/stdout
```
Sulle piattaforme Windows è possibile usare `con` al posto di `/dev/stdout`.
```
aws iot-data get-thing-shadow --thing-name mySimulatedThing --shadow-name simShadow1 con
```
1. Poiché la copia shadow è stata appena aggiornata dal dispositivo per riflettere lo stato corrente, dovrebbe restituire il seguente documento shadow.
```
{
"state": {
"desired": {
"ColorRGB": [
255,
255,
0
]
},
"reported": {
"ID": "SmartLamp21",
"ColorRGB": [
255,
255,
0
]
}
},
"metadata": {
"desired": {
"ColorRGB": [
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
},
{
"timestamp": 1591141596
}
]
},
"reported": {
"ID": {
"timestamp": 1591140517
},
"ColorRGB": [
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
},
{
"timestamp": 1591142747
}
]
}
},
"version": 5,
"timestamp": 1591143269
}
```
## Andare oltre la simulazione
Prova l'interazione tra AWS CLI (che rappresenta l'app) e la console (che rappresenta il dispositivo) per modellare la soluzione IoT.
# 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](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html) 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 su un argomento di richiesta per informazioni sulla modalità di AWS IoT gestione della richiesta. Per ulteriori informazioni, consultare [Argomenti MQTT di Device Shadow](device-shadow-mqtt.md) e [API REST del servizio Device Shadow](device-shadow-rest-api.md).
## 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](device-shadow-rest-api.md#API_UpdateThingShadow) o pubblicando sull'argomento [/update](device-shadow-mqtt.md#update-pub-sub-topic). 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.
1. 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`
1. 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"
}
}
}
```
1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) e il messaggio `/update/delta` contiene un documento shadow [/delta response state document](device-shadow-document.md#device-shadow-example-response-json-delta).
1. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'`$aws/things/thingName/shadow/name/shadowName/update/rejected`argomento con un documento [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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](device-shadow-document.md#device-shadow-example-request-json) come corpo del messaggio.
1. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP e un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) shadow come corpo del messaggio di risposta.
AWS IoT pubblicherà anche un messaggio MQTT sull'`$aws/things/thingName/shadow/name/shadowName/update/delta`argomento con un documento [/delta response state document](device-shadow-document.md#device-shadow-example-response-json-delta) shadow per tutti i dispositivi o i client che lo sottoscrivono.
1. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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`
1. 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"
}
}
}
```
1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) ombra.
1. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'`$aws/things/thingName/shadow/name/shadowName/update/rejected`argomento con un documento [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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](device-shadow-document.md#device-shadow-example-request-json) come corpo del messaggio.
1. 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](device-shadow-document.md#device-shadow-example-response-json-accepted) shadow come corpo del messaggio di risposta.
AWS IoT pubblicherà anche un messaggio MQTT sull'`$aws/things/thingName/shadow/name/shadowName/update/delta`argomento con un documento [/delta response state document](device-shadow-document.md#device-shadow-example-response-json-delta) shadow per tutti i dispositivi o i client che lo sottoscrivono.
1. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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`.
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](device-shadow-rest-api.md#API_GetThingShadow) o effettuando la sottoscrizione o la pubblicazione sull'argomento [/get](device-shadow-mqtt.md#get-pub-sub-topic). 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`
1. Il dispositivo o il client pubblica un messaggio nell'argomento `$aws/things/thingName/shadow/name/shadowName/get` con un corpo del messaggio vuoto.
1. Se la richiesta ha esito positivo, AWS IoT pubblica un messaggio nell'`$aws/things/thingName/shadow/name/shadowName/get/accepted`argomento con a [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) nel corpo del messaggio.
1. Se la richiesta non era valida, AWS IoT pubblica un messaggio sull'`$aws/things/thingName/shadow/name/shadowName/get/rejected`argomento con un [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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.
1. Se la richiesta è valida, AWS IoT restituisce un codice di risposta di successo HTTP con un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) ombra come corpo del messaggio di risposta.
1. Se la richiesta non è valida, AWS IoT restituisce un codice di risposta agli errori HTTP e [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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](device-shadow-rest-api.md#API_DeleteThingShadow) o pubblicare nell'argomento [/delete](device-shadow-mqtt.md#delete-pub-sub-topic).
**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](#retrieving-device-shadow) per informazioni su come ottenere il documento shadow corrente.
1. 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`
1. 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
}
}
}
```
1. 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/accepted`argomento con un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) ombra nel corpo del messaggio.
1. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'`$aws/things/thingName/shadow/name/shadowName/update/rejected`argomento con un documento [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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](device-shadow-document.md#device-shadow-example-request-json) 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
}
}
}
```
1. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP e un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) shadow come corpo del messaggio di risposta.
1. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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`
1. Il dispositivo o il client pubblica un `$aws/things/thingName/shadow/name/shadowName/delete` con un buffer di messaggi vuoto.
1. Se la richiesta di eliminazione è valida, AWS IoT elimina l'ombra e pubblica un messaggio con l'`$aws/things/thingName/shadow/name/shadowName/delete/accepted`argomento e un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) shadow abbreviato nel corpo del messaggio. Questo è un esempio del messaggio di eliminazione accettato:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Se la richiesta di aggiornamento non è valida, AWS IoT pubblica un messaggio con l'`$aws/things/thingName/shadow/name/shadowName/delete/rejected`argomento con un documento [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) 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.
1. Se la richiesta era valida, AWS IoT restituisce un codice di risposta di successo HTTP [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) e un documento [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted) shadow abbreviato nel corpo del messaggio. Questo è un esempio del messaggio di eliminazione accettato:
```
{
"version": 4,
"timestamp": 1591057529
}
```
1. Se la richiesta non era valida, AWS IoT restituisce un codice di risposta all'errore HTTP e [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json) come corpo del messaggio di risposta.
# API REST del servizio Device Shadow
Un copia shadow espone l'URI seguente per aggiornare le informazioni sullo stato:
```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```
L'endpoint è specifico per il tuo Account AWS. Per trovare l'endpoint, puoi:
+ Utilizzare il comando [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) da AWS CLI.
+ Usa le impostazioni della AWS IoT console. Nelle **Impostazioni**, l'endpoint è elencato sotto **Endpoint personalizzato**
+ Usa la pagina dei dettagli dell'oggetto della AWS IoT console. Nella console:
1. Apri **Gestione** e sotto **Gestione**, scegli **Oggetti**.
1. Nell'elenco degli oggetti, scegli la cosa per la quale vuoi ottenere l'URI dell'endpoint.
1. Seleziona **Device Shadows** e scegli la tua shadow. È possibile visualizzare l'URI dell'endpoint nella sezione **URL Device Shadow** della pagina **Dettagli Device Shadow**.
Il formato dell'endpoint è il seguente:
```
identifier.iot.region.amazonaws.com
```
L'API shadow REST segue le stesse protocols/port mappature HTTPS descritte in. [Protocolli di dispositivo di comunicazione](protocols.md)
**Nota**
Per utilizzare APIs, è necessario utilizzare `iotdevicegateway` come nome del servizio per l'autenticazione. Per ulteriori informazioni, vedere [Io TData Plane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html).
**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)
Puoi inoltre utilizzare l'API per creare una copia shadow con nome fornendo `name=shadowName` come parte del parametro di query dell'API.
## GetThingShadow
Ottiene la copia shadow per l'oggetto specificato.
Il documento sullo stato della risposta include il delta tra gli stati `desired` e `reported`.
**Richiesta**
La richiesta include le intestazioni HTTP standard più l'URI seguente:
```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Il parametro della query `name` non è necessario per le copie shadow senza nome (classiche).
**Risposta**
In caso di esito positivo, la risposta include le intestazioni HTTP standard più il codice e il corpo seguenti:
```
HTTP 200
Response Body: response state document
```
Per ulteriori informazioni, consulta il [documento di esempio sullo stato della risposta](device-shadow-document.md#device-shadow-example-response-json).
**Autorizzazione**
Per recuperare una copia shadow, è necessaria una policy che permetta all'intermediario di eseguire l'operazione `iot:GetThingShadow`. Il servizio Device Shadow accetta due forme di autenticazione: Signature Version 4 con credenziali IAM o autenticazione reciproca TLS con un certificato client.
Di seguito è riportato un esempio di policy che permette a un intermediario di recuperare una copia shadow di un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:GetThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## UpdateThingShadow
Aggiorna la copia shadow per l'oggetto specificato.
Gli aggiornamenti interessano solo i campi specificati nel documento sullo stato della richiesta. Qualsiasi campo con un valore `null` viene rimosso dalla copia shadow del dispositivo.
**Richiesta**
La richiesta include le intestazioni HTTP standard più l'URI e il corpo seguenti:
```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```
Il parametro della query `name` non è necessario per le copie shadow senza nome (classiche).
Per ulteriori informazioni, consulta il [documento di esempio sullo stato della richiesta](device-shadow-document.md#device-shadow-example-request-json).
**Risposta**
In caso di esito positivo, la risposta include le intestazioni HTTP standard più il codice e il corpo seguenti:
```
HTTP 200
Response body: response state document
```
Per ulteriori informazioni, consulta il [documento di esempio sullo stato della risposta](device-shadow-document.md#device-shadow-example-response-json).
**Autorizzazione**
Per aggiornare una copia shadow, è necessaria una policy che permetta all'intermediario di eseguire l'operazione `iot:UpdateThingShadow`. Il servizio Device Shadow accetta due forme di autenticazione: Signature Version 4 con credenziali IAM o autenticazione reciproca TLS con un certificato client.
Di seguito è riportato un esempio di policy che permette a un intermediario di aggiornare una copia shadow di un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:UpdateThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## DeleteThingShadow
Elimina la copia shadow per l'oggetto specificato.
**Richiesta**
La richiesta include le intestazioni HTTP standard più l'URI seguente:
```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```
Il parametro della query `name` non è necessario per le copie shadow senza nome (classiche).
**Risposta**
In caso di esito positivo, la risposta include le intestazioni HTTP standard più il codice e il corpo seguenti:
```
HTTP 200
Response body: Empty response state document
```
Si noti che l'eliminazione di una copia shadow non reimposta il suo numero di versione su 0.
**Autorizzazione**
Per eliminare una copia shadow di un dispositivo è necessaria una policy che permetta all'intermediario di eseguire l'operazione `iot:DeleteThingShadow`. Il servizio Device Shadow accetta due forme di autenticazione: Signature Version 4 con credenziali IAM o autenticazione reciproca TLS con un certificato client.
Di seguito è riportato un esempio di policy che permette a un intermediario di eliminare una copia shadow di un dispositivo:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DeleteThingShadow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
## ListNamedShadowsForThing
Elenca le copie shadow per l'oggetto specificato.
**Richiesta**
La richiesta include le intestazioni HTTP standard più l'URI seguente:
```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```
nextToken
Token usato per recuperare il successivo set di risultati.
Questo valore viene restituito sui risultati di paging e viene utilizzato nella chiamata che restituisce la pagina successiva.
pageSize
Numero di nomi shadow da restituire in ogni chiamata. Consulta anche `nextToken`.
thingName
Il nome dell'oggetto per cui elencare le copie shadow con nome.
**Risposta**
In caso di esito positivo, la risposta include le intestazioni HTTP standard più il codice di risposta e un [Documento di risposta elenco nomi shadow](device-shadow-document.md#device-shadow-list-json) seguenti:
**Nota**
La copia shadow senza nome (classica) non viene visualizzata in questo elenco. La risposta è una lista vuota se hai solo una copia shadow classica o se il `thingName` non esiste.
```
HTTP 200
Response body: Shadow name list document
```
**Autorizzazione**
Per elencare una copia shadow di un dispositivo è necessaria una policy che permetta all'intermediario di eseguire l'operazione `iot:ListNamedShadowsForThing`. Il servizio Device Shadow accetta due forme di autenticazione: Signature Version 4 con credenziali IAM o autenticazione reciproca TLS con un certificato client.
Di seguito è riportato un esempio di policy che permette a un chiamante di aggiornare una copia shadow con nome di un oggetto:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:ListNamedShadowsForThing",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing"
]
}
]
}
```
# Argomenti MQTT di Device Shadow
Il servizio Device Shadow usa argomenti MQTT riservati per permettere alle applicazioni e ai dispositivi di ottenere, aggiornare o eliminare le informazioni sullo stato per un dispositivo (copia shadow).
Per la pubblicazione e la sottoscrizione negli argomenti delle copie shadow è richiesta l'autorizzazione basata su argomento. AWS IoT si riserva il diritto di aggiungere nuovi argomenti alla struttura di argomenti esistente. Per questo motivo, è consigliabile evitare le sottoscrizioni con caratteri jolly degli argomenti delle copie shadow. Ad esempio, evitate di abbonarvi ai filtri per argomenti, `$aws/things/thingName/shadow/#` perché il numero di argomenti che corrispondono a questo filtro per argomenti potrebbe aumentare man mano che AWS IoT vengono introdotti nuovi argomenti ombra. Per esempi di messaggi pubblicati in questi argomenti, consulta [Interazione con le copia shadow](device-shadow-data-flow.md).
Le copie shadow possono essere con nome o senza nome (classiche). Gli argomenti utilizzati da ciascuno differiscono solo nel prefisso dell'argomento. Questa tabella mostra il prefisso dell'argomento utilizzato da ogni tipo di copia shadow.
| *ShadowTopicPrefix* value | Tipo di copia shadow |
| --- | --- |
| \$1aws/things/thingName/shadow | Copia shadow senza nome (classica) |
| \$1aws/things/thingName/shadow/name/shadowName | Copia shadow con nome |
Per creare un argomento completo, selezionare `ShadowTopicPrefix` per il tipo di copia shadow a cui si desidera fare riferimento, sostituire `thingName` e `shadowName` se applicabile, con i relativi valori corrispondenti, quindi aggiungerlo con lo stub dell'argomento, come illustrato nelle sezioni seguenti.
Di seguito sono elencati gli argomenti MQTT usati per l'interazione con le copie shadow.
**Topics**
+ [/get](#get-pub-sub-topic)
+ [/get/accepted](#get-accepted-pub-sub-topic)
+ [/get/rejected](#get-rejected-pub-sub-topic)
+ [/update](#update-pub-sub-topic)
+ [/update/delta](#update-delta-pub-sub-topic)
+ [/update/accepted](#update-accepted-pub-sub-topic)
+ [/update/documents](#update-documents-pub-sub-topic)
+ [/update/rejected](#update-rejected-pub-sub-topic)
+ [/delete](#delete-pub-sub-topic)
+ [/delete/accepted](#delete-accepted-pub-sub-topic)
+ [/delete/rejected](#delete-rejected-pub-sub-topic)
## /get
Pubblica un messaggio vuoto in questo argomento per ottenere la copia shadow del dispositivo:
```
ShadowTopicPrefix/get
```
AWS IoT risponde pubblicando su uno o. [/get/accepted](#get-accepted-pub-sub-topic) [/get/rejected](#get-rejected-pub-sub-topic)
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get"
]
}
]
}
```
## /get/accepted
AWS IoT pubblica un documento shadow di risposta a questo argomento quando restituisce l'ombra del dispositivo:
```
ShadowTopicPrefix/get/accepted
```
Per ulteriori informazioni, consulta [Documenti sullo stato della risposta](device-shadow-document.md#device-shadow-example-response-json).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/accepted"
]
}
]
}
```
## /get/rejected
AWS IoT pubblica un documento di risposta agli errori su questo argomento quando non può restituire l'ombra del dispositivo:
```
ShadowTopicPrefix/get/rejected
```
Per ulteriori informazioni, consulta [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/get/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/get/rejected"
]
}
]
}
```
## /update
Pubblica un documento sullo stato della richiesta in questo argomento per aggiornare la copia shadow del dispositivo:
```
ShadowTopicPrefix/update
```
Il corpo del messaggio contiene un [documento di stato della richiesta parziale](device-shadow-document.md#device-shadow-example-request-json).
Un client che tenta di aggiornare lo stato di un dispositivo invierebbe un documento di stato della richiesta JSON con la proprietà `desired` come questa:
```
{
"state": {
"desired": {
"color": "red",
"power": "on"
}
}
}
```
Un dispositivo che aggiorna la sua copia shadow invierebbe un documento di stato della richiesta JSON con la proprietà `reported`, ad esempio:
```
{
"state": {
"reported": {
"color": "red",
"power": "on"
}
}
}
```
AWS IoT risponde pubblicando su o[/update/accepted](#update-accepted-pub-sub-topic). [/update/rejected](#update-rejected-pub-sub-topic)
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update"
]
}
]
}
```
## /update/delta
AWS IoT pubblica un documento sullo stato di risposta a questo argomento quando accetta una modifica per l'ombra del dispositivo e il documento sullo stato di risposta contiene valori `desired` e `reported` stati diversi per:
```
ShadowTopicPrefix/update/delta
```
Il buffer dei messaggi contiene un file [/delta response state document](device-shadow-document.md#device-shadow-example-response-json-delta).
### Dettagli corpo del messaggio
+ Un messaggio pubblicato in `update/delta` include solo gli attributi desiderati diversi tra le sezioni `desired` e `reported`. Contiene tutti questi attributi, indipendentemente dal fatto che siano inclusi nel messaggio di aggiornamento corrente o siano già archiviati in AWS IoT. Gli attributi che non presentano differenze tra le sezioni `desired` e `reported` non sono inclusi.
+ Se un attributo è nella sezione `reported`, ma non ha un equivalente nella sezione `desired`, non viene incluso.
+ Se un attributo è nella sezione `desired`, ma non ha un equivalente nella sezione `reported`, viene incluso.
+ Se un attributo viene eliminato dalla sezione `reported`, ma è ancora presente nella sezione `desired`, viene incluso.
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/delta"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/delta"
]
}
]
}
```
## /update/accepted
AWS IoT pubblica un documento sullo stato della risposta a questo argomento quando accetta una modifica per l'ombra del dispositivo:
```
ShadowTopicPrefix/update/accepted
```
Il buffer dei messaggi contiene un file [/accepted response state document](device-shadow-document.md#device-shadow-example-response-json-accepted).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/accepted"
]
}
]
}
```
## /update/documents
AWS IoT pubblica un documento di stato su questo argomento ogni volta che un aggiornamento dell'ombra viene eseguito correttamente:
```
ShadowTopicPrefix/update/documents
```
Il corpo del messaggio contiene un [/documents response state document](device-shadow-document.md#device-shadow-example-response-json-documents).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/documents"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/documents"
]
}
]
}
```
## /update/rejected
AWS IoT pubblica un documento di risposta agli errori su questo argomento quando rifiuta una modifica all'ombra del dispositivo:
```
ShadowTopicPrefix/update/rejected
```
Il corpo del messaggio contiene un [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/update/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/update/rejected"
]
}
]
}
```
## /delete
Per eliminare una copia shadow di un dispositivo, pubblica un messaggio vuoto nell'argomento delete:
```
ShadowTopicPrefix/delete
```
Il contenuto del messaggio viene ignorato.
Si noti che l'eliminazione di una copia shadow non reimposta il suo numero di versione su 0.
AWS IoT risponde pubblicando su o. [/delete/accepted](#delete-accepted-pub-sub-topic) [/delete/rejected](#delete-rejected-pub-sub-topic)
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete"
]
}
]
}
```
## /delete/accepted
AWS IoT pubblica un messaggio su questo argomento quando viene eliminata l'ombra di un dispositivo:
```
ShadowTopicPrefix/delete/accepted
```
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/accepted"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/accepted"
]
}
]
}
```
## /delete/rejected
AWS IoT pubblica un documento di risposta agli errori su questo argomento quando non può eliminare l'ombra del dispositivo:
```
ShadowTopicPrefix/delete/rejected
```
Il corpo del messaggio contiene un [Documenti sulla risposta di errore](device-shadow-document.md#device-shadow-example-error-json).
### Policy di esempio
Di seguito è illustrato un esempio della policy necessaria:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/thingName/shadow/delete/rejected"
]
},
{
"Effect": "Allow",
"Action": [
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thingName/shadow/delete/rejected"
]
}
]
}
```
# 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.
**Topics**
+ [Esempi di documenti shadow](#device-shadow-document-syntax)
+ [Proprietà del documento](#document-structure)
+ [Stato delta](#delta-state)
+ [Controllo delle versioni documenti shadow](#versioning)
+ [I token client nei documenti shadow](#client-token)
+ [Proprietà documento shadow vuote](#device-shadow-empty-fields)
+ [Valori di array nei documenti shadow](#device-shadow-arrays)
## Esempi di documenti shadow
Il servizio Device Shadow utilizza questi documenti nelle operazioni UPDATE, GET e DELETE utilizzando l'[API REST](device-shadow-rest-api.md) o i [ Pub/Sub messaggi MQTT](device-shadow-mqtt.md).
**Topics**
+ [Documento sullo stato della richiesta](#device-shadow-example-request-json)
+ [Documenti sullo stato della risposta](#device-shadow-example-response-json)
+ [Documenti sulla risposta di errore](#device-shadow-example-error-json)
+ [Documento di risposta elenco nomi shadow](#device-shadow-list-json)
### 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à `desired` o `reported`, 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 il `state` dell'oggetto prima dell'aggiornamento.
+ `current` – Dopo un aggiornamento riuscito, contiene il `state` dell'oggetto dopo l'aggiornamento.
+ `state`
+ `reported` – Presente solo se un oggetto ha segnalato dati nella sezione `reported` e contiene solo campi presenti nel documento sullo stato della richiesta.
+ `desired` – Presente solo se un dispositivo ha segnalato dati nella sezione `desired` e contiene solo campi che erano presenti nel documento sullo stato della richiesta.
+ `metadata` - Contiene i timestamp per ogni attributo nelle sezioni `desired` e `reported`, 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](device-shadow-error-messages.md).
### 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 `state` del documento. Le informazioni includono i timestamp, in base all'epoca (Unix epoch), per ogni attributo nella sezione `state`, che permettono di determinare quando gli attributi sono stati aggiornati.
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](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_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 `desired` o `reported`, 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](#device-shadow-document-syntax).
## 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" ]
}
}
```
# Messaggi di errore Device Shadow
Il servizio Device Shadow pubblica un messaggio di errore nell'argomento di errore (tramite MQTT) quando un tentativo di modificare il documento sullo stato ha esito negativo. Questo messaggio viene inviato solo in risposta a una richiesta di pubblicazione in uno degli argomenti `$aws` riservati. Se il client aggiorna il documento usando l'API REST, riceve il codice di errore HTTP come parte della risposta e non viene inviato alcun messaggio di errore MQTT.
****
| Codice di errore HTTP | Messaggi di errore |
| --- | --- |
| 400 (Richiesta non valida) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 401 (Non autorizzato) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 403 (Accesso negato) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 404 (Non trovato) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 409 (Conflitto) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 413 (Payload troppo grande) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 415 (Tipo di supporto non supportato) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 429 (Troppe richieste) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |
| 500 (Errore interno del server) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/device-shadow-error-messages.html) |