Interaja com sombras locais - AWS IoT Greengrass

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Interaja com sombras locais

Use o serviço IPC de sombra para interagir com sombras locais em um dispositivo. O dispositivo com o qual você escolhe interagir pode ser seu dispositivo principal ou um dispositivo cliente conectado.

Para usar essas operações de IPC, inclua o componente do gerenciador de sombras como uma dependência em seu componente personalizado. Em seguida, você pode usar as operações de IPC em seus componentes personalizados para interagir com sombras locais em seu dispositivo por meio do gerenciador de sombras. Para permitir que componentes personalizados reajam às mudanças nos estados de sombra locais, você também pode usar o serviço IPC de publicação/assinatura para assinar eventos paralelos. Para obter mais informações sobre como usar o serviço de publicação/assinatura, consulte o. Publique/assine mensagens locais

nota

Para permitir que um dispositivo principal interaja com as sombras do dispositivo cliente, você também deve configurar e implantar o componente de ponte MQTT. Para obter mais informações, consulte Habilitar o shadow manager para se comunicar com dispositivos clientes.

Versões mínimas do SDK

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para interagir com sombras locais.

Autorização

Para usar o serviço IPC paralelo em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente interaja com sombras. Para obter informações sobre a definição de políticas de autorização, consulteAutorize componentes a realizar operações de IPC.

As políticas de autorização para interação paralela têm as seguintes propriedades.

Identificador de serviço IPC: aws.greengrass.ShadowManager

Operation Descrição Recursos

aws.greengrass#GetThingShadow

Permite que um componente recupere a sombra de uma coisa.

Uma das seguintes sequências de caracteres:

  • $aws/things/thingName/shadow/, para permitir o acesso à sombra clássica do dispositivo.

  • $aws/things/thingName/shadow/name/shadowName, para permitir o acesso a uma sombra nomeada.

  • *para permitir o acesso a todas as sombras.

aws.greengrass#UpdateThingShadow

Permite que um componente atualize a sombra de uma coisa.

Uma das seguintes sequências de caracteres:

  • $aws/things/thingName/shadow/, para permitir o acesso à sombra clássica do dispositivo.

  • $aws/things/thingName/shadow/name/shadowName, para permitir o acesso a uma sombra nomeada.

  • *para permitir o acesso a todas as sombras.

aws.greengrass#DeleteThingShadow

Permite que um componente exclua a sombra de uma coisa.

Uma das seguintes sequências de caracteres:

  • $aws/things/thingName/shadow/, para permitir o acesso à sombra clássica do dispositivo

  • $aws/things/thingName/shadow/name/shadowName, para permitir o acesso a uma sombra nomeada

  • *, para permitir o acesso a todas as sombras.

aws.greengrass#ListNamedShadowsForThing

Permite que um componente recupere a lista de sombras nomeadas de uma coisa.

Uma string de nome de coisa que permite acessar a coisa para listar suas sombras.

Use * para permitir o acesso a todas as coisas.

Identificador de serviço IPC: aws.greengrass.ipc.pubsub

Operation Descrição Recursos

aws.greengrass#SubscribeToTopic

Permite que um componente assine mensagens para os tópicos que você especificar.

Uma das seguintes sequências de tópicos:

  • shadowTopicPrefix/get/accepted

  • shadowTopicPrefix/get/rejected

  • shadowTopicPrefix/delete/accepted

  • shadowTopicPrefix/delete/rejected

  • shadowTopicPrefix/update/accepted

  • shadowTopicPrefix/update/delta

  • shadowTopicPrefix/update/rejected

O valor do prefixo shadowTopicPrefix do tópico depende do tipo de sombra:

  • Sombra clássica: $aws/things/thingName/shadow

  • Sombra nomeada: $aws/things/thingName/shadow/name/shadowName

Use * para permitir o acesso a todos os tópicos.

No Greengrass nucleus v2.6.0 e versões posteriores, você pode se inscrever em tópicos que contêm curingas de tópicos do MQTT (e). # + Essa string de tópico suporta curingas de tópico MQTT como caracteres literais. Por exemplo, se a política de autorização de um componente conceder acesso atest/topic/#, o componente pode se inscrevertest/topic/#, mas não pode assinartest/topic/filter.

Variáveis de receita nas políticas locais de autorização paralela

Se você usar a versão 2.6.0 ou posterior do núcleo do Greengrass e definir a opção de interpolateComponentConfigurationconfiguração do núcleo do Greengrass comotrue, poderá usar a variável de receita nas políticas de autorização. {iot:thingName} Esse recurso permite que você configure uma única política de autorização para um grupo de dispositivos principais, em que cada dispositivo principal pode acessar somente sua própria sombra. Por exemplo, você pode permitir que um componente acesse o seguinte recurso para operações de IPC paralelas.

$aws/things/{iot:thingName}/shadow/

Exemplos de políticas de autorização

Você pode consultar os seguintes exemplos de políticas de autorização para ajudá-lo a configurar políticas de autorização para seus componentes.

exemplo Exemplo: permitir que um grupo de dispositivos principais interaja com sombras locais
Importante

Este exemplo usa um recurso que está disponível para a versão 2.6.0 e posterior do componente núcleo do Greengrass. O Greengrass nucleus v2.6.0 adiciona suporte para a maioria das variáveis de receita, como configurações de componentes. {iot:thingName} Para ativar esse recurso, defina a opção de interpolateComponentConfigurationconfiguração do núcleo Greengrass como. true Para ver um exemplo que funciona para todas as versões do núcleo do Greengrass, consulte o exemplo de política de autorização para um único dispositivo central.

O exemplo de política de autorização a seguir permite que o componente com.example.MyShadowInteractionComponent interaja com a sombra clássica do dispositivo e a sombra myNamedShadow nomeada do dispositivo principal que executa o componente. Essa política também permite que esse componente receba mensagens sobre tópicos locais para essas 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
exemplo Exemplo: permitir que um grupo de dispositivos principais interaja com as sombras do dispositivo cliente

O exemplo de política de autorização a seguir permite que com.example.MyShadowInteractionComponent o componente interaja com todas as sombras de dispositivos clientes cujos nomes começam comMyClientDevice.

nota

Para permitir que um dispositivo principal interaja com as sombras do dispositivo cliente, você também deve configurar e implantar o componente de ponte MQTT. Para obter mais informações, consulte Habilitar o shadow manager para se comunicar com dispositivos clientes.

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*
exemplo Exemplo: permitir que um dispositivo de núcleo único interaja com sombras locais

O exemplo de política de autorização a seguir permite que o componente com.example.MyShadowInteractionComponent interaja com a sombra clássica do dispositivo e a sombra myNamedShadow nomeada do dispositivoMyThingName. Essa política também permite que esse componente receba mensagens sobre tópicos locais para essas 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
exemplo Exemplo: permitir que um grupo de dispositivos principais reaja às mudanças locais do estado de sombra
Importante

Este exemplo usa um recurso que está disponível para a versão 2.6.0 e posterior do componente núcleo do Greengrass. O Greengrass nucleus v2.6.0 adiciona suporte para a maioria das variáveis de receita, como configurações de componentes. {iot:thingName} Para ativar esse recurso, defina a opção de interpolateComponentConfigurationconfiguração do núcleo Greengrass como. true Para ver um exemplo que funciona para todas as versões do núcleo do Greengrass, consulte o exemplo de política de autorização para um único dispositivo central.

O exemplo de política de controle de acesso a seguir permite que o cliente receba mensagens sobre o /update/delta tópico da sombra clássica do dispositivo e da sombra nomeada myNamedShadow em cada dispositivo principal que executa o componente. com.example.MyShadowReactiveComponent

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
exemplo Exemplo: permitir que um dispositivo de núcleo único reaja às mudanças locais do estado de sombra

O exemplo de política de controle de acesso com.example.MyShadowReactiveComponent a seguir permite que o cliente receba mensagens sobre o /update/delta tópico da sombra clássica do dispositivo e a sombra myNamedShadow nomeada do dispositivoMyThingName.

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

Obtenha a sombra de uma coisa específica.

Solicitação

A solicitação dessa operação tem os seguintes parâmetros:

thingName(Python:) thing_name

O nome da coisa.

Tipo: string

shadowName(Python:) shadow_name

O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia ("").

Atenção

O AWS IoT Greengrass serviço usa a sombra AWSManagedGreengrassV2Deployment nomeada para gerenciar implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso pelo AWS IoT Greengrass serviço. Não atualize nem exclua essa sombra nomeada.

Tipo: string

Resposta

A resposta dessa operação tem as seguintes informações:

payload

O documento de estado da resposta como um blob.

Tipo: object que contém as seguintes informações:

state

As informações do estado.

Esse objeto contém as seguintes informações.

desired

As propriedades e os valores do estado solicitados para serem atualizados no dispositivo.

Tipo: map de pares de valores-chave

reported

As propriedades e os valores do estado relatados pelo dispositivo.

Tipo: map de pares de valores-chave

delta

A diferença entre as propriedades e valores do estado desejado e relatado. Essa propriedade está presente somente se os reported estados desired e forem diferentes.

Tipo: map de pares de valores-chave

metadata

Os registros de data e hora de cada atributo nas reported seções desired e para que você possa determinar quando o estado foi atualizado.

Tipo: string

timestamp

A data e a hora da época em que a resposta foi gerada.

Tipo: integer

clientToken(Python:) clientToken

O token usado para corresponder à solicitação e à resposta correspondente

Tipo: string

version

A versão do documento paralelo local.

Tipo: integer

Erros

Essa operação pode retornar os seguintes erros.

InvalidArgumentsError

O serviço paralelo local não consegue validar os parâmetros da solicitação. Isso pode ocorrer se a solicitação contiver caracteres JSON malformados ou sem suporte.

ResourceNotFoundError

O documento paralelo local solicitado não foi encontrado.

ServiceError

Ocorreu um erro de serviço interno ou o número de solicitações ao serviço IPC excedeu os limites especificados nos parâmetros de maxTotalLocalRequestsRate configuração maxLocalRequestsPerSecondPerThing e no componente do gerenciador de sombra.

UnauthorizedError

A política de autorização do componente não inclui as permissões necessárias para essa operação.

Exemplos

Os exemplos a seguir demonstram como chamar essa operação no código de componente personalizado.

Java (IPC client V1)
exemplo Exemplo: pegue uma sombra
nota

Este exemplo usa uma IPCUtils classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para ter mais informações, consulte Conecte-se ao serviço 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)
exemplo Exemplo: pegue uma sombra
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
exemplo Exemplo: pegue uma sombra
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

Atualize a sombra para a coisa especificada. Se uma sombra não existe, uma é criada.

Solicitação

A solicitação dessa operação tem os seguintes parâmetros:

thingName(Python:) thing_name

O nome da coisa.

Tipo: string

shadowName(Python:) shadow_name

O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia ("").

Atenção

O AWS IoT Greengrass serviço usa a sombra AWSManagedGreengrassV2Deployment nomeada para gerenciar implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso pelo AWS IoT Greengrass serviço. Não atualize nem exclua essa sombra nomeada.

Tipo: string

payload

O documento de estado da solicitação como um blob.

Tipo: object que contém as seguintes informações:

state

As informações do estado a serem atualizadas. Essa operação de IPC afeta somente os campos especificados.

Esse objeto contém as seguintes informações. Normalmente, você usará a desired propriedade ou a reported propriedade, mas não as duas na mesma solicitação.

desired

As propriedades e os valores do estado solicitados para serem atualizados no dispositivo.

Tipo: map de pares de valores-chave

reported

As propriedades e os valores do estado relatados pelo dispositivo.

Tipo: map de pares de valores-chave

clientToken(Python:) client_token

(Opcional) O token usado para corresponder à solicitação e à resposta correspondente do token do cliente.

Tipo: string

version

(Opcional) A versão do documento paralelo local a ser atualizada. O serviço paralelo processa a atualização somente se a versão especificada corresponder à versão mais recente que ela tem.

Tipo: integer

Resposta

A resposta dessa operação tem as seguintes informações:

payload

O documento de estado da resposta como um blob.

Tipo: object que contém as seguintes informações:

state

As informações do estado.

Esse objeto contém as seguintes informações.

desired

As propriedades e os valores do estado solicitados para serem atualizados no dispositivo.

Tipo: map de pares de valores-chave

reported

As propriedades e os valores do estado relatados pelo dispositivo.

Tipo: map de pares de valores-chave

delta

As propriedades e os valores do estado relatados pelo dispositivo.

Tipo: map de pares de valores-chave

metadata

Os registros de data e hora de cada atributo nas reported seções desired e para que você possa determinar quando o estado foi atualizado.

Tipo: string

timestamp

A data e a hora da época em que a resposta foi gerada.

Tipo: integer

clientToken(Python:) client_token

O token usado para corresponder à solicitação e à resposta correspondente.

Tipo: string

version

A versão do documento paralelo local após a conclusão da atualização.

Tipo: integer

Erros

Essa operação pode retornar os seguintes erros.

ConflictError

O serviço paralelo local encontrou um conflito de versão durante a operação de atualização. Isso ocorre quando a versão na carga útil da solicitação não corresponde à versão no último documento paralelo local disponível.

InvalidArgumentsError

O serviço paralelo local não consegue validar os parâmetros da solicitação. Isso pode ocorrer se a solicitação contiver caracteres JSON malformados ou sem suporte.

Um válido payload tem as seguintes propriedades:

  • O state nó existe e é um objeto que contém as informações do reported estado desired ou.

  • Os reported nós desired e são objetos ou nulos. Pelo menos um desses objetos deve conter informações de estado válidas.

  • A profundidade dos reported objetos desired e não pode exceder oito nós.

  • O tamanho do clientToken valor não pode exceder 64 caracteres.

  • O version valor deve ser igual 1 ou superior.

ServiceError

Ocorreu um erro de serviço interno ou o número de solicitações ao serviço IPC excedeu os limites especificados nos parâmetros de maxTotalLocalRequestsRate configuração maxLocalRequestsPerSecondPerThing e no componente do gerenciador de sombra.

UnauthorizedError

A política de autorização do componente não inclui as permissões necessárias para essa operação.

Exemplos

Os exemplos a seguir demonstram como chamar essa operação no código de componente personalizado.

Java (IPC client V1)
exemplo Exemplo: atualizar a sombra de uma coisa
nota

Este exemplo usa uma IPCUtils classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para ter mais informações, consulte Conecte-se ao serviço 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)
exemplo Exemplo: atualizar a sombra de uma coisa
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
exemplo Exemplo: atualizar a sombra de uma coisa
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

Apaga o shadow do objeto especificada.

A partir do shadow manager v2.0.4, a exclusão de uma sombra incrementa o número da versão. Por exemplo, quando você exclui a sombra MyThingShadow na versão 1, a versão da sombra excluída é 2. Se você recriar uma sombra com o nomeMyThingShadow, a versão dessa sombra será 3.

Solicitação

A solicitação dessa operação tem os seguintes parâmetros:

thingName(Python:) thing_name

O nome da coisa.

Tipo: string

shadowName(Python:) shadow_name

O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia ("").

Atenção

O AWS IoT Greengrass serviço usa a sombra AWSManagedGreengrassV2Deployment nomeada para gerenciar implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso pelo AWS IoT Greengrass serviço. Não atualize nem exclua essa sombra nomeada.

Tipo: string

Resposta

A resposta dessa operação tem as seguintes informações:

payload

Um documento de estado de resposta vazio.

Erros

Essa operação pode retornar os seguintes erros.

InvalidArgumentsError

O serviço paralelo local não consegue validar os parâmetros da solicitação. Isso pode ocorrer se a solicitação contiver caracteres JSON malformados ou sem suporte.

ResourceNotFoundError

O documento paralelo local solicitado não foi encontrado.

ServiceError

Ocorreu um erro de serviço interno ou o número de solicitações ao serviço IPC excedeu os limites especificados nos parâmetros de maxTotalLocalRequestsRate configuração maxLocalRequestsPerSecondPerThing e no componente do gerenciador de sombra.

UnauthorizedError

A política de autorização do componente não inclui as permissões necessárias para essa operação.

Exemplos

Os exemplos a seguir demonstram como chamar essa operação no código de componente personalizado.

Java (IPC client V1)
exemplo Exemplo: excluir uma sombra de coisa
nota

Este exemplo usa uma IPCUtils classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para ter mais informações, consulte Conecte-se ao serviço 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)
exemplo Exemplo: excluir uma sombra de coisa
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
exemplo Exemplo: excluir uma sombra de coisa
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

Liste as sombras nomeadas para a coisa especificada.

Solicitação

A solicitação dessa operação tem os seguintes parâmetros:

thingName(Python:) thing_name

O nome da coisa.

Tipo: string

pageSize(Python:) page_size

(Opcional) O número de nomes de sombra a serem retornados em cada chamada.

Tipo: integer

Padrão: 25

Maximum (Máximo): 100

nextToken(Python:) next_token

(Opcional) O token para recuperar o próximo conjunto de resultados. Esse valor é retornado nos resultados paginados e é usado na chamada que retorna a próxima página.

Tipo: string

Resposta

A resposta dessa operação tem as seguintes informações:

results

A lista de nomes de sombras.

Tipo: array

timestamp

(Opcional) A data e a hora em que a resposta foi gerada.

Tipo: integer

nextToken(Python:) next_token

(Opcional) O valor do token a ser usado em solicitações paginadas para recuperar a próxima página na sequência. Esse token não está presente quando não há mais nomes de sombra a serem retornados.

Tipo: string

nota

Se o tamanho da página solicitada corresponder exatamente ao número de nomes de sombra na resposta, esse token estará presente; no entanto, quando usado, ele retornará uma lista vazia.

Erros

Essa operação pode retornar os seguintes erros.

InvalidArgumentsError

O serviço paralelo local não consegue validar os parâmetros da solicitação. Isso pode ocorrer se a solicitação contiver caracteres JSON malformados ou sem suporte.

ResourceNotFoundError

O documento paralelo local solicitado não foi encontrado.

ServiceError

Ocorreu um erro de serviço interno ou o número de solicitações ao serviço IPC excedeu os limites especificados nos parâmetros de maxTotalLocalRequestsRate configuração maxLocalRequestsPerSecondPerThing e no componente do gerenciador de sombra.

UnauthorizedError

A política de autorização do componente não inclui as permissões necessárias para essa operação.

Exemplos

Os exemplos a seguir demonstram como chamar essa operação no código de componente personalizado.

Java (IPC client V1)
exemplo Exemplo: Listar sombras de uma coisa chamada
nota

Este exemplo usa uma IPCUtils classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para ter mais informações, consulte Conecte-se ao serviço 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)
exemplo Exemplo: Listar sombras de uma coisa chamada
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
exemplo Exemplo: Listar sombras de uma coisa chamada
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();