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á.
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 publish/subscribe IPC service to subscribe to shadow events. For more information about using the publish/subscribe serviço, consulte Publicar/assinar mensagens locais o.
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 Gerenciador de sombras para comunicação com dispositivos cliente.
Tópicos
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.
SDK | Versão mínima |
---|---|
v1.4.0 |
|
v1.6.0 |
|
v1.17.0 |
|
v1.12.0 |
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, consulte Autorizar componentes a realizar operações de IPC.
As políticas de autorização para interação de sombras tem as propriedades a seguir.
Identificador de serviço IPC: aws.greengrass.ShadowManager
Operação | Descrição | Recursos |
---|---|---|
|
Permite que um componente recupere a sombra de um objeto. |
Uma das seguintes strings:
|
|
Permite que um componente atualize a sombra de um objeto. |
Uma das seguintes strings:
|
|
Permite que um componente exclua a sombra de um objeto. |
Uma das seguintes strings:
|
|
Permite que um componente recupere a lista de sombras nomeadas para uma coisa. |
Uma string de nome de objeto que permite acessar o objeto para listar suas sombras. Use |
Identificador de serviço IPC: aws.greengrass.ipc.pubsub
Operação | Descrição | Recursos |
---|---|---|
|
Permite que um componente publique mensagens nos tópicos do MQTT que você especificar. |
Uma das seguintes strings de tópicos:
O valor do prefixo do tópico
Use No núcleo do Greengrass v2.6.0 e versões posteriores, você pode se inscrever em tópicos que contenham curingas de tópicos do MQTT ( |
Variáveis de fórmula nas políticas locais de autorização de sombra
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ítica de autorização
Consulte os exemplos de política de autorização a seguir para 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 de núcleo do Greengrass. O núcleo do Greengrass v2.6.0 adiciona suporte para a maioria das variáveis de fórmula, como {iot:thingName}
, em configurações de componentes. Para habilitar esse recurso, defina a opção de interpolateComponentConfigurationconfiguração do Greengrass nucleus 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 do dispositivo clássica e a sombra nomeada myNamedShadow
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.
{
"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 Exempo: permitir que um grupo de dispositivos principais interaja com sombras do dispositivo locais.
Importante
Esse recurso requer o núcleo do Greengrass v2.6.0 ou posterior, o gerenciador de sombras v2.2.0 ou posterior e a ponte MQTT v2.2.0 ou posterior. Você deve configurar a ponte MQTT para permitir que o gerenciador de sombras se comunique com os dispositivos do cliente.
O exemplo de política de autorização a seguir permite que o componente com.example.MyShadowInteractionComponent
interaja com todas as sombras de dispositivos clientes cujos nomes começam com MyClientDevice
.
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 Gerenciador de sombras para comunicação com dispositivos cliente.
{
"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 principal ú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 nomeada myNamedShadow
do dispositivo MyThingName
. Essa política também permite que esse componente receba mensagens sobre tópicos locais para essas sombras.
{
"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 de núcleo do Greengrass. O núcleo do Greengrass v2.6.0 adiciona suporte para a maioria das variáveis de fórmula, como {iot:thingName}
, em configurações de componentes. Para habilitar esse recurso, defina a opção de interpolateComponentConfigurationconfiguração do Greengrass nucleus 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 com.example.MyShadowReactiveComponent
personalizado receba mensagens no tópico /update/delta
da sombra clássica do dispositivo e da sombra nomeada myNamedShadow
em cada dispositivo principal que executa o componente.
{
"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 principal único reaja às mudanças locais do estado de sombra
O exemplo de política de controle de acesso a seguir permite que o com.example.MyShadowReactiveComponent
personalizado receba mensagens no tópico /update/delta
da sombra clássica do dispositivo e da sombra nomeada myNamedShadow
do dispositivo MyThingName
.
{
"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
Obtém a sombra do objeto especificado.
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 a atualize nem exclua.Tipo:
string
Resposta
A resposta dessa operação tem as seguintes informações:
payload
-
O documento de estado da resposta como um blob.
Tipo: o
object
que contém as seguintes informações:state
-
As informações do estado.
Esse objeto contém as informações a seguir.
desired
-
As propriedades de estado e os valores solicitados para serem atualizados no dispositivo.
Tipo:
map
de pares de chave-valor reported
-
As propriedades de estado e os valores relatados pelo dispositivo.
Tipo:
map
de pares de chave-valor delta
-
A diferença entre as propriedades e valores do estado desejado e relatado. Essa propriedade está presente somente se os estados
desired
ereported
forem diferentes.Tipo:
map
de pares de chave-valor
metadata
-
As marcações de data e hora de cada atributo nas seções
desired
ereported
para que você possa determinar quando o estado foi atualizado.Tipo:
string
timestamp
-
A data e a hora de Epoch em que a resposta foi gerada.
Tipo:
integer
clientToken
(Python:clientToken
)-
O token usado para combinar a solicitação e a resposta correspondente
Tipo:
string
version
-
A versão do documento de sombra local.
Tipo:
integer
Erros
Essa operação não pode retornar os erros a seguir.
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
-
Não foi possível encontrar o documento paralelo local.
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 configuração
maxLocalRequestsPerSecondPerThing
emaxTotalLocalRequestsRate
no componente do gerenciador de sombra. -
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 do componente personalizado.
exemplo Exemplo: obter 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 obter 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());
}
}
UpdateThingShadow
Atualiza a sombra da coisa especificada. Se a sombra não existir, ela será 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 a atualize nem exclua.Tipo:
string
payload
-
O documento de estado da solicitação como um blob.
Tipo: o
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 informações a seguir. Normalmente, você usará a propriedade
reported
oudesired
, mas não ambas na mesma solicitação.desired
-
As propriedades de estado e os valores solicitados para serem atualizados no dispositivo.
Tipo:
map
de pares de chave-valor reported
-
As propriedades de estado e os valores relatados pelo dispositivo.
Tipo:
map
de pares de chave-valor
clientToken
(Python:client_token
)-
(Opcional) O token usado para combinar a solicitação e a resposta correspondente pelo token do cliente.
Tipo:
string
version
-
(Opcional) A versão do documento de sombra local a ser atualizada. O serviço de sombra processa a atualização somente se a versão especificada corresponder à versão mais recente que ele possui.
Tipo:
integer
Resposta
A resposta dessa operação tem as seguintes informações:
payload
-
O documento de estado da resposta como um blob.
Tipo: o
object
que contém as seguintes informações:state
-
As informações do estado.
Esse objeto contém as informações a seguir.
desired
-
As propriedades de estado e os valores solicitados para serem atualizados no dispositivo.
Tipo:
map
de pares de chave-valor reported
-
As propriedades de estado e os valores relatados pelo dispositivo.
Tipo:
map
de pares de chave-valor delta
-
As propriedades de estado e os valores relatados pelo dispositivo.
Tipo:
map
de pares de chave-valor
metadata
-
As marcações de data e hora de cada atributo nas seções
desired
ereported
para que você possa determinar quando o estado foi atualizado.Tipo:
string
timestamp
-
A data e a hora de Epoch em que a resposta foi gerada.
Tipo:
integer
clientToken
(Python:client_token
)-
O token usado para combinar a solicitação e a 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 não pode retornar os erros a seguir.
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.
Uma
payload
válida tem as seguintes propriedades:-
O nó
state
existe e é um objeto que contém as informações de estadodesired
oureported
. -
Os nós
desired
ereported
são objetos ou nulos. Pelo menos um desses objetos deve conter informações de estado válidas. -
A profundidade dos objetos
desired
ereported
não pode exceder oito nós. -
O comprimento do valor de
clientToken
não pode exceder 64 caracteres. -
O valor de
version
deve ser1
ou mais.
-
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 configuração
maxLocalRequestsPerSecondPerThing
emaxTotalLocalRequestsRate
no componente do gerenciador de sombra. -
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 do componente personalizado.
exemplo Exemplo: atualizar a sombra de um objeto.
nota
Este exemplo usa uma IPCUtils
classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para obter 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());
}
}
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 nome MyThingShadow
, 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 a atualize nem exclua.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 não pode retornar os erros a seguir.
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
-
Não foi possível encontrar o documento paralelo local.
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 configuração
maxLocalRequestsPerSecondPerThing
emaxTotalLocalRequestsRate
no componente do gerenciador de sombra. -
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 do componente personalizado.
exemplo Exemplo: excluir a sombra de um objeto.
nota
Este exemplo usa uma IPCUtils
classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para obter 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());
}
}
ListNamedShadowsForThing
Liste as sombras com nome 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 recuperação do 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 para retornar.
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 não pode retornar os erros a seguir.
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
-
Não foi possível encontrar o documento paralelo local.
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 configuração
maxLocalRequestsPerSecondPerThing
emaxTotalLocalRequestsRate
no componente do gerenciador de sombra. -
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 do componente personalizado.
exemplo Exemplo: listar sombras de uma coisa nomeada
nota
Este exemplo usa uma IPCUtils
classe para criar uma conexão com o serviço AWS IoT Greengrass Core IPC. Para obter 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());
}
}