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.
Interagissez avec les ombres locales
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 service IPC de publication/abonnement pour vous abonner à des événements fantômes. Pour plus d'informations sur l'utilisation du service de publication/d'abonnement, consultez le. Publier/souscrire des messages locaux
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.
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 IPC opérations.
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 |
aws.greengrass#GetThingShadow
|
Permet à un composant de récupérer l'ombre d'un objet.
|
L'une des chaînes suivantes :
-
$aws/things/thingName /shadow/ , pour permettre l'accès à l'ombre classique de l'appareil.
-
$aws/things/thingName /shadow/name/shadowName , pour autoriser l'accès à une ombre nommée.
-
* pour permettre l'accès à toutes les ombres.
|
aws.greengrass#UpdateThingShadow
|
Permet à un composant de mettre à jour l'ombre d'un objet.
|
L'une des chaînes suivantes :
-
$aws/things/thingName /shadow/ , pour permettre l'accès à l'ombre classique de l'appareil.
-
$aws/things/thingName /shadow/name/shadowName , pour autoriser l'accès à une ombre nommée.
-
* pour permettre l'accès à toutes les ombres.
|
aws.greengrass#DeleteThingShadow
|
Permet à un composant de supprimer l'ombre d'un objet.
|
L'une des chaînes suivantes :
-
$aws/things/thingName /shadow/ , pour permettre l'accès au shadow classique de l'appareil
-
$aws/things/thingName /shadow/name/shadowName , pour autoriser l'accès à une ombre nommée
-
* , pour permettre l'accès à toutes les ombres.
|
aws.greengrass#ListNamedShadowsForThing
|
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.
* À utiliser pour autoriser l'accès à tout.
|
Identifiant du service IPC : aws.greengrass.ipc.pubsub
Opération |
Description |
Ressources |
aws.greengrass#SubscribeToTopic
|
Permet à un composant de s'abonner à des messages pour les sujets que vous spécifiez.
|
L'une des chaînes de rubrique suivantes :
-
shadowTopicPrefix /get/accepted
-
shadowTopicPrefix /get/rejected
-
shadowTopicPrefix /delete/accepted
-
shadowTopicPrefix /delete/rejected
-
shadowTopicPrefix /update/accepted
-
shadowTopicPrefix /update/delta
-
shadowTopicPrefix /update/rejected
La valeur du préfixe de rubrique shadowTopicPrefix dépend du type d'ombre :
* À utiliser pour autoriser l'accès à toutes les rubriques.
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). # + Cette chaîne de rubrique prend en charge les caractères génériques des rubriques MQTT sous forme de caractères littéraux. Par exemple, si la politique d'autorisation d'un composant accorde l'accès à test/topic/# test/topic/# , le composant peut s'abonner, mais pastest/topic/filter .
|
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
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.
- JSON
-
{
"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"
]
}
}
}
}
- YAML
-
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
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
.
- JSON
-
{
"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*"
]
}
}
}
}
- YAML
-
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.
- JSON
-
{
"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"
]
}
}
}
}
- YAML
-
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
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.
- JSON
-
{
"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"
]
}
}
}
}
- YAML
-
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
.
- JSON
-
{
"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"
]
}
}
}
}
- YAML
-
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 (""
).
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
états desired
et sont différents.
Type : map
de paires clé-valeur
metadata
-
Les horodatages de chaque attribut dans les reported
sections desired
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
configuration maxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager.
UnauthorizedError
-
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é.
- Java (IPC client V1)
-
Exemple : Get a thing Shadow
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());
}
}
- Python (IPC client V1)
-
Exemple : Get a thing Shadow
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import GetThingShadowRequest
TIMEOUT = 10
def sample_get_thing_shadow_request(thingName, shadowName):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the GetThingShadow request
get_thing_shadow_request = GetThingShadowRequest()
get_thing_shadow_request.thing_name = thingName
get_thing_shadow_request.shadow_name = shadowName
# retrieve the GetThingShadow response after sending the request to the IPC server
op = ipc_client.new_get_thing_shadow()
op.activate(get_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
- JavaScript
-
Exemple : Get a thing Shadow
import {
GetThingShadowRequest
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc';
class GetThingShadow {
private ipcClient: greengrasscoreipc.Client;
private thingName: string;
private shadowName: string;
constructor() {
// Define args parameters here
this.thingName = "<define_your_own_thingName>";
this.shadowName = "<define_your_own_shadowName>";
this.bootstrap();
}
async bootstrap() {
try {
this.ipcClient = await getIpcClient();
} catch (err) {
// parse the error depending on your use cases
throw err
}
try {
await this.handleGetThingShadowOperation(this.thingName,
this.shadowName);
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
async handleGetThingShadowOperation(
thingName: string,
shadowName: string
) {
const request: GetThingShadowRequest = {
thingName: thingName,
shadowName: shadowName
};
const response = await this.ipcClient.getThingShadow(request);
}
}
export async function getIpcClient() {
try {
const ipcClient = greengrasscoreipc.createClient();
await ipcClient.connect()
.catch(error => {
// parse the error depending on your use cases
throw error;
});
return ipcClient
} catch (err) {
// parse the error depending on your use caseså
throw err
}
}
const startScript = new GetThingShadow();
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 (""
).
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 la reported
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
sections desired
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 informations reported
d'état desired
ou.
-
Les reported
nœuds desired
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
objets desired
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 être 1
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
configuration maxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager.
UnauthorizedError
-
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é.
- Java (IPC client V1)
-
Exemple : mettre à jour un objet (shadow)
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());
}
}
- Python (IPC client V1)
-
Exemple : mettre à jour un objet (shadow)
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import UpdateThingShadowRequest
TIMEOUT = 10
def sample_update_thing_shadow_request(thingName, shadowName, payload):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the UpdateThingShadow request
update_thing_shadow_request = UpdateThingShadowRequest()
update_thing_shadow_request.thing_name = thingName
update_thing_shadow_request.shadow_name = shadowName
update_thing_shadow_request.payload = payload
# retrieve the UpdateThingShadow response after sending the request to the IPC server
op = ipc_client.new_update_thing_shadow()
op.activate(update_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
...
# except ConflictError | UnauthorizedError | ServiceError
- JavaScript
-
Exemple : mettre à jour un objet (shadow)
import {
UpdateThingShadowRequest
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc';
class UpdateThingShadow {
private ipcClient: greengrasscoreipc.Client;
private thingName: string;
private shadowName: string;
private shadowDocumentStr: string;
constructor() {
// Define args parameters here
this.thingName = "<define_your_own_thingName>";
this.shadowName = "<define_your_own_shadowName>";
this.shadowDocumentStr = "<define_your_own_payload>";
this.bootstrap();
}
async bootstrap() {
try {
this.ipcClient = await getIpcClient();
} catch (err) {
// parse the error depending on your use cases
throw err
}
try {
await this.handleUpdateThingShadowOperation(
this.thingName,
this.shadowName,
this.shadowDocumentStr);
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
async handleUpdateThingShadowOperation(
thingName: string,
shadowName: string,
payloadStr: string
) {
const request: UpdateThingShadowRequest = {
thingName: thingName,
shadowName: shadowName,
payload: payloadStr
}
// make the UpdateThingShadow request
const response = await this.ipcClient.updateThingShadow(request);
}
}
export async function getIpcClient() {
try {
const ipcClient = greengrasscoreipc.createClient();
await ipcClient.connect()
.catch(error => {
// parse the error depending on your use cases
throw error;
});
return ipcClient
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
const startScript = new UpdateThingShadow();
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 (""
).
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
configuration maxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager.
UnauthorizedError
-
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é.
- Java (IPC client V1)
-
Exemple : supprimer une ombre d'objet
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());
}
}
- Python (IPC client V1)
-
Exemple : supprimer une ombre d'objet
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import DeleteThingShadowRequest
TIMEOUT = 10
def sample_delete_thing_shadow_request(thingName, shadowName):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the DeleteThingShadow request
delete_thing_shadow_request = DeleteThingShadowRequest()
delete_thing_shadow_request.thing_name = thingName
delete_thing_shadow_request.shadow_name = shadowName
# retrieve the DeleteThingShadow response after sending the request to the IPC server
op = ipc_client.new_delete_thing_shadow()
op.activate(delete_thing_shadow_request)
fut = op.get_response()
result = fut.result(TIMEOUT)
return result.payload
except InvalidArgumentsError as e:
# add error handling
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
- JavaScript
-
Exemple : supprimer une ombre d'objet
import {
DeleteThingShadowRequest
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc';
class DeleteThingShadow {
private ipcClient: greengrasscoreipc.Client;
private thingName: string;
private shadowName: string;
constructor() {
// Define args parameters here
this.thingName = "<define_your_own_thingName>";
this.shadowName = "<define_your_own_shadowName>";
this.bootstrap();
}
async bootstrap() {
try {
this.ipcClient = await getIpcClient();
} catch (err) {
// parse the error depending on your use cases
throw err
}
try {
await this.handleDeleteThingShadowOperation(this.thingName, this.shadowName)
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
async handleDeleteThingShadowOperation(thingName: string, shadowName: string) {
const request: DeleteThingShadowRequest = {
thingName: thingName,
shadowName: shadowName
}
// make the DeleteThingShadow request
const response = await this.ipcClient.deleteThingShadow(request);
}
}
export async function getIpcClient() {
try {
const ipcClient = greengrasscoreipc.createClient();
await ipcClient.connect()
.catch(error => {
// parse the error depending on your use cases
throw error;
});
return ipcClient
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
const startScript = new DeleteThingShadow();
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
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
configuration maxLocalRequestsPerSecondPerThing
et dans le composant Shadow Manager.
UnauthorizedError
-
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é.
- Java (IPC client V1)
-
Exemple : répertorier un objet nommé ombres
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());
}
}
- Python (IPC client V1)
-
Exemple : répertorier un objet nommé ombres
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import ListNamedShadowsForThingRequest
TIMEOUT = 10
def sample_list_named_shadows_for_thing_request(thingName, nextToken, pageSize):
try:
# set up IPC client to connect to the IPC server
ipc_client = awsiot.greengrasscoreipc.connect()
# create the ListNamedShadowsForThingRequest request
list_named_shadows_for_thing_request = ListNamedShadowsForThingRequest()
list_named_shadows_for_thing_request.thing_name = thingName
list_named_shadows_for_thing_request.next_token = nextToken
list_named_shadows_for_thing_request.page_size = pageSize
# retrieve the ListNamedShadowsForThingRequest response after sending the request to the IPC server
op = ipc_client.new_list_named_shadows_for_thing()
op.activate(list_named_shadows_for_thing_request)
fut = op.get_response()
list_result = fut.result(TIMEOUT)
# additional returned fields
timestamp = list_result.timestamp
next_token = result.next_token
named_shadow_list = list_result.results
return named_shadow_list, next_token, timestamp
except InvalidArgumentsError as e:
# add error handling
...
# except ResourceNotFoundError | UnauthorizedError | ServiceError
- JavaScript
-
Exemple : répertorier un objet nommé ombres
import {
ListNamedShadowsForThingRequest
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc';
class listNamedShadowsForThing {
private ipcClient: greengrasscoreipc.Client;
private thingName: string;
private pageSizeStr: string;
private nextToken: string;
constructor() {
// Define args parameters here
this.thingName = "<define_your_own_thingName>";
this.pageSizeStr = "<define_your_own_pageSize>";
this.nextToken = "<define_your_own_token>";
this.bootstrap();
}
async bootstrap() {
try {
this.ipcClient = await getIpcClient();
} catch (err) {
// parse the error depending on your use cases
throw err
}
try {
await this.handleListNamedShadowsForThingOperation(this.thingName,
this.nextToken, this.pageSizeStr);
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
async handleListNamedShadowsForThingOperation(
thingName: string,
nextToken: string,
pageSizeStr: string
) {
let request: ListNamedShadowsForThingRequest = {
thingName: thingName,
nextToken: nextToken,
};
if (pageSizeStr) {
request.pageSize = parseInt(pageSizeStr);
}
// make the ListNamedShadowsForThing request
const response = await this.ipcClient.listNamedShadowsForThing(request);
const shadowNames = response.results;
}
}
export async function getIpcClient(){
try {
const ipcClient = greengrasscoreipc.createClient();
await ipcClient.connect()
.catch(error => {
// parse the error depending on your use cases
throw error;
});
return ipcClient
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
const startScript = new listNamedShadowsForThing();