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á.
Interagir 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 Publicar/assinar mensagens locais.
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, consulte Autorizar componentes a realizar operações 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
Operation |
Descrição |
Recursos |
aws.greengrass#GetThingShadow
|
Permite que um componente recupere a sombra de um objeto.
|
Uma das seguintes strings:
-
$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 um objeto.
|
Uma das seguintes strings:
-
$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 um objeto.
|
Uma das seguintes strings:
-
$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 para uma coisa.
|
Uma string de nome de objeto que permite acessar o objeto para listar suas sombras.
Use * para permitir o acesso a todos os objetos.
|
Identificador de serviço IPC: aws.greengrass.ipc.pubsub
Operation |
Descrição |
Recursos |
aws.greengrass#SubscribeToTopic
|
Permite que um componente publique mensagens nos tópicos do MQTT que você especificar.
|
Uma das seguintes strings 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 do tópico shadowTopicPrefix depende do tipo de sombra:
Use * para permitir o acesso a todos os tópicos.
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 (# e + ). Essa string de tópico aceita curingas de tópico MQTT como caracteres literais. Por exemplo, se a política de autorização de um componente conceder acesso a test/topic/# , o componente pode se inscrever no test/topic/# , mas não pode se inscrever no test/topic/filter .
|
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 configuração interpolateComponentConfiguration do núcleo do Greengrass como true, poderá usar a variável de fórmula {iot:thingName}
nas políticas de autorização. 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
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.
- 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 Exempo: permitir que um grupo de dispositivos principais interaja com sombras do dispositivo locais.
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
.
- 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 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.
- 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
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.
- 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 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
.
- 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
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 (""
).
O serviço do AWS IoT Greengrass usa a sombra nomeada AWSManagedGreengrassV2Deployment
para gerenciar as implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso do serviço AWS IoT Greengrass. 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
e reported
forem diferentes.
Tipo: map
de pares de chave-valor
metadata
-
As marcações de data e hora de cada atributo nas seções desired
e reported
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
e maxTotalLocalRequestsRate
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 do componente personalizado.
- Java (IPC client V1)
-
exemplo Exemplo: obter uma sombra de coisa
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: obter uma sombra de coisa
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: obter uma sombra de coisa
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
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 (""
).
O serviço do AWS IoT Greengrass usa a sombra nomeada AWSManagedGreengrassV2Deployment
para gerenciar as implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso do serviço AWS IoT Greengrass. 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
ou desired
, 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
e reported
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 estado desired
ou reported
.
-
Os nós desired
e reported
são objetos ou nulos. Pelo menos um desses objetos deve conter informações de estado válidas.
-
A profundidade dos objetos desired
e reported
não pode exceder oito nós.
-
O comprimento do valor de clientToken
não pode exceder 64 caracteres.
-
O valor de version
deve ser 1
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
e maxTotalLocalRequestsRate
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 do componente personalizado.
- Java (IPC client V1)
-
exemplo Exemplo: atualizar a sombra de um 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)
-
exemplo Exemplo: atualizar a sombra de um 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
-
exemplo Exemplo: atualizar a sombra de um 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
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 (""
).
O serviço do AWS IoT Greengrass usa a sombra nomeada AWSManagedGreengrassV2Deployment
para gerenciar as implantações direcionadas a dispositivos principais individuais. Essa sombra nomeada é reservada para uso do serviço AWS IoT Greengrass. 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
e maxTotalLocalRequestsRate
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 do componente personalizado.
- Java (IPC client V1)
-
exemplo Exemplo: excluir a sombra de um 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)
-
exemplo Exemplo: excluir a sombra de um 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
-
exemplo Exemplo: excluir a sombra de um 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
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
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
e maxTotalLocalRequestsRate
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 do componente personalizado.
- Java (IPC client V1)
-
exemplo Exemplo: listar sombras de uma coisa nomeada
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 nomeada
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 nomeada
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();