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 AWS IoT Device SDK para se comunicar com o núcleo do Greengrass, outros componentes e AWS IoT Core
Os componentes executados em seu dispositivo principal podem usar a biblioteca de comunicação entre processos AWS IoT Greengrass principais (IPC) no AWS IoT Device SDK para se comunicar com o AWS IoT Greengrass núcleo e outros componentes do Greengrass. Para desenvolver e executar componentes personalizados que usam IPC, você deve usar o AWS IoT Device SDK para se conectar ao serviço AWS IoT Greengrass Core IPC e realizar operações de IPC.
A interface IPC suporta dois tipos de operações:
-
Solicitação/resposta
Os componentes enviam uma solicitação ao serviço IPC e recebem uma resposta que contém o resultado da solicitação.
-
Assinatura
Os componentes enviam uma solicitação de assinatura ao serviço IPC e esperam um fluxo de mensagens de eventos em resposta. Os componentes fornecem um manipulador de assinaturas que lida com mensagens de eventos, erros e encerramento de streams. AWS IoT Device SDK Isso inclui uma interface de manipulador com os tipos corretos de resposta e evento para cada operação de IPC. Para ter mais informações, consulte Inscreva-se nos streams de eventos do IPC.
Tópicos
- Versões do cliente IPC
- SDKs compatíveis para comunicação entre processos
- Conecte-se ao serviço AWS IoT Greengrass Core IPC
- Autorize componentes a realizar operações de IPC
- Inscreva-se nos streams de eventos do IPC
- Melhores práticas do IPC
- Publique/assine mensagens locais
- Publique/assine mensagens MQTT AWS IoT Core
- Interaja com o ciclo de vida dos componentes
- Interaja com a configuração do componente
- Recuperar valores secretos
- Interaja com sombras locais
- Gerencie implantações e componentes locais
- Autenticar e autorizar dispositivos clientes
Versões do cliente IPC
Nas versões posteriores dos SDKs de Java e Python, AWS IoT Greengrass fornece uma versão aprimorada do cliente IPC, chamada cliente IPC V2. Cliente IPC V2:
-
Reduz a quantidade de código que você precisa escrever para usar operações IPC e ajuda a evitar erros comuns que podem ocorrer com o cliente IPC V1.
-
Chama os retornos de chamada do manipulador de assinatura em um thread separado, para que agora você possa executar o código de bloqueio, incluindo chamadas de função IPC adicionais, nos retornos de chamada do manipulador de assinaturas. O cliente IPC V1 usa o mesmo encadeamento para se comunicar com o servidor IPC e chamar os retornos de chamada do manipulador de assinatura.
-
Permite chamar operações de assinatura usando expressões Lambda (Java) ou funções (Python). O cliente IPC V1 exige que você defina classes de manipuladores de assinaturas.
-
Fornece versões síncronas e assíncronas de cada operação IPC. O cliente IPC V1 fornece somente versões assíncronas de cada operação.
Recomendamos que você use o cliente IPC V2 para aproveitar essas melhorias. No entanto, muitos exemplos nesta documentação e em alguns conteúdos on-line demonstram somente como usar o cliente IPC V1. Você pode usar os exemplos e tutoriais a seguir para ver exemplos de componentes que usam o cliente IPC V2:
Atualmente, o AWS IoT Device SDK for C++ v2 suporta somente o cliente IPC V1.
SDKs compatíveis para comunicação entre processos
As bibliotecas AWS IoT Greengrass principais do IPC estão incluídas nas seguintes AWS IoT Device SDK versões.
SDK | Versão mínima | Uso |
---|---|---|
v1.6.0 |
Consulte Use AWS IoT Device SDK para Java v2 (cliente IPC V2) |
|
v1.9.0 |
Consulte Use AWS IoT Device SDK para Python v2 (cliente IPC V2) |
|
v1.17.0 |
Consulte Use AWS IoT Device SDK para C++ v2 |
|
v1.12.0 |
Consulte Use AWS IoT Device SDK para JavaScript v2 (cliente IPC V1) |
Conecte-se ao serviço AWS IoT Greengrass Core IPC
Para usar a comunicação entre processos em seu componente personalizado, você deve criar uma conexão com um soquete de servidor IPC executado pelo software AWS IoT Greengrass Core. Conclua as tarefas a seguir para baixar e usar o AWS IoT Device SDK no idioma de sua escolha.
Para usar o AWS IoT Device SDK para Java v2 (cliente IPC V2)
-
Faça o download do AWS IoT Device SDK para Java v2
(v1.6.0 ou posterior). -
Faça o seguinte para executar seu código personalizado em seu componente:
-
Crie seu componente como um arquivo JAR que inclua AWS IoT Device SDK o. e execute esse arquivo JAR na receita do componente.
-
Defina o AWS IoT Device SDK JAR como um artefato de componente e adicione esse artefato ao classpath ao executar seu aplicativo na receita do componente.
-
-
Use o código a seguir para criar o cliente IPC.
try (GreengrassCoreIPCClientV2 ipcClient = GreengrassCoreIPCClientV2.builder().build()) { // Use client. } catch (Exception e) { LOGGER.log(Level.SEVERE, "Exception occurred when using IPC.", e); System.exit(1); }
Para usar o AWS IoT Device SDK para Python v2 (cliente IPC V2)
-
Baixe o AWS IoT Device SDK para Python
(v1.9.0 ou posterior). -
Adicione as etapas de instalação
do SDK ao ciclo de vida da instalação na receita do seu componente. -
Crie uma conexão com o serviço AWS IoT Greengrass Core IPC. Use o código a seguir para criar o cliente IPC.
from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2 try: ipc_client = GreengrassCoreIPCClientV2() # Use IPC client. except Exception: print('Exception occurred when using IPC.', file=sys.stderr) traceback.print_exc() exit(1)
Para criar a AWS IoT Device SDK v2 para C++, um dispositivo deve ter as seguintes ferramentas:
-
C++ 11 ou posterior
-
CMake 3.1 ou posterior
-
Um dos seguintes compiladores:
-
GCC 4.8 ou posterior
-
Clang 3.9 ou posterior
-
MSVC 2015 ou posterior
-
Para usar o AWS IoT Device SDK para C++ v2
-
Faça o download do AWS IoT Device SDK para C++ v2 (v1.17.0
ou posterior). -
Siga as instruções de instalação no README para criar o
AWS IoT Device SDK para C++ v2 a partir do código-fonte. -
Em sua ferramenta de criação de C++, vincule a biblioteca Greengrass IPC
AWS::GreengrassIpc-cpp
,, que você criou na etapa anterior. OCMakeLists.txt
exemplo a seguir vincula a biblioteca Greengrass IPC a um projeto que você cria com o CMake.cmake_minimum_required(VERSION 3.1) project (greengrassv2_pubsub_subscriber) file(GLOB MAIN_SRC "*.h" "*.cpp" ) add_executable(${PROJECT_NAME} ${MAIN_SRC}) set_target_properties(${PROJECT_NAME} PROPERTIES LINKER_LANGUAGE CXX CXX_STANDARD 11) find_package(aws-crt-cpp PATHS ~/sdk-cpp-workspace/build) find_package(EventstreamRpc-cpp PATHS ~/sdk-cpp-workspace/build) find_package(GreengrassIpc-cpp PATHS ~/sdk-cpp-workspace/build) target_link_libraries(${PROJECT_NAME} AWS::GreengrassIpc-cpp)
-
No código do componente, crie uma conexão com o serviço AWS IoT Greengrass Core IPC para criar um cliente IPC ()
Aws::Greengrass::GreengrassCoreIpcClient
. Você deve definir um manipulador do ciclo de vida da conexão IPC que gerencie eventos de conexão, desconexão e erro IPC. O exemplo a seguir cria um cliente IPC e um manipulador do ciclo de vida da conexão IPC que imprime quando o cliente IPC se conecta, desconecta e encontra erros.#include <iostream> #include <aws/crt/Api.h> #include <aws/greengrass/GreengrassCoreIpcClient.h> using namespace Aws::Crt; using namespace Aws::Greengrass; class IpcClientLifecycleHandler : public ConnectionLifecycleHandler { void OnConnectCallback() override { std::cout << "OnConnectCallback" << std::endl; } void OnDisconnectCallback(RpcError error) override { std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl; exit(-1); } bool OnErrorCallback(RpcError error) override { std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl; return true; } }; int main() { // Create the IPC client. ApiHandle apiHandle(g_allocator); Io::EventLoopGroup eventLoopGroup(1); Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30); Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver); IpcClientLifecycleHandler ipcLifecycleHandler; GreengrassCoreIpcClient ipcClient(bootstrap); auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get(); if (!connectionStatus) { std::cerr << "Failed to establish IPC connection: " << connectionStatus.StatusToString() << std::endl; exit(-1); } // Use the IPC client to create an operation request. // Activate the operation request. auto activate = operation.Activate(request, nullptr); activate.wait(); // Wait for Greengrass Core to respond to the request. auto responseFuture = operation.GetResult(); if (responseFuture.wait_for(std::chrono::seconds(timeout)) == std::future_status::timeout) { std::cerr << "Operation timed out while waiting for response from Greengrass Core." << std::endl; exit(-1); } // Check the result of the request. auto response = responseFuture.get(); if (response) { std::cout << "Successfully published to topic: " << topic << std::endl; } else { // An error occurred. std::cout << "Failed to publish to topic: " << topic << std::endl; auto errorType = response.GetResultType(); if (errorType == OPERATION_ERROR) { auto *error = response.GetOperationError(); std::cout << "Operation error: " << error->GetMessage().value() << std::endl; } else { std::cout << "RPC error: " << response.GetRpcError() << std::endl; } exit(-1); } return 0; }
-
Para executar seu código personalizado em seu componente, crie seu código como um artefato binário e execute o artefato binário em sua receita de componente. Defina a
Execute
permissão do artefatoOWNER
para permitir que o software AWS IoT Greengrass Core execute o artefato binário.A
Manifests
seção da receita do seu componente pode ser semelhante ao exemplo a seguir.
Para criar o AWS IoT Device SDK for JavaScript v2 para uso com o NodeJS, um dispositivo deve ter as seguintes ferramentas:
-
NodeJS 10.0 ou posterior
-
Execute
node -v
para verificar a versão do Node.
-
-
CMake 3.1 ou posterior
Para usar o AWS IoT Device SDK for JavaScript v2 (cliente IPC V1)
-
Baixe o AWS IoT Device SDK para JavaScript v2 (v1.12.10
ou posterior). -
Siga as instruções de instalação no README para criar o
AWS IoT Device SDK for JavaScript v2 a partir do código-fonte. -
Crie uma conexão com o serviço AWS IoT Greengrass Core IPC. Conclua as etapas a seguir para criar o cliente IPC e estabelecer uma conexão.
-
Use o código a seguir para criar o cliente IPC.
import * as greengrascoreipc from 'aws-iot-device-sdk-v2'; let client = greengrascoreipc.createClient();
-
Use o código a seguir para estabelecer uma conexão do seu componente com o núcleo do Greengrass.
await client.connect();
Autorize componentes a realizar operações de IPC
Para permitir que seus componentes personalizados usem algumas operações de IPC, você deve definir políticas de autorização que permitam que o componente execute a operação em determinados recursos. Cada política de autorização define uma lista de operações e uma lista de recursos que a política permite. Por exemplo, o serviço IPC de mensagens de publicação/assinatura define operações de publicação e assinatura para recursos de tópicos. Você pode usar o *
caractere curinga para permitir o acesso a todas as operações ou a todos os recursos.
Você define políticas de autorização com o parâmetro de accessControl
configuração, que pode ser definido na receita do componente ou ao implantar o componente. O accessControl
objeto mapeia identificadores de serviço IPC para listas de políticas de autorização. Você pode definir várias políticas de autorização para cada serviço IPC para controlar o acesso. Cada política de autorização tem um ID de política, que deve ser exclusivo entre todos os componentes.
dica
Para criar IDs de política exclusivos, você pode combinar o nome do componente, o nome do serviço IPC e um contador. Por exemplo, um componente chamado com.example.HelloWorld
pode definir duas políticas de autorização de publicação/assinatura com as seguintes IDs:
-
com.example.HelloWorld:pubsub:1
-
com.example.HelloWorld:pubsub:2
As políticas de autorização usam o seguinte formato. Esse objeto é o parâmetro accessControl
de configuração.
Caracteres curingas nas políticas de autorização
Você pode usar o *
caractere curinga no resources
elemento das políticas de autorização do IPC para permitir o acesso a vários recursos em uma única política de autorização.
-
Em todas as versões do núcleo do Greengrass, você pode especificar um único
*
caractere como recurso para permitir o acesso a todos os recursos. -
No Greengrass nucleus v2.6.0 e versões posteriores, você pode especificar o
*
caractere em um recurso para corresponder a qualquer combinação de caracteres. Por exemplo, você pode especificarfactory/1/devices/Thermostat*/status
para permitir o acesso a um tópico de status para todos os dispositivos de termostato em uma fábrica, onde o nome de cada dispositivo começa com.Thermostat
Ao definir políticas de autorização para o serviço AWS IoT Core MQTT IPC, você também pode usar curingas do MQTT (+
e#
) para combinar vários recursos. Para obter mais informações, consulte Caracteres curinga do MQTT nas políticas de autorização do IPC do AWS IoT Core MQTT.
Variáveis de receita nas políticas de autorização
Se você usar o Greengrass nucleus v2.6.0 ou posterior e definir a opção de interpolateComponentConfigurationconfiguração do Greengrass nucleus comotrue, poderá usar a variável de receita nas políticas de autorização. {iot:thingName} Quando você precisar de uma política de autorização que inclua o nome do dispositivo principal, como para tópicos do MQTT ou sombras do dispositivo, você pode usar essa variável de receita para configurar uma única política de autorização para um grupo de dispositivos principais. Por exemplo, você pode permitir que um componente acesse o seguinte recurso para operações de IPC paralelas.
$aws/things/{iot:thingName}/shadow/
Caracteres especiais nas políticas de autorização
Para especificar um literal *
ou ?
caractere em uma política de autorização, você deve usar uma sequência de escape. As sequências de escape a seguir instruem o software AWS IoT Greengrass Core a usar o valor literal em vez do significado especial do caractere. Por exemplo, o *
caractere é um curinga que corresponde a qualquer combinação de caracteres.
Caráter literal | Sequência de escape | Observações |
---|---|---|
|
|
|
|
|
AWS IoT Greengrass atualmente não suporta o |
|
|
Use essa sequência de escape para corresponder a um recurso que contém |
Exemplos de políticas de autorização
Você pode consultar os exemplos de políticas de autorização a seguir para ajudá-lo a configurar políticas de autorização para seus componentes.
exemplo Exemplo de receita de componente com uma política de autorização
O exemplo de receita de componente a seguir inclui um accessControl
objeto que define uma política de autorização. Essa política autoriza o com.example.HelloWorld
componente a publicar no test/topic
tópico.
exemplo Exemplo de atualização da configuração do componente com uma política de autorização
O exemplo de atualização de configuração a seguir em uma implantação especifica a configuração de um componente com um accessControl
objeto que define uma política de autorização. Essa política autoriza o com.example.HelloWorld
componente a publicar no test/topic
tópico.
Inscreva-se nos streams de eventos do IPC
Você pode usar as operações de IPC para assinar fluxos de eventos em um dispositivo principal do Greengrass. Para usar uma operação de assinatura, defina um manipulador de assinatura e crie uma solicitação para o serviço IPC. Em seguida, o cliente IPC executa as funções do manipulador de assinaturas sempre que o dispositivo principal transmite uma mensagem de evento para seu componente.
Você pode fechar uma assinatura para interromper o processamento de mensagens de eventos. Para fazer isso, chame closeStream()
(Java), close()
(Python) ou Close()
(C++) no objeto de operação de assinatura que você usou para abrir a assinatura.
O serviço AWS IoT Greengrass Core IPC suporta as seguintes operações de assinatura:
Defina gerenciadores de assinaturas
Para definir um manipulador de assinatura, defina funções de retorno de chamada que lidem com mensagens de eventos, erros e encerramento de fluxo. Se você usar o cliente IPC V1, deverá definir essas funções em uma classe. Se você usa o cliente IPC V2, que está disponível em versões posteriores dos SDKs para Java e Python, você pode definir essas funções sem criar uma classe de manipulador de assinaturas.
Exemplos de gerenciadores de assinaturas
O exemplo a seguir demonstra como usar a SubscribeToTopic operação e um manipulador de assinaturas para assinar mensagens locais de publicação/assinatura.
Melhores práticas do IPC
As melhores práticas para usar o IPC em componentes personalizados diferem entre o cliente IPC V1 e o cliente IPC V2. Siga as melhores práticas para a versão do cliente IPC que você usa.