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à.
Utilizzate il servizio shadow IPC per interagire con le ombre locali su un dispositivo. Il dispositivo con cui scegli di interagire può essere il tuo dispositivo principale o un dispositivo client connesso.
Per utilizzare queste operazioni IPC, includete il componente shadow manager come dipendenza nel componente personalizzato. È quindi possibile utilizzare le operazioni IPC nei componenti personalizzati per interagire con le ombre locali sul dispositivo tramite lo shadow manager. Per consentire ai componenti personalizzati di reagire ai cambiamenti negli stati shadow locali, puoi anche utilizzare il publish/subscribe IPC service to subscribe to shadow events. For more information about using the publish/subscribe servizio, consulta il. Pubblicare/sottoscrivere messaggi locali
Nota
Per consentire a un dispositivo principale di interagire con le ombre dei dispositivi client, è inoltre necessario configurare e distribuire il componente bridge MQTT. Per ulteriori informazioni, consultate Attivare lo shadow manager per comunicare con i dispositivi client.
Argomenti
Versioni SDK minime
La tabella seguente elenca le versioni minime di SDK per dispositivi AWS IoT da utilizzare per interagire con le ombre locali.
SDK | Versione minima |
---|---|
v1.4.0 |
|
v1.6.0 |
|
v1.17.0 |
|
v1.12.0 |
Autorizzazione
Per utilizzare il servizio shadow IPC in un componente personalizzato, è necessario definire politiche di autorizzazione che consentano al componente di interagire con le ombre. Per informazioni sulla definizione delle politiche di autorizzazione, vedere. Autorizza i componenti a eseguire operazioni IPC
Le politiche di autorizzazione per l'interazione shadow hanno le seguenti proprietà.
Identificatore del servizio IPC: aws.greengrass.ShadowManager
Operazione | Descrizione | Risorse |
---|---|---|
|
Consente a un componente di recuperare l'ombra di un oggetto. |
Una delle seguenti stringhe:
|
|
Consente a un componente di aggiornare l'ombra di un oggetto. |
Una delle seguenti stringhe:
|
|
Consente a un componente di eliminare l'ombra di un oggetto. |
Una delle seguenti stringhe:
|
|
Consente a un componente di recuperare l'elenco delle ombre denominate per un oggetto. |
Una stringa di nome dell'oggetto che consente di accedere all'oggetto per elencarne le ombre.
|
Identificatore del servizio IPC: aws.greengrass.ipc.pubsub
Operazione | Descrizione | Risorse |
---|---|---|
|
Consente a un componente di sottoscrivere i messaggi per gli argomenti specificati. |
Una delle seguenti stringhe di argomenti:
Il valore del prefisso dell'argomento
Utilizzato In Greengrass nucleus v2.6.0 e versioni successive, è possibile sottoscrivere argomenti che contengono caratteri jolly degli argomenti MQTT (and). |
Variabili Recipe nelle politiche di autorizzazione shadow locali
Se si utilizza la versione 2.6.0 o successiva del nucleo di Greengrass e si imposta l'opzione di interpolateComponentConfigurationconfigurazione di Greengrass nucleus sutrue, è possibile utilizzare la variabile recipe nelle politiche di autorizzazione. {iot:thingName} Questa funzionalità consente di configurare un'unica politica di autorizzazione per un gruppo di dispositivi principali, in cui ogni dispositivo principale può accedere solo alla propria ombra. Ad esempio, è possibile consentire a un componente l'accesso alla seguente risorsa per le operazioni IPC shadow.
$aws/things/{iot:thingName}/shadow/
Esempi di politiche di autorizzazione
Puoi fare riferimento ai seguenti esempi di politiche di autorizzazione per aiutarti a configurare le politiche di autorizzazione per i tuoi componenti.
Esempio: consenti a un gruppo di dispositivi principali di interagire con le ombre locali
Importante
Questo esempio utilizza una funzionalità disponibile per la versione 2.6.0 e successive del componente Greengrass nucleus. Greengrass nucleus v2.6.0 aggiunge il supporto per la maggior parte delle variabili di ricetta, ad esempio nelle configurazioni dei componenti. {iot:thingName}
Per abilitare questa funzionalità, imposta l'opzione di interpolateComponentConfigurationconfigurazione del nucleo di Greengrass su. true
Per un esempio che funziona per tutte le versioni del Greengrass nucleus, vedi la politica di autorizzazione di esempio per un dispositivo single core.
Il seguente esempio di politica di autorizzazione consente com.example.MyShadowInteractionComponent
al componente di interagire con la classica ombra del dispositivo e l'ombra denominata myNamedShadow
per il dispositivo principale che esegue il componente. Questa politica consente inoltre a questo componente di ricevere messaggi su argomenti locali relativi a queste ombre.
{
"accessControl": {
"aws.greengrass.ShadowManager": {
"com.example.MyShadowInteractionComponent:shadow:1": {
"policyDescription": "Allows access to shadows",
"operations": [
"aws.greengrass#GetThingShadow",
"aws.greengrass#UpdateThingShadow",
"aws.greengrass#DeleteThingShadow"
],
"resources": [
"$aws/things/{iot:thingName}/shadow",
"$aws/things/{iot:thingName}/shadow/name/myNamedShadow"
]
},
"com.example.MyShadowInteractionComponent:shadow:2": {
"policyDescription": "Allows access to things with shadows",
"operations": [
"aws.greengrass#ListNamedShadowsForThing"
],
"resources": [
"{iot:thingName}"
]
}
},
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowInteractionComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/{iot:thingName}/shadow/get/accepted",
"$aws/things/{iot:thingName}/shadow/name/myNamedShadow/get/accepted"
]
}
}
}
}
Esempio: consenti a un gruppo di dispositivi principali di interagire con le ombre dei dispositivi client
Importante
Il seguente esempio di politica di autorizzazione consente com.example.MyShadowInteractionComponent
al componente di interagire con tutte le ombre dei dispositivi per i dispositivi client i cui nomi iniziano con. MyClientDevice
Nota
Per consentire a un dispositivo principale di interagire con le ombre dei dispositivi client, è inoltre necessario configurare e distribuire il componente bridge MQTT. Per ulteriori informazioni, consultate Attivare lo shadow manager per comunicare con i dispositivi client.
{
"accessControl": {
"aws.greengrass.ShadowManager": {
"com.example.MyShadowInteractionComponent:shadow:1": {
"policyDescription": "Allows access to shadows",
"operations": [
"aws.greengrass#GetThingShadow",
"aws.greengrass#UpdateThingShadow",
"aws.greengrass#DeleteThingShadow"
],
"resources": [
"$aws/things/MyClientDevice*/shadow",
"$aws/things/MyClientDevice*/shadow/name/*"
]
},
"com.example.MyShadowInteractionComponent:shadow:2": {
"policyDescription": "Allows access to things with shadows",
"operations": [
"aws.greengrass#ListNamedShadowsForThing"
],
"resources": [
"MyClientDevice*"
]
}
}
}
}
Esempio: consenti a un dispositivo single-core di interagire con le ombre locali
Il seguente esempio di politica di autorizzazione consente com.example.MyShadowInteractionComponent
al componente di interagire con la classica ombra del dispositivo e l'ombra denominata myNamedShadow
per il dispositivoMyThingName
. Questa politica consente inoltre a questo componente di ricevere messaggi su argomenti locali relativi a queste ombre.
{
"accessControl": {
"aws.greengrass.ShadowManager": {
"com.example.MyShadowInteractionComponent:shadow:1": {
"policyDescription": "Allows access to shadows",
"operations": [
"aws.greengrass#GetThingShadow",
"aws.greengrass#UpdateThingShadow",
"aws.greengrass#DeleteThingShadow"
],
"resources": [
"$aws/things/MyThingName/shadow",
"$aws/things/MyThingName/shadow/name/myNamedShadow"
]
},
"com.example.MyShadowInteractionComponent:shadow:2": {
"policyDescription": "Allows access to things with shadows",
"operations": [
"aws.greengrass#ListNamedShadowsForThing"
],
"resources": [
"MyThingName"
]
}
},
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowInteractionComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/MyThingName/shadow/get/accepted",
"$aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted"
]
}
}
}
}
Esempio: consenti a un gruppo di dispositivi principali di reagire ai cambiamenti dello stato ombra locale
Importante
Questo esempio utilizza una funzionalità disponibile per la versione 2.6.0 e successive del componente Greengrass nucleus. Greengrass nucleus v2.6.0 aggiunge il supporto per la maggior parte delle variabili di ricetta, ad esempio nelle configurazioni dei componenti. {iot:thingName}
Per abilitare questa funzionalità, imposta l'opzione di interpolateComponentConfigurationconfigurazione del nucleo di Greengrass su. true
Per un esempio che funziona per tutte le versioni del Greengrass nucleus, vedi la politica di autorizzazione di esempio per un dispositivo single core.
Il seguente esempio di politica di controllo degli accessi consente com.example.MyShadowReactiveComponent
all'utente personalizzato di ricevere messaggi sull'/update/delta
argomento per il dispositivo shadow classico e l'shadow denominato myNamedShadow
su ogni dispositivo principale su cui è in esecuzione il componente.
{
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowReactiveComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/{iot:thingName}/shadow/update/delta",
"$aws/things/{iot:thingName}/shadow/name/myNamedShadow/update/delta"
]
}
}
}
}
Esempio: consentire a un dispositivo single-core di reagire ai cambiamenti dello stato ombra locale
Il seguente esempio di politica di controllo degli accessi consente com.example.MyShadowReactiveComponent
all'utente personalizzato di ricevere messaggi sull'/update/delta
argomento per il dispositivo shadow classico e l'ombra denominata myNamedShadow
per il dispositivoMyThingName
.
{
"accessControl": {
"aws.greengrass.ipc.pubsub": {
"com.example.MyShadowReactiveComponent:pubsub:1": {
"policyDescription": "Allows access to shadow pubsub topics",
"operations": [
"aws.greengrass#SubscribeToTopic"
],
"resources": [
"$aws/things/MyThingName/shadow/update/delta",
"$aws/things/MyThingName/shadow/name/myNamedShadow/update/delta"
]
}
}
}
}
GetThingShadow
Ottieni l'ombra per una cosa specificata.
Richiesta
La richiesta di questa operazione ha i seguenti parametri:
thingName
(Python:)thing_name
-
Nome dell'oggetto.
Tipo:
string
shadowName
(Python:)shadow_name
-
Il nome della copia shadow. Per specificare l'ombra classica dell'oggetto, imposta questo parametro su una stringa vuota (
""
).avvertimento
Il AWS IoT Greengrass servizio utilizza lo shadow
AWSManagedGreengrassV2Deployment
denominato per gestire le distribuzioni destinate a singoli dispositivi core. Questa ombra denominata è riservata all'uso da parte del AWS IoT Greengrass servizio. Non aggiornare o eliminare questa ombra denominata.Tipo:
string
Risposta
La risposta di questa operazione contiene le seguenti informazioni:
payload
-
Il documento sullo stato della risposta sotto forma di blob.
Tipo:
object
che contiene le seguenti informazioni:state
-
Le informazioni sullo stato.
Questo oggetto contiene le seguenti informazioni.
desired
-
Le proprietà e i valori dello stato da aggiornare nel dispositivo.
Tipo:
map
di coppie chiave-valore reported
-
Le proprietà e i valori dello stato riportati dal dispositivo.
Tipo:
map
di coppie chiave-valore delta
-
La differenza tra le proprietà e i valori dello stato desiderati e quelli riportati. Questa proprietà è presente solo se gli
reported
statidesired
and sono diversi.Tipo:
map
di coppie chiave-valore
metadata
-
I timestamp per ogni attributo nelle
reported
sezionidesired
and in modo da poter determinare quando lo stato è stato aggiornato.Tipo:
string
timestamp
-
L'epoca, la data e l'ora in cui è stata generata la risposta.
Tipo:
integer
clientToken
(Python:)clientToken
-
Il token utilizzato per abbinare la richiesta e la risposta corrispondente
Tipo:
string
version
-
La versione del documento shadow locale.
Tipo:
integer
Errori
Questa operazione può restituire i seguenti errori.
InvalidArgumentsError
-
Il servizio shadow locale non è in grado di convalidare i parametri della richiesta. Ciò può verificarsi se la richiesta contiene caratteri JSON non validi o non supportati.
ResourceNotFoundError
-
Il documento shadow locale richiesto non può essere trovato.
ServiceError
-
Si è verificato un errore interno del servizio oppure il numero di richieste al servizio IPC ha superato i limiti specificati nei parametri di
maxTotalLocalRequestsRate
configurazionemaxLocalRequestsPerSecondPerThing
e nel componente shadow manager. -
La politica di autorizzazione del componente non include le autorizzazioni necessarie per questa operazione.
Esempi
Gli esempi seguenti mostrano come chiamare questa operazione nel codice del componente personalizzato.
Esempio: Get a thing shadow
Nota
Questo esempio utilizza una IPCUtils
classe per creare una connessione al servizio AWS IoT Greengrass Core IPC. Per ulteriori informazioni, consulta Connect al servizio AWS IoT Greengrass Core IPC.
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GetThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.GetThingShadowRequest;
import software.amazon.awssdk.aws.greengrass.model.GetThingShadowResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class GetThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0];
String shadowName = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
GetThingShadowResponseHandler responseHandler =
GetThingShadow.getThingShadow(ipcClient, thingName, shadowName);
CompletableFuture<GetThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
GetThingShadowResponse response = futureResponse.get(TIMEOUT_SECONDS,
TimeUnit.SECONDS);
String shadowPayload = new String(response.getPayload(), StandardCharsets.UTF_8);
System.out.printf("Successfully got shadow %s/%s: %s%n", thingName, shadowName,
shadowPayload);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while getting shadow: %s/%s%n", thingName,
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while getting shadow: %s/%s%n",
thingName, shadowName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.printf("Unable to find shadow to get: %s/%s%n", thingName,
shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static GetThingShadowResponseHandler getThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) {
GetThingShadowRequest getThingShadowRequest = new GetThingShadowRequest();
getThingShadowRequest.setThingName(thingName);
getThingShadowRequest.setShadowName(shadowName);
return greengrassCoreIPCClient.getThingShadow(getThingShadowRequest, Optional.empty());
}
}
UpdateThingShadow
Aggiorna l'ombra per l'oggetto specificato. Se non esiste un'ombra, ne viene creata una.
Richiesta
La richiesta di questa operazione ha i seguenti parametri:
thingName
(Python:)thing_name
-
Nome dell'oggetto.
Tipo:
string
shadowName
(Python:)shadow_name
-
Il nome della copia shadow. Per specificare l'ombra classica dell'oggetto, imposta questo parametro su una stringa vuota (
""
).avvertimento
Il AWS IoT Greengrass servizio utilizza lo shadow
AWSManagedGreengrassV2Deployment
denominato per gestire le distribuzioni destinate a singoli dispositivi core. Questa ombra denominata è riservata all'uso da parte del AWS IoT Greengrass servizio. Non aggiornare o eliminare questa ombra denominata.Tipo:
string
payload
-
Il documento di stato della richiesta come blob.
Tipo:
object
che contiene le seguenti informazioni:state
-
Le informazioni sullo stato da aggiornare. Questa operazione IPC ha effetto solo sui campi specificati.
Questo oggetto contiene le seguenti informazioni. In genere, utilizzerai la
desired
proprietà o lareported
proprietà, ma non entrambe nella stessa richiesta.desired
-
Le proprietà e i valori dello stato di cui si richiede l'aggiornamento nel dispositivo.
Tipo:
map
di coppie chiave-valore reported
-
Le proprietà e i valori dello stato riportati dal dispositivo.
Tipo:
map
di coppie chiave-valore
clientToken
(Python:)client_token
-
(Facoltativo) Il token utilizzato per abbinare la richiesta e la risposta corrispondente dal token client.
Tipo:
string
version
-
(Facoltativo) La versione del documento shadow locale da aggiornare. Il servizio shadow elabora l'aggiornamento solo se la versione specificata corrisponde all'ultima versione disponibile.
Tipo:
integer
Risposta
La risposta di questa operazione contiene le seguenti informazioni:
payload
-
Il documento sullo stato della risposta sotto forma di blob.
Tipo:
object
che contiene le seguenti informazioni:state
-
Le informazioni sullo stato.
Questo oggetto contiene le seguenti informazioni.
desired
-
Le proprietà e i valori dello stato da aggiornare nel dispositivo.
Tipo:
map
di coppie chiave-valore reported
-
Le proprietà e i valori dello stato riportati dal dispositivo.
Tipo:
map
di coppie chiave-valore delta
-
Le proprietà e i valori dello stato riportati dal dispositivo.
Tipo:
map
di coppie chiave-valore
metadata
-
I timestamp per ogni attributo nelle
reported
sezionidesired
and in modo da poter determinare quando lo stato è stato aggiornato.Tipo:
string
timestamp
-
L'epoca, la data e l'ora in cui è stata generata la risposta.
Tipo:
integer
clientToken
(Python:)client_token
-
Il token utilizzato per abbinare la richiesta e la risposta corrispondente.
Tipo:
string
version
-
La versione del documento shadow locale dopo il completamento dell'aggiornamento.
Tipo:
integer
Errori
Questa operazione può restituire i seguenti errori.
ConflictError
-
Il servizio shadow locale ha rilevato un conflitto di versione durante l'operazione di aggiornamento. Ciò si verifica quando la versione nel payload della richiesta non corrisponde alla versione dell'ultimo documento shadow locale disponibile.
InvalidArgumentsError
-
Il servizio shadow locale non è in grado di convalidare i parametri della richiesta. Ciò può verificarsi se la richiesta contiene caratteri JSON non validi o non supportati.
Un valido
payload
ha le seguenti proprietà:-
Il
state
nodo esiste ed è un oggetto che contiene le informazionireported
sullo statodesired
o. -
I
reported
nodidesired
and sono oggetti o nulli. Almeno uno di questi oggetti deve contenere informazioni sullo stato valide. -
La profondità degli
reported
oggettidesired
e non può superare gli otto nodi. -
La lunghezza del
clientToken
valore non può superare i 64 caratteri. -
Il
version
valore deve essere uguale1
o superiore.
-
ServiceError
-
Si è verificato un errore interno del servizio oppure il numero di richieste al servizio IPC ha superato i limiti specificati nei parametri di
maxTotalLocalRequestsRate
configurazionemaxLocalRequestsPerSecondPerThing
e nel componente shadow manager. -
La politica di autorizzazione del componente non include le autorizzazioni necessarie per questa operazione.
Esempi
Gli esempi seguenti mostrano come chiamare questa operazione nel codice del componente personalizzato.
Esempio: aggiorna l'ombra di una cosa
Nota
Questo esempio utilizza una IPCUtils
classe per creare una connessione al servizio AWS IoT Greengrass Core IPC. Per ulteriori informazioni, consulta Connect al servizio AWS IoT Greengrass Core IPC.
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.UpdateThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowRequest;
import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowResponse;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class UpdateThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0];
String shadowName = args[1];
byte[] shadowPayload = args[2].getBytes(StandardCharsets.UTF_8);
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
UpdateThingShadowResponseHandler responseHandler =
UpdateThingShadow.updateThingShadow(ipcClient, thingName, shadowName,
shadowPayload);
CompletableFuture<UpdateThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.printf("Successfully updated shadow: %s/%s%n", thingName, shadowName);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while updating shadow: %s/%s%n", thingName,
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while updating shadow: %s/%s%n",
thingName, shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static UpdateThingShadowResponseHandler updateThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName, byte[] shadowPayload) {
UpdateThingShadowRequest updateThingShadowRequest = new UpdateThingShadowRequest();
updateThingShadowRequest.setThingName(thingName);
updateThingShadowRequest.setShadowName(shadowName);
updateThingShadowRequest.setPayload(shadowPayload);
return greengrassCoreIPCClient.updateThingShadow(updateThingShadowRequest,
Optional.empty());
}
}
DeleteThingShadow
Elimina la copia shadow per l'oggetto specificato.
A partire da shadow manager v2.0.4, l'eliminazione di un'ombra incrementa il numero di versione. Ad esempio, quando si elimina l'ombra MyThingShadow
nella versione 1, la versione dell'ombra eliminata è 2. Se poi ricreate un'ombra con il nomeMyThingShadow
, la versione per quell'ombra è 3.
Richiesta
La richiesta di questa operazione ha i seguenti parametri:
thingName
(Python:)thing_name
-
Nome dell'oggetto.
Tipo:
string
shadowName
(Python:)shadow_name
-
Il nome della copia shadow. Per specificare l'ombra classica dell'oggetto, imposta questo parametro su una stringa vuota (
""
).avvertimento
Il AWS IoT Greengrass servizio utilizza lo shadow
AWSManagedGreengrassV2Deployment
denominato per gestire le distribuzioni destinate a singoli dispositivi core. Questa ombra denominata è riservata all'uso da parte del AWS IoT Greengrass servizio. Non aggiornare o eliminare questa ombra denominata.Tipo:
string
Risposta
La risposta di questa operazione contiene le seguenti informazioni:
payload
-
Un documento vuoto sullo stato della risposta.
Errori
Questa operazione può restituire i seguenti errori.
InvalidArgumentsError
-
Il servizio shadow locale non è in grado di convalidare i parametri della richiesta. Ciò può verificarsi se la richiesta contiene caratteri JSON non validi o non supportati.
ResourceNotFoundError
-
Il documento shadow locale richiesto non può essere trovato.
ServiceError
-
Si è verificato un errore interno del servizio oppure il numero di richieste al servizio IPC ha superato i limiti specificati nei parametri di
maxTotalLocalRequestsRate
configurazionemaxLocalRequestsPerSecondPerThing
e nel componente shadow manager. -
La politica di autorizzazione del componente non include le autorizzazioni necessarie per questa operazione.
Esempi
Gli esempi seguenti mostrano come chiamare questa operazione nel codice del componente personalizzato.
Esempio: eliminare l'ombra di una cosa
Nota
Questo esempio utilizza una IPCUtils
classe per creare una connessione al servizio AWS IoT Greengrass Core IPC. Per ulteriori informazioni, consulta Connect al servizio AWS IoT Greengrass Core IPC.
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.DeleteThingShadowResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowRequest;
import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class DeleteThingShadow {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0];
String shadowName = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
DeleteThingShadowResponseHandler responseHandler =
DeleteThingShadow.deleteThingShadow(ipcClient, thingName, shadowName);
CompletableFuture<DeleteThingShadowResponse> futureResponse =
responseHandler.getResponse();
try {
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
System.out.printf("Successfully deleted shadow: %s/%s%n", thingName, shadowName);
} catch (TimeoutException e) {
System.err.printf("Timeout occurred while deleting shadow: %s/%s%n", thingName,
shadowName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.printf("Unauthorized error while deleting shadow: %s/%s%n",
thingName, shadowName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.printf("Unable to find shadow to delete: %s/%s%n", thingName,
shadowName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static DeleteThingShadowResponseHandler deleteThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) {
DeleteThingShadowRequest deleteThingShadowRequest = new DeleteThingShadowRequest();
deleteThingShadowRequest.setThingName(thingName);
deleteThingShadowRequest.setShadowName(shadowName);
return greengrassCoreIPCClient.deleteThingShadow(deleteThingShadowRequest,
Optional.empty());
}
}
ListNamedShadowsForThing
Elenca le ombre denominate per l'oggetto specificato.
Richiesta
La richiesta di questa operazione ha i seguenti parametri:
thingName
(Python:)thing_name
-
Nome dell'oggetto.
Tipo:
string
pageSize
(Python:)page_size
-
(Facoltativo) Il numero di nomi shadow da restituire in ogni chiamata.
Tipo:
integer
Impostazione predefinita: 25
Massimo: 100
nextToken
(Python:)next_token
-
(Facoltativo) Il token per recuperare il prossimo set di risultati. Questo valore viene restituito sui risultati di paging e viene utilizzato nella chiamata che restituisce la pagina successiva.
Tipo:
string
Risposta
La risposta di questa operazione contiene le seguenti informazioni:
results
-
L'elenco dei nomi delle ombre.
Tipo:
array
timestamp
-
(Facoltativo) La data e l'ora in cui è stata generata la risposta.
Tipo:
integer
nextToken
(Python:)next_token
-
(Facoltativo) Il valore del token da utilizzare nelle richieste paginate per recuperare la pagina successiva nella sequenza. Questo token non è presente quando non ci sono più nomi ombra da restituire.
Tipo:
string
Nota
Se la dimensione della pagina richiesta corrisponde esattamente al numero di nomi shadow nella risposta, allora questo token è presente; tuttavia, se utilizzato, restituisce un elenco vuoto.
Errori
Questa operazione può restituire i seguenti errori.
InvalidArgumentsError
-
Il servizio shadow locale non è in grado di convalidare i parametri della richiesta. Ciò può verificarsi se la richiesta contiene caratteri JSON non validi o non supportati.
ResourceNotFoundError
-
Il documento shadow locale richiesto non può essere trovato.
ServiceError
-
Si è verificato un errore interno del servizio oppure il numero di richieste al servizio IPC ha superato i limiti specificati nei parametri di
maxTotalLocalRequestsRate
configurazionemaxLocalRequestsPerSecondPerThing
e nel componente shadow manager. -
La politica di autorizzazione del componente non include le autorizzazioni necessarie per questa operazione.
Esempi
Gli esempi seguenti mostrano come chiamare questa operazione nel codice del componente personalizzato.
Esempio: elenca una cosa chiamata shadows
Nota
Questo esempio utilizza una IPCUtils
classe per creare una connessione al servizio AWS IoT Greengrass Core IPC. Per ulteriori informazioni, consulta Connect al servizio AWS IoT Greengrass Core IPC.
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.ListNamedShadowsForThingResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingRequest;
import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingResponse;
import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class ListNamedShadowsForThing {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
// Use the current core device's name if thing name isn't set.
String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
List<String> namedShadows = new ArrayList<>();
String nextToken = null;
try {
// Send additional requests until there's no pagination token in the response.
do {
ListNamedShadowsForThingResponseHandler responseHandler =
ListNamedShadowsForThing.listNamedShadowsForThing(ipcClient, thingName,
nextToken, 25);
CompletableFuture<ListNamedShadowsForThingResponse> futureResponse =
responseHandler.getResponse();
ListNamedShadowsForThingResponse response =
futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
List<String> responseNamedShadows = response.getResults();
namedShadows.addAll(responseNamedShadows);
nextToken = response.getNextToken();
} while (nextToken != null);
System.out.printf("Successfully got named shadows for thing %s: %s%n", thingName,
String.join(",", namedShadows));
} catch (TimeoutException e) {
System.err.println("Timeout occurred while listing named shadows for thing: " + thingName);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while listing named shadows for " +
"thing: " + thingName);
} else if (e.getCause() instanceof ResourceNotFoundError) {
System.err.println("Unable to find thing to list named shadows: " + thingName);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static ListNamedShadowsForThingResponseHandler listNamedShadowsForThing(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String nextToken, int pageSize) {
ListNamedShadowsForThingRequest listNamedShadowsForThingRequest =
new ListNamedShadowsForThingRequest();
listNamedShadowsForThingRequest.setThingName(thingName);
listNamedShadowsForThingRequest.setNextToken(nextToken);
listNamedShadowsForThingRequest.setPageSize(pageSize);
return greengrassCoreIPCClient.listNamedShadowsForThing(listNamedShadowsForThingRequest,
Optional.empty());
}
}