Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Interactúe con las sombras locales
Utilice el servicio IPC de sombra para interactuar con las sombras locales de un dispositivo. El dispositivo con el que elija interactuar puede ser su dispositivo principal o un dispositivo de cliente conectado.
Para utilizar estas operaciones de IPC, incluya el componente administrador de sombras como una dependencia en su componente personalizado. A continuación, puede utilizar las operaciones de IPC en sus componentes personalizados para interactuar con las sombras locales del dispositivo a través del administrador de sombras. Para permitir que los componentes personalizados reaccionen ante los cambios en los estados de sombras locales, también puede utilizar el servicio de publicación/suscripción de IPC para suscribirse a eventos de sombra. Para obtener más información acerca de cómo utilizar el servicio de publicación/suscripción, consulte Publicar/suscribir mensajes locales.
Versiones mínimas de SDK
En la siguiente tabla, se enumeran las versiones mínimas del SDK para dispositivos con AWS IoT que debe utilizar para interactuar con las sombras locales.
Autorización
Para utilizar el servicio IPC de sombra en un componente personalizado, debe definir políticas de autorización que permitan a su componente interactuar con las sombras. Para obtener información sobre cómo definir las políticas de autorización, consulte Autoriza a los componentes a realizar IPC operaciones.
Las políticas de autorización para la interacción con las sombra tienen las siguientes propiedades.
Identificador de servicio IPC: aws.greengrass.ShadowManager
Operación |
Descripción |
Recursos |
aws.greengrass#GetThingShadow
|
Permite que un componente recupere la sombra de un objeto.
|
Una de las siguientes cadenas:
-
$aws/things/thingName /shadow/ , para permitir el acceso a la sombra de dispositivo clásico.
-
$aws/things/thingName /shadow/name/shadowName , para permitir el acceso a una sombra con nombre.
-
* , para permitir el acceso a todas las sombras.
|
aws.greengrass#UpdateThingShadow
|
Permite que un componente actualice la sombra de un objeto.
|
Una de las siguientes cadenas:
-
$aws/things/thingName /shadow/ , para permitir el acceso a la sombra de dispositivo clásico.
-
$aws/things/thingName /shadow/name/shadowName , para permitir el acceso a una sombra con nombre.
-
* , para permitir el acceso a todas las sombras.
|
aws.greengrass#DeleteThingShadow
|
Permite a un componente eliminar la sombra de un objeto.
|
Una de las siguientes cadenas:
-
$aws/things/thingName /shadow/ , para permitir el acceso a la sombra de dispositivo clásico.
-
$aws/things/thingName /shadow/name/shadowName , para permitir el acceso a una sombra con nombre.
-
* , para permitir el acceso a todas las sombras.
|
aws.greengrass#ListNamedShadowsForThing
|
Permite que un componente recupere la lista de sombras con nombre de un objeto.
|
Cadena con el nombre de un objeto que permite acceder al objeto para enumerar sus sombras.
Se usa * para permitir el acceso a todos los objetos.
|
Identificador de servicio IPC: aws.greengrass.ipc.pubsub
Operación |
Descripción |
Recursos |
aws.greengrass#SubscribeToTopic
|
Permite que un componente se suscriba a los mensajes de los temas que especifique.
|
Una de las siguientes cadenas de temas:
-
shadowTopicPrefix /get/accepted
-
shadowTopicPrefix /get/rejected
-
shadowTopicPrefix /delete/accepted
-
shadowTopicPrefix /delete/rejected
-
shadowTopicPrefix /update/accepted
-
shadowTopicPrefix /update/delta
-
shadowTopicPrefix /update/rejected
El valor del prefijo del tema shadowTopicPrefix depende del tipo de sombra:
Se usa * para permitir el acceso a todos los temas.
En el núcleo de Greengrass versión 2.6.0 y versiones posteriores, puede suscribirse a temas que contengan comodines de temas MQTT (# y + ). Esta cadena de tema admite los comodines de los temas MQTT como caracteres literales. Por ejemplo, si la política de autorización de un componente permite el acceso a test/topic/# , el componente se puede suscribir a test/topic/# , pero no se puede suscribir a test/topic/filter .
|
Variables de receta en las políticas de autorización de sombras locales
Si usa la versión 2.6.0 o posterior del núcleo de Greengrass y establece la opción de configuración interpolateComponentConfiguration del núcleo de Greengrass en true
, puede usar la variable de receta {iot:thingName}
en las políticas de autorización. Esta característica le permite configurar una política de autorización única para un grupo de dispositivos principales, de forma que cada dispositivo principal solo pueda acceder a su propia sombra. Por ejemplo, puede permitir que un componente acceda al siguiente recurso para realizar operaciones de IPC de sombra.
$aws/things/{iot:thingName}/shadow/
Ejemplos de políticas de autorización
Puede consultar los siguientes ejemplos de políticas de autorización con el fin de configurar las políticas de autorización para sus componentes.
ejemplo Ejemplo: permitir que un grupo de dispositivos principales interactúe con las sombras locales
El siguiente ejemplo de política de autorización permite que el componente com.example.MyShadowInteractionComponent
interactúe con la sombra de dispositivo clásico y con la sombra con nombre myNamedShadow
del dispositivo principal que ejecuta el componente. Esta política también permite que este componente reciba mensajes sobre temas locales relacionados con estas sombras.
- 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
ejemplo Ejemplo: permitir que un grupo de dispositivos principales interactúe con sombra de dispositivo del cliente
El siguiente ejemplo de política de autorización permite que el componente com.example.MyShadowInteractionComponent
interactúe con todas las sombras de dispositivos de los dispositivos de cliente cuyos nombres comiencen con MyClientDevice
.
- 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*
ejemplo Ejemplo: permitir que un solo dispositivo principal interactúe con las sombras locales
El siguiente ejemplo de política de autorización permite que el componente com.example.MyShadowInteractionComponent
interactúe con la sombra de dispositivo clásico y con la sombra con nombre myNamedShadow
para el dispositivo MyThingName
. Esta política también permite que este componente reciba mensajes sobre temas locales relacionados con estas sombras.
- 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
ejemplo Ejemplo: permitir que un grupo de dispositivos principales reaccione a los cambios en el estado de la sombra local
El siguiente ejemplo de política de control de acceso permite personalizar com.example.MyShadowReactiveComponent
para recibir mensajes sobre el tema /update/delta
de la sombra de dispositivo clásico y de la sombra con nombre myNamedShadow
en cada dispositivo principal en el que se ejecute el componente.
- 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
ejemplo Ejemplo: permitir que un solo dispositivo principal reaccione a los cambios en el estado de la sombra local
El siguiente ejemplo de política de control de acceso permite personalizar com.example.MyShadowReactiveComponent
para recibir mensajes sobre el tema /update/delta
de la sombra de dispositivo clásico y de la sombra con nombre myNamedShadow
para el dispositivo MyThingName
.
- 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
Obtenga la sombra de objeto especificado.
Solicitud
Esta solicitud de operación tiene los siguientes parámetros:
thingName
(Python: thing_name
)
-
El nombre del objeto.
Tipo: string
shadowName
(Python: shadow_name
)
-
El nombre de la sombra. Para especificar la sombra clásica del objeto, defina este parámetro en una cadena vacía (""
).
El servicio de AWS IoT Greengrass usa el nombre de sombra AWSManagedGreengrassV2Deployment
para administrar las implementaciones que se dirigen a dispositivos principales individuales. Esta sombra con nombre está reservada para que la utilice el servicio de AWS IoT Greengrass. No actualice ni elimine esta sombra con nombre.
Tipo: string
Respuesta
Esta respuesta de operación contiene la siguiente información:
payload
-
El documento de estado de la respuesta en forma de blob.
Tipo: object
que contiene la siguiente información:
state
-
La información del estado.
Este objeto contiene la siguiente información:
desired
-
Las propiedades y los valores de estado que se solicitan actualizar en el dispositivo.
Tipo: map
de pares clave-valor
reported
-
Las propiedades y los valores de estado informados por el dispositivo.
Tipo: map
de pares clave-valor
delta
-
La diferencia entre las propiedades y los valores de estado deseados e informados. Esta propiedad solo está presente si los estados desired
y reported
son diferentes.
Tipo: map
de pares clave-valor
metadata
-
Las marcas temporales de cada atributo de las secciones desired
y reported
para que se pueda determinar cuándo se actualizó el estado.
Tipo: string
timestamp
-
La fecha y hora de inicio en que se generó la respuesta.
Tipo: integer
clientToken
(Python: clientToken
)
-
El token que se usa para hacer coincidir la solicitud y la respuesta correspondiente.
Tipo: string
version
-
La versión del documento de sombra local.
Tipo: integer
Errores
Esta operación puede devolver los siguientes errores.
InvalidArgumentsError
-
El servicio de sombra local no puede validar los parámetros de la solicitud. Esto puede ocurrir si la solicitud contiene un formato incorrecto de JSON o caracteres no admitidos.
ResourceNotFoundError
-
No se encuentra el documento de sombra local solicitado.
ServiceError
-
Se ha producido un error de servicio interno o la cantidad de solicitudes al servicio de IPC ha superado los límites especificados en los parámetros de configuración de maxLocalRequestsPerSecondPerThing
y maxTotalLocalRequestsRate
del componente del administrador de sombra.
UnauthorizedError
-
La política de autorización del componente no incluye los permisos necesarios para esta operación.
Ejemplos
En los ejemplos siguientes, se muestra cómo llamar a esta operación en código de componente personalizado.
- Java (IPC client V1)
-
ejemplo Ejemplo: obtener la sombra de un objeto
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)
-
ejemplo Ejemplo: obtener la sombra de un objeto
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
-
ejemplo Ejemplo: obtener la sombra de un objeto
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
Actualice la sombra del objeto especificado. Si la sombra no existe, se crea una.
Solicitud
Esta solicitud de operación tiene los siguientes parámetros:
thingName
(Python: thing_name
)
-
El nombre del objeto.
Tipo: string
shadowName
(Python: shadow_name
)
-
El nombre de la sombra. Para especificar la sombra clásica del objeto, defina este parámetro en una cadena vacía (""
).
El servicio de AWS IoT Greengrass usa el nombre de sombra AWSManagedGreengrassV2Deployment
para administrar las implementaciones que se dirigen a dispositivos principales individuales. Esta sombra con nombre está reservada para que la utilice el servicio de AWS IoT Greengrass. No actualice ni elimine esta sombra con nombre.
Tipo: string
payload
-
El documento del estado de solicitud es un blob.
Tipo: object
que contiene la siguiente información:
state
-
La información del estado que se va a actualizar. Esta operación de IPC afecta únicamente a los campos especificados.
Este objeto contiene la siguiente información: Normalmente, utilizará la propiedad desired
o la propiedad reported
, pero no ambas en la misma solicitud.
desired
-
Las propiedades y los valores de estado que se solicitan actualizar en el dispositivo.
Tipo: map
de pares clave-valor
reported
-
Las propiedades y los valores de estado informados por el dispositivo.
Tipo: map
de pares clave-valor
clientToken
(Python: client_token
)
-
(Opcional) El token que se usa para hacer coincidir la solicitud y la respuesta correspondiente con el token del cliente.
Tipo: string
version
-
(Opcional) La versión del documento de sombra local que se va a actualizar. El servicio de sombra procesa la actualización solo si la versión especificada coincide con la versión más reciente que tiene.
Tipo: integer
Respuesta
Esta respuesta de operación contiene la siguiente información:
payload
-
El documento de estado de la respuesta en forma de blob.
Tipo: object
que contiene la siguiente información:
state
-
La información del estado.
Este objeto contiene la siguiente información:
desired
-
Las propiedades y los valores de estado que se solicitan actualizar en el dispositivo.
Tipo: map
de pares clave-valor
reported
-
Las propiedades y los valores de estado informados por el dispositivo.
Tipo: map
de pares clave-valor
delta
-
Las propiedades y los valores de estado informados por el dispositivo.
Tipo: map
de pares clave-valor
metadata
-
Las marcas temporales de cada atributo de las secciones desired
y reported
para que se pueda determinar cuándo se actualizó el estado.
Tipo: string
timestamp
-
La fecha y hora de inicio en que se generó la respuesta.
Tipo: integer
clientToken
(Python: client_token
)
-
El token que se usa para hacer coincidir la solicitud y la respuesta correspondiente.
Tipo: string
version
-
La versión del documento de sombra local una vez finalizada la actualización.
Tipo: integer
Errores
Esta operación puede devolver los siguientes errores.
ConflictError
-
El servicio de sombra local detectó un conflicto de versiones durante la operación de actualización. Esto ocurre cuando la versión de la carga útil de la solicitud no coincide con la versión del último documento de sombra local disponible.
InvalidArgumentsError
-
El servicio de sombra local no puede validar los parámetros de la solicitud. Esto puede ocurrir si la solicitud contiene un formato incorrecto de JSON o caracteres no admitidos.
Un payload
válido incluye las siguientes propiedades:
-
El nodo state
existe y es un objeto que contiene la información de estado desired
o reported
.
-
Los nodos desired
y reported
son objetos o nulos. Al menos uno de estos objetos debe contener información de estado válida.
-
La profundidad de los objetos desired
y reported
no puede superar los ocho nodos.
-
La longitud del valor clientToken
no puede superar los 64 caracteres.
-
El valor version
debe ser 1
o superior.
ServiceError
-
Se ha producido un error de servicio interno o la cantidad de solicitudes al servicio de IPC ha superado los límites especificados en los parámetros de configuración de maxLocalRequestsPerSecondPerThing
y maxTotalLocalRequestsRate
del componente del administrador de sombra.
UnauthorizedError
-
La política de autorización del componente no incluye los permisos necesarios para esta operación.
Ejemplos
En los ejemplos siguientes, se muestra cómo llamar a esta operación en código de componente personalizado.
- Java (IPC client V1)
-
ejemplo Ejemplo: actualizar una sombra de objeto
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)
-
ejemplo Ejemplo: actualizar una sombra de objeto
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
-
ejemplo Ejemplo: actualizar una sombra de objeto
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
Elimina la sombra de objeto especificado.
A partir de la versión 2.0.4 de administrador de sombra, cuando se elimina una sombra se incrementa el número de versión. Por ejemplo, si elimina la sombra MyThingShadow
en la versión 1, la versión de la sombra eliminada es 2. Si después vuelve a crear una sombra con el nombre MyThingShadow
, la versión de esa sombra es 3.
Solicitud
Esta solicitud de operación tiene los siguientes parámetros:
thingName
(Python: thing_name
)
-
El nombre del objeto.
Tipo: string
shadowName
(Python: shadow_name
)
-
El nombre de la sombra. Para especificar la sombra clásica del objeto, defina este parámetro en una cadena vacía (""
).
El servicio de AWS IoT Greengrass usa el nombre de sombra AWSManagedGreengrassV2Deployment
para administrar las implementaciones que se dirigen a dispositivos principales individuales. Esta sombra con nombre está reservada para que la utilice el servicio de AWS IoT Greengrass. No actualice ni elimine esta sombra con nombre.
Tipo: string
Respuesta
Esta respuesta de operación contiene la siguiente información:
payload
-
Un documento de estado de respuesta vacío.
Errores
Esta operación puede devolver los siguientes errores.
InvalidArgumentsError
-
El servicio de sombra local no puede validar los parámetros de la solicitud. Esto puede ocurrir si la solicitud contiene un formato incorrecto de JSON o caracteres no admitidos.
ResourceNotFoundError
-
No se encuentra el documento de sombra local solicitado.
ServiceError
-
Se ha producido un error de servicio interno o la cantidad de solicitudes al servicio de IPC ha superado los límites especificados en los parámetros de configuración de maxLocalRequestsPerSecondPerThing
y maxTotalLocalRequestsRate
del componente del administrador de sombra.
UnauthorizedError
-
La política de autorización del componente no incluye los permisos necesarios para esta operación.
Ejemplos
En los ejemplos siguientes, se muestra cómo llamar a esta operación en código de componente personalizado.
- Java (IPC client V1)
-
ejemplo Ejemplo: eliminar una sombra de objeto
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)
-
ejemplo Ejemplo: eliminar una sombra de objeto
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
-
ejemplo Ejemplo: eliminar una sombra de objeto
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
Enumera las sombras con nombre del objeto especificado.
Solicitud
Esta solicitud de operación tiene los siguientes parámetros:
thingName
(Python: thing_name
)
-
El nombre del objeto.
Tipo: string
pageSize
(Python: page_size
)
-
(Opcional) La cantidad de nombres de sombra que se devuelve en cada llamada.
Tipo: integer
Predeterminado: 25
Máximo: 100
nextToken
(Python: next_token
)
-
(Opcional) El token para recuperar el siguiente grupo de resultados. Este valor se devuelve en los resultados paginados y se utiliza en la llamada que devuelve la página siguiente.
Tipo: string
Respuesta
Esta respuesta de operación contiene la siguiente información:
results
-
La lista de sombras con nombre.
Tipo: array
timestamp
-
(Opcional) La fecha y hora en que se generó la respuesta.
Tipo: integer
nextToken
(Python: next_token
)
-
(Opcional) El valor del token que se utilizará en las solicitudes paginadas para recuperar la siguiente página de la secuencia. Este token no está presente cuando no hay más sombras con nombre que devolver.
Tipo: string
Si el tamaño de página solicitado coincide exactamente con la cantidad de nombres de sombra de la respuesta, entonces este token está presente; sin embargo, cuando se usa, devuelve una lista vacía.
Errores
Esta operación puede devolver los siguientes errores.
InvalidArgumentsError
-
El servicio de sombra local no puede validar los parámetros de la solicitud. Esto puede ocurrir si la solicitud contiene un formato incorrecto de JSON o caracteres no admitidos.
ResourceNotFoundError
-
No se encuentra el documento de sombra local solicitado.
ServiceError
-
Se ha producido un error de servicio interno o la cantidad de solicitudes al servicio de IPC ha superado los límites especificados en los parámetros de configuración de maxLocalRequestsPerSecondPerThing
y maxTotalLocalRequestsRate
del componente del administrador de sombra.
UnauthorizedError
-
La política de autorización del componente no incluye los permisos necesarios para esta operación.
Ejemplos
En los ejemplos siguientes, se muestra cómo llamar a esta operación en código de componente personalizado.
- Java (IPC client V1)
-
ejemplo Ejemplo: enumerar las sombras con nombre de un objeto
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)
-
ejemplo Ejemplo: enumerar las sombras con nombre de un objeto
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
-
ejemplo Ejemplo: enumerar las sombras con nombre de un objeto
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();