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à.

# Utilizzo delle copie shadow nei dispositivi
<a name="device-shadow-comms-device"></a>

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
<a name="device-shadow-comms-device-first-connect"></a>

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
<a name="device-shadow-comms-device-while-connected"></a>

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
<a name="device-shadow-comms-device-reconnect"></a>

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.