Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Utilisez le service Shadow IPC pour interagir avec les ombres locales sur un appareil. L'appareil avec lequel vous choisissez d'interagir peut être votre appareil principal ou un appareil client connecté.
Pour utiliser ces opérations IPC, incluez le composant Shadow Manager en tant que dépendance dans votre composant personnalisé. Vous pouvez ensuite utiliser les opérations IPC dans vos composants personnalisés pour interagir avec les ombres locales de votre appareil via le gestionnaire d'ombres. Pour permettre aux composants personnalisés de réagir aux modifications des états fantômes locaux, vous pouvez également utiliser le publish/subscribe IPC service to subscribe to shadow events. For more information about using the publish/subscribe service, voir lePublier/souscrire des messages locaux.
Note
Pour permettre à un périphérique principal d'interagir avec les ombres du périphérique client, vous devez également configurer et déployer le composant de pont MQTT. Pour plus d'informations, voir Activer le Shadow Manager pour communiquer avec les appareils clients.
Rubriques
Versions minimales du SDK
Le tableau suivant répertorie les versions minimales Kit SDK des appareils AWS IoT que vous devez utiliser pour interagir avec les ombres locales.
SDK | Version minimale |
---|---|
v1.4.0 |
|
v1.6.0 |
|
v1.17.0 |
|
v1.12.0 |
Autorisation
Pour utiliser le service Shadow IPC dans un composant personnalisé, vous devez définir des politiques d'autorisation permettant à votre composant d'interagir avec les ombres. Pour plus d'informations sur la définition des politiques d'autorisation, consultezAutoriser les composants à effectuer des opérations IPC.
Les politiques d'autorisation pour l'interaction parallèle ont les propriétés suivantes.
Identifiant du service IPC : aws.greengrass.ShadowManager
Opération | Description | Ressources |
---|---|---|
|
Permet à un composant de récupérer l'ombre d'un objet. |
L'une des chaînes suivantes :
|
|
Permet à un composant de mettre à jour l'ombre d'un objet. |
L'une des chaînes suivantes :
|
|
Permet à un composant de supprimer l'ombre d'un objet. |
L'une des chaînes suivantes :
|
|
Permet à un composant de récupérer la liste des ombres nommées pour un objet. |
Chaîne de nom d'objet qui permet d'accéder à l'objet pour répertorier ses ombres.
|
Identifiant du service IPC : aws.greengrass.ipc.pubsub
Opération | Description | Ressources |
---|---|---|
|
Permet à un composant de s'abonner à des messages pour les sujets que vous spécifiez. |
L'une des chaînes de rubrique suivantes :
La valeur du préfixe de rubrique
Dans Greengrass nucleus v2.6.0 et versions ultérieures, vous pouvez vous abonner à des sujets contenant des caractères génériques MQTT (et). |
Variables de recette dans les politiques d'autorisation fictives locales
Si vous utilisez la version 2.6.0 ou ultérieure du noyau Greengrass et que vous définissez l'option de interpolateComponentConfigurationconfiguration du noyau Greengrass surtrue, vous pouvez utiliser la variable de recette dans les politiques d'autorisation. {iot:thingName} Cette fonctionnalité vous permet de configurer une politique d'autorisation unique pour un groupe de périphériques principaux, chaque périphérique principal ne pouvant accéder qu'à son propre périphérique fantôme. Par exemple, vous pouvez autoriser un composant à accéder à la ressource suivante pour les opérations IPC parallèles.
$aws/things/{iot:thingName}/shadow/
Exemples de politiques d'autorisation
Vous pouvez vous référer aux exemples de politiques d'autorisation suivants pour vous aider à configurer les politiques d'autorisation pour vos composants.
Exemple : autoriser un groupe d'appareils principaux à interagir avec les ombres locales
Important
Cet exemple utilise une fonctionnalité disponible pour les versions 2.6.0 et ultérieures du composant Greengrass nucleus. Greengrass nucleus v2.6.0 ajoute la prise en charge de la plupart des variables de recette, notamment dans les configurations de composants{iot:thingName}
. Pour activer cette fonctionnalité, définissez l'option de configuration du noyau de Greengrass sur. interpolateComponentConfigurationtrue
Pour un exemple qui fonctionne pour toutes les versions du noyau Greengrass, consultez l'exemple de politique d'autorisation pour un appareil monocœur.
L'exemple de politique d'autorisation suivant permet com.example.MyShadowInteractionComponent
au composant d'interagir avec l'ombre de périphérique classique et l'ombre nommée myNamedShadow
pour le périphérique principal qui exécute le composant. Cette politique permet également à ce composant de recevoir des messages sur des sujets locaux pour ces ombres.
{
"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"
]
}
}
}
}
Exemple : autoriser un groupe d'appareils principaux à interagir avec les ombres des appareils clients
Important
L'exemple de politique d'autorisation suivant permet au composant com.example.MyShadowInteractionComponent
d'interagir avec toutes les ombres de périphériques pour les appareils clients dont le nom commence parMyClientDevice
.
Note
Pour permettre à un périphérique principal d'interagir avec les ombres du périphérique client, vous devez également configurer et déployer le composant de pont MQTT. Pour plus d'informations, voir Activer le Shadow Manager pour communiquer avec les appareils clients.
{
"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*"
]
}
}
}
}
Exemple : autoriser un appareil central à interagir avec les ombres locales
L'exemple de politique d'autorisation suivant permet com.example.MyShadowInteractionComponent
au composant d'interagir avec l'ombre classique du périphérique et l'ombre nommée myNamedShadow
pour le périphériqueMyThingName
. Cette politique permet également à ce composant de recevoir des messages sur des sujets locaux pour ces ombres.
{
"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"
]
}
}
}
}
Exemple : autoriser un groupe de périphériques principaux à réagir aux modifications de l'état parallèle local
Important
Cet exemple utilise une fonctionnalité disponible pour les versions 2.6.0 et ultérieures du composant Greengrass nucleus. Greengrass nucleus v2.6.0 ajoute la prise en charge de la plupart des variables de recette, notamment dans les configurations de composants{iot:thingName}
. Pour activer cette fonctionnalité, définissez l'option de configuration du noyau de Greengrass sur. interpolateComponentConfigurationtrue
Pour un exemple qui fonctionne pour toutes les versions du noyau Greengrass, consultez l'exemple de politique d'autorisation pour un appareil monocœur.
L'exemple de politique de contrôle d'accès suivant permet com.example.MyShadowReactiveComponent
au client de recevoir des messages sur le /update/delta
sujet de l'ombre de périphérique classique et de l'ombre nommée myNamedShadow
sur chaque périphérique principal qui exécute le composant.
{
"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"
]
}
}
}
}
Exemple : autoriser un périphérique à cœur unique à réagir aux modifications de l'état fantôme local
L'exemple de politique de contrôle d'accès suivant permet com.example.MyShadowReactiveComponent
au client de recevoir des messages sur le /update/delta
sujet correspondant à l'ombre classique de l'appareil et à l'ombre nommée myNamedShadow
pour l'appareilMyThingName
.
{
"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
Obtenez l'ombre d'un objet spécifique.
Demande
La demande de cette opération comporte les paramètres suivants :
thingName
(Python :thing_name
)-
Nom de l'objet.
Type :
string
shadowName
(Python :shadow_name
)-
Nom du shadow. Pour spécifier l'ombre classique de l'objet, définissez ce paramètre sur une chaîne vide (
""
).Avertissement
Le AWS IoT Greengrass service utilise le
AWSManagedGreengrassV2Deployment
nom shadow pour gérer les déploiements qui ciblent des appareils principaux individuels. Cette ombre nommée est réservée à l'usage du AWS IoT Greengrass service. Ne mettez pas à jour ou ne supprimez pas cette ombre nommée.Type :
string
Réponse
La réponse de cette opération contient les informations suivantes :
payload
-
Le document d'état de réponse sous forme de blob.
Type :
object
qui contient les informations suivantes :state
-
Les informations sur l'état.
Cet objet contient les informations suivantes.
desired
-
Les propriétés d'état et les valeurs dont la mise à jour est demandée dans l'appareil.
Type :
map
de paires clé-valeur reported
-
Les propriétés d'état et les valeurs signalées par l'appareil.
Type :
map
de paires clé-valeur delta
-
Différence entre les propriétés et valeurs d'état souhaitées et signalées. Cette propriété n'est présente que si les
reported
étatsdesired
et sont différents.Type :
map
de paires clé-valeur
metadata
-
Les horodatages de chaque attribut dans les
reported
sectionsdesired
et afin que vous puissiez déterminer quand l'état a été mis à jour.Type :
string
timestamp
-
L'époque, la date et l'heure auxquelles la réponse a été générée.
Type :
integer
clientToken
(Python :clientToken
)-
Le jeton utilisé pour faire correspondre la demande et la réponse correspondante
Type :
string
version
-
Version du document fantôme local.
Type :
integer
Erreurs
Cette opération peut renvoyer les erreurs suivantes.
InvalidArgumentsError
-
Le service parallèle local n'est pas en mesure de valider les paramètres de la demande. Cela peut se produire si la demande contient du JSON mal formé ou des caractères non pris en charge.
ResourceNotFoundError
-
Le document parallèle local demandé est introuvable.
ServiceError
-
Une erreur de service interne s'est produite ou le nombre de demandes adressées au service IPC a dépassé les limites spécifiées dans les paramètres de
maxTotalLocalRequestsRate
configurationmaxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager. -
La politique d'autorisation du composant n'inclut pas les autorisations requises pour cette opération.
Exemples
Les exemples suivants montrent comment appeler cette opération dans le code de composant personnalisé.
Exemple : Get a thing Shadow
Note
Cet exemple utilise une IPCUtils
classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour de plus amples informations, veuillez consulter Connectez-vous au service 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
Mettez à jour l'ombre pour l'objet spécifié. Si aucune ombre n'existe, une ombre est créée.
Demande
La demande de cette opération comporte les paramètres suivants :
thingName
(Python :thing_name
)-
Nom de l'objet.
Type :
string
shadowName
(Python :shadow_name
)-
Nom du shadow. Pour spécifier l'ombre classique de l'objet, définissez ce paramètre sur une chaîne vide (
""
).Avertissement
Le AWS IoT Greengrass service utilise le
AWSManagedGreengrassV2Deployment
nom shadow pour gérer les déploiements qui ciblent des appareils principaux individuels. Cette ombre nommée est réservée à l'usage du AWS IoT Greengrass service. Ne mettez pas à jour ou ne supprimez pas cette ombre nommée.Type :
string
payload
-
Le document d'état de la demande sous forme de blob.
Type :
object
qui contient les informations suivantes :state
-
Informations d'état à mettre à jour. Cette opération IPC n'affecte que les champs spécifiés.
Cet objet contient les informations suivantes. Généralement, vous utiliserez la
desired
propriété ou lareported
propriété, mais pas les deux dans la même demande.desired
-
Les propriétés d'état et les valeurs dont la mise à jour est demandée dans l'appareil.
Type :
map
de paires clé-valeur reported
-
Les propriétés d'état et les valeurs signalées par l'appareil.
Type :
map
de paires clé-valeur
clientToken
(Python :client_token
)-
(Facultatif) Le jeton utilisé pour faire correspondre la demande et la réponse correspondante du jeton client.
Type :
string
version
-
(Facultatif) Version du document fantôme local à mettre à jour. Le service parallèle traite la mise à jour uniquement si la version spécifiée correspond à la dernière version dont il dispose.
Type :
integer
Réponse
La réponse de cette opération contient les informations suivantes :
payload
-
Le document d'état de réponse sous forme de blob.
Type :
object
qui contient les informations suivantes :state
-
Les informations sur l'état.
Cet objet contient les informations suivantes.
desired
-
Les propriétés d'état et les valeurs dont la mise à jour est demandée dans l'appareil.
Type :
map
de paires clé-valeur reported
-
Les propriétés d'état et les valeurs signalées par l'appareil.
Type :
map
de paires clé-valeur delta
-
Les propriétés d'état et les valeurs signalées par l'appareil.
Type :
map
de paires clé-valeur
metadata
-
Les horodatages de chaque attribut dans les
reported
sectionsdesired
et afin que vous puissiez déterminer quand l'état a été mis à jour.Type :
string
timestamp
-
L'époque, la date et l'heure auxquelles la réponse a été générée.
Type :
integer
clientToken
(Python :client_token
)-
Le jeton utilisé pour faire correspondre la demande et la réponse correspondante.
Type :
string
version
-
Version du document fantôme local une fois la mise à jour terminée.
Type :
integer
Erreurs
Cette opération peut renvoyer les erreurs suivantes.
ConflictError
-
Le service fantôme local a rencontré un conflit de version lors de l'opération de mise à jour. Cela se produit lorsque la version de la charge utile de la demande ne correspond pas à la version du dernier document parallèle local disponible.
InvalidArgumentsError
-
Le service parallèle local n'est pas en mesure de valider les paramètres de la demande. Cela peut se produire si la demande contient du JSON mal formé ou des caractères non pris en charge.
Une valeur valide
payload
possède les propriétés suivantes :-
Le
state
nœud existe et est un objet qui contient les informationsreported
d'étatdesired
ou. -
Les
reported
nœudsdesired
et sont soit des objets, soit des nœuds nuls. Au moins l'un de ces objets doit contenir des informations d'état valides. -
La profondeur des
reported
objetsdesired
et ne peut pas dépasser huit nœuds. -
La longueur de la
clientToken
valeur ne peut pas dépasser 64 caractères. -
La
version
valeur doit être1
ou supérieure.
-
ServiceError
-
Une erreur de service interne s'est produite ou le nombre de demandes adressées au service IPC a dépassé les limites spécifiées dans les paramètres de
maxTotalLocalRequestsRate
configurationmaxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager. -
La politique d'autorisation du composant n'inclut pas les autorisations requises pour cette opération.
Exemples
Les exemples suivants montrent comment appeler cette opération dans le code de composant personnalisé.
Exemple : mettre à jour un objet (shadow)
Note
Cet exemple utilise une IPCUtils
classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour de plus amples informations, veuillez consulter Connectez-vous au service 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
Supprime le shadow de l'objet spécifié.
À partir de la version 2.0.4 du gestionnaire d'ombres, la suppression d'une ombre augmente le numéro de version. Par exemple, lorsque vous supprimez l'ombre MyThingShadow
dans la version 1, la version de l'ombre supprimée est 2. Si vous recréez ensuite une ombre portant ce nomMyThingShadow
, la version de cette ombre est 3.
Demande
La demande de cette opération comporte les paramètres suivants :
thingName
(Python :thing_name
)-
Nom de l'objet.
Type :
string
shadowName
(Python :shadow_name
)-
Nom du shadow. Pour spécifier l'ombre classique de l'objet, définissez ce paramètre sur une chaîne vide (
""
).Avertissement
Le AWS IoT Greengrass service utilise le
AWSManagedGreengrassV2Deployment
nom shadow pour gérer les déploiements qui ciblent des appareils principaux individuels. Cette ombre nommée est réservée à l'usage du AWS IoT Greengrass service. Ne mettez pas à jour ou ne supprimez pas cette ombre nommée.Type :
string
Réponse
La réponse de cette opération contient les informations suivantes :
payload
-
Document d'état de réponse vide.
Erreurs
Cette opération peut renvoyer les erreurs suivantes.
InvalidArgumentsError
-
Le service parallèle local n'est pas en mesure de valider les paramètres de la demande. Cela peut se produire si la demande contient du JSON mal formé ou des caractères non pris en charge.
ResourceNotFoundError
-
Le document parallèle local demandé est introuvable.
ServiceError
-
Une erreur de service interne s'est produite ou le nombre de demandes adressées au service IPC a dépassé les limites spécifiées dans les paramètres de
maxTotalLocalRequestsRate
configurationmaxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager. -
La politique d'autorisation du composant n'inclut pas les autorisations requises pour cette opération.
Exemples
Les exemples suivants montrent comment appeler cette opération dans le code de composant personnalisé.
Exemple : supprimer une ombre d'objet
Note
Cet exemple utilise une IPCUtils
classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour de plus amples informations, veuillez consulter Connectez-vous au service 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
Répertoriez les ombres nommées pour l'objet spécifié.
Demande
La demande de cette opération comporte les paramètres suivants :
thingName
(Python :thing_name
)-
Nom de l'objet.
Type :
string
pageSize
(Python :page_size
)-
(Facultatif) Le nombre de noms fictifs à renvoyer lors de chaque appel.
Type :
integer
Par défaut: 25
Maximum : 100
nextToken
(Python :next_token
)-
(Facultatif) Le jeton permettant de récupérer le prochain ensemble de résultats. Cette valeur est renvoyée sur les résultats paginés et est utilisée dans l'appel qui renvoie la page suivante.
Type :
string
Réponse
La réponse de cette opération contient les informations suivantes :
results
-
La liste des noms des ombres.
Type :
array
timestamp
-
(Facultatif) Date et heure auxquelles la réponse a été générée.
Type :
integer
nextToken
(Python :next_token
)-
(Facultatif) La valeur du jeton à utiliser dans les demandes paginées pour récupérer la page suivante de la séquence. Ce jeton n'est pas présent lorsqu'il n'y a plus de noms d'ombres à renvoyer.
Type :
string
Note
Si le format de page demandé correspond exactement au nombre de noms d'ombres dans la réponse, ce jeton est présent ; toutefois, lorsqu'il est utilisé, il renvoie une liste vide.
Erreurs
Cette opération peut renvoyer les erreurs suivantes.
InvalidArgumentsError
-
Le service parallèle local n'est pas en mesure de valider les paramètres de la demande. Cela peut se produire si la demande contient du JSON mal formé ou des caractères non pris en charge.
ResourceNotFoundError
-
Le document parallèle local demandé est introuvable.
ServiceError
-
Une erreur de service interne s'est produite ou le nombre de demandes adressées au service IPC a dépassé les limites spécifiées dans les paramètres de
maxTotalLocalRequestsRate
configurationmaxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager. -
La politique d'autorisation du composant n'inclut pas les autorisations requises pour cette opération.
Exemples
Les exemples suivants montrent comment appeler cette opération dans le code de composant personnalisé.
Exemple : répertorier un objet nommé ombres
Note
Cet exemple utilise une IPCUtils
classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour de plus amples informations, veuillez consulter Connectez-vous au service 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());
}
}