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à.
# 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"
]
}
]
}
```