Interagissez avec les ombres locales - AWS IoT Greengrass

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

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.

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

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 :

  • Ombre classique : $aws/things/thingName/shadow

  • Ombre nommée : $aws/things/thingName/shadow/name/shadowName

*À 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
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.

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.

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.

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

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 ("").

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 é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
Note

Cet exemple utilise une IPCUtils classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour plus d’informations, consultez 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()); } }
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 ("").

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 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)
Note

Cet exemple utilise une IPCUtils classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour plus d’informations, consultez 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()); } }
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 ("").

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 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
Note

Cet exemple utilise une IPCUtils classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour plus d’informations, consultez 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()); } }
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

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 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
Note

Cet exemple utilise une IPCUtils classe pour créer une connexion au service AWS IoT Greengrass Core IPC. Pour plus d’informations, consultez 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()); } }
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();