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
<a name="interprocess-communication"></a>

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 do IPC aceita dois tipos de operações:
+ **Resposta/solicitação**

  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 fluxos. 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 obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](#ipc-subscribe-operations).

**Topics**
+ [Versões do cliente de IPC](#ipc-client-versions)
+ [Compatível com SDKs comunicação entre processos](#ipc-requirements)
+ [Conecte-se ao serviço AWS IoT Greengrass Core IPC](#ipc-service-connect)
+ [Autorizar componentes a realizar operações de IPC](#ipc-authorization-policies)
+ [Inscrever-se nos fluxos de eventos da IPC](#ipc-subscribe-operations)
+ [Práticas recomendadas de IPC](#ipc-best-practices)
+ [Publicar/assinar mensagens locais](ipc-publish-subscribe.md)
+ [Publique/assine mensagens MQTT AWS IoT Core](ipc-iot-core-mqtt.md)
+ [Interaja com o ciclo de vida dos componentes](ipc-component-lifecycle.md)
+ [Interagir com a configuração do componente](ipc-component-configuration.md)
+ [Recuperar valores de segredos](ipc-secret-manager.md)
+ [Interagir com sombras locais](ipc-local-shadows.md)
+ [Gerenciar implantações e componentes locais](ipc-local-deployments-components.md)
+ [Autentique e autorize dispositivos cliente](ipc-client-device-auth.md)

## Versões do cliente de IPC
<a name="ipc-client-versions"></a>

Nas versões posteriores do Java e do Python SDKs, 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 de IPC e ajuda a evitar erros comuns que podem ocorrer com o cliente IPC V1.
+ Chama os callbacks do manipulador de assinatura em um thread separado, de modo que agora é possível executar código de bloqueio, incluindo chamadas de função IPC adicionais, em callbacks do manipulador de assinatura. 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 (Java) ou funções (Python) do Lambda. 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 o uso do cliente IPC V2 para o aproveitamento dessas 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:
+ [Exemplos da PublishToTopic](ipc-publish-subscribe.md#ipc-operation-publishtotopic-examples)
+ [Exemplos da SubscribeToTopic](ipc-publish-subscribe.md#ipc-operation-subscribetotopic-examples)
+ [Tutorial: Desenvolver um componente do Greengrass que adia as atualizações de componentes](defer-component-updates-tutorial.md)
+ [Tutorial: interagir com dispositivos de IoT locais por meio do MQTT](client-devices-tutorial.md)

Atualmente, o AWS IoT Device SDK for C\$1\$1 v2 suporta somente o cliente IPC V1.

## Compatível com SDKs comunicação entre processos
<a name="ipc-requirements"></a>

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 | Usage | 
| --- | --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.6.0  |  Consulte [Use AWS IoT Device SDK para Java v2 (cliente IPC V2)](#ipc-java-v2)  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.9.0  |  Consulte [Use AWS IoT Device SDK para Python v2 (cliente IPC V2)](#ipc-python-v2)  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  |  Consulte [Use AWS IoT Device SDK para C\$1\$1 v2](#ipc-cpp)  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  |  Consulte [Use AWS IoT Device SDK para JavaScript v2 (cliente IPC V1)](#ipc-nodejs)  | 

## Conecte-se ao serviço AWS IoT Greengrass Core IPC
<a name="ipc-service-connect"></a>

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. 

### Use AWS IoT Device SDK para Java v2 (cliente IPC V2)
<a name="ipc-java-v2"></a>

**Para usar o AWS IoT Device SDK para Java v2 (cliente IPC V2)**

1. Faça o download do [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2) (v1.6.0 ou posterior).

1. <a name="use-ipc-java-component-install-step"></a>Para executar o código personalizado em seu componente, faça o seguinte:
   + 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.

1. Use o código a seguir para criar o cliente de 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);
   }
   ```

### Use AWS IoT Device SDK para Python v2 (cliente IPC V2)
<a name="ipc-python-v2"></a>

**Para usar o AWS IoT Device SDK para Python v2 (cliente IPC V2)**

1. Faça download do [AWS IoT Device SDK para Python](https://github.com/aws/aws-iot-device-sdk-python-v2) (v1.9.0 ou posterior).

1. <a name="use-ipc-python-component-install-step"></a>Adicione as [etapas de instalação](https://github.com/aws/aws-iot-device-sdk-python-v2#installation) do SDK ao ciclo de vida da instalação na fórmula do seu componente.

1. Crie uma conexão com o serviço AWS IoT Greengrass Core IPC. Use o código a seguir para criar o cliente de 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)
   ```

### Use AWS IoT Device SDK para C\$1\$1 v2
<a name="ipc-cpp"></a>

<a name="iot-device-sdk-cpp-v2-build-requirements-intro"></a>Para criar a AWS IoT Device SDK v2 para C\$1\$1, um dispositivo deve ter as seguintes ferramentas:<a name="iot-device-sdk-cpp-v2-build-requirements"></a>
+ C\$1\$1 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\$1\$1 v2**

1. Faça download do [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2) (v1.17.0 ou posterior).

1. Siga as [instruções de instalação no README para criar o](https://github.com/aws/aws-iot-device-sdk-cpp-v2#Installation) AWS IoT Device SDK para C\$1\$1 v2 a partir do código-fonte.

1. Em sua ferramenta de compilação de C\$1\$1, vincule a biblioteca de IPC do Greengrass, `AWS::GreengrassIpc-cpp`, que você criou na etapa anterior. O `CMakeLists.txt` exemplo a seguir vincula a biblioteca Greengrass IPC a um projeto com o qual você constrói. 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)
   ```

1. 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. 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;
   }
   ```

1. 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 fórmula de componente. Defina a `Execute` permissão do artefato `OWNER` para permitir que o software AWS IoT Greengrass Core execute o artefato binário.

   A seção `Manifests` da fórmula pode parecer com o exemplo a seguir.

------
#### [ JSON ]

   ```
   {
     ...
     "Manifests": [
       {
         "Lifecycle": {
           "Run": "{artifacts:path}/greengrassv2_pubsub_subscriber"
         },
         "Artifacts": [
           {
             "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber",
             "Permission": {
               "Execute": "OWNER"
             }
           }
         ]
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ...
   Manifests:
     - Lifecycle:
         Run: {artifacts:path}/greengrassv2_pubsub_subscriber
       Artifacts:
         - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber
           Permission:
             Execute: OWNER
   ```

------

### Use AWS IoT Device SDK para JavaScript v2 (cliente IPC V1)
<a name="ipc-nodejs"></a>

<a name="iot-device-sdk-nodejs-build-requirements-intro"></a>Para criar o AWS IoT Device SDK for JavaScript v2 para uso com o NodeJS, um dispositivo deve ter as seguintes ferramentas:<a name="iot-device-sdk-nodejs-build-requirements"></a>
+ 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)**

1. Faça o download do [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2) (v1.12.10 ou posterior).

1. Siga as [instruções de instalação no README para criar o](https://github.com/aws/aws-iot-device-sdk-js-v2/tree/v1.12.1#installation) AWS IoT Device SDK for JavaScript v2 a partir do código-fonte.

1. 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.

1. Use o código a seguir para criar o cliente de IPC.

   ```
   import * as greengrascoreipc from 'aws-iot-device-sdk-v2';
   
   let client = greengrascoreipc.createClient();
   ```

1. Use o código a seguir para estabelecer uma conexão do seu componente com o núcleo do Greengrass.

   ```
   await client.connect();
   ```

## Autorizar componentes a realizar operações de IPC
<a name="ipc-authorization-policies"></a>

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 publish/subscribe mensagens define operações de publicação e assinatura para recursos de tópicos. É possível especificar o 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 configuração `accessControl`, que pode ser definido na fórmula do componente ou ao implantar o componente. O objeto `accessControl` mapeia identificadores de serviço de IPC para listas de políticas de autorização. Você pode definir várias políticas de autorização para cada serviço IPC a fim de 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 uma política exclusiva IDs, 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 publish/subscribe autorização com o seguinte IDs:  
`com.example.HelloWorld:pubsub:1`
`com.example.HelloWorld:pubsub:2`

As políticas de autorização usam o formato a seguir. Esse objeto é o parâmetro de configuração `accessControl`.

------
#### [ JSON ]

```
{
  "IPC service identifier": {
    "policyId": {
      "policyDescription": "description",
      "operations": [
        "operation1",
        "operation2"
      ],
      "resources": [
        "resource1",
        "resource2"
      ]
    }
  }
}
```

------
#### [ YAML ]

```
IPC service identifier:
  policyId:
    policyDescription: description
    operations:
      - operation1
      - operation2
    resources:
      - resource1
      - resource2
```

------

### Curingas nas políticas de autorização
<a name="ipc-authorization-policy-wildcards"></a>

Você pode usar o curinga `*` no elemento `resources` 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](greengrass-nucleus-component.md), você pode especificar um único caractere `*` como recurso para permitir o acesso a todos os recursos.
+ No [Núcleo do Greengrass](greengrass-nucleus-component.md) 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 especificar `factory/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 IPC do AWS IoT Core MQTT, 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](ipc-iot-core-mqtt.md#ipc-iot-core-mqtt-authorization-mqtt-wildcards).

### Variáveis de fórmula nas políticas de autorização
<a name="ipc-authorization-policy-recipe-variables"></a>

[Se você usar o [Greengrass nucleus](greengrass-nucleus-component.md) v2.6.0 ou posterior e definir a opção de [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)configuração do Greengrass nucleus como`true`, poderá usar a variável de receita nas políticas de autorização. `{iot:thingName}`](component-recipe-reference.md#recipe-variables) 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 fórmula 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 em políticas de autorização
<a name="ipc-authorization-policy-special-characters"></a>

Para especificar um caractere `*` ou `?` literal 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](#ipc-authorization-policy-wildcards) que corresponde a qualquer combinação de caracteres.


| Caractere literal | Sequência de escape | Observações | 
| --- | --- | --- | 
|  `*`  |  `${*}`  |  | 
|  `?`  |  `${?}`  |  AWS IoT Greengrass atualmente não suporta o `?` curinga, que corresponde a um único caractere.  | 
|  `$`  |  `${$}`  |  Use essa sequência de escape para corresponder a um recurso que contém `${`. Por exemplo, para corresponder a um recurso chamado `${resourceName}`, você deve especificar `${$}{resourceName}`. Caso contrário, para corresponder a um recurso que contém `$`, você pode usar um `$` literal, como para permitir acesso a um tópico que comece com `$aws`.  | 

### Exemplos de política de autorização
<a name="ipc-authorization-policy-examples"></a>

Consulte os exemplos de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de fórmula de componente com uma política de autorização**  
O exemplo de fórmula de componente a seguir inclui um objeto `accessControl` que define uma política de autorização. Essa política autoriza o componente `com.example.HelloWorld` a publicar no tópico `test/topic`.  

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.HelloWorld:pubsub:1": {
            "policyDescription": "Allows access to publish to test/topic.",
            "operations": [
              "aws.greengrass#PublishToTopic"
            ],
            "resources": [
              "test/topic"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "java -jar {artifacts:path}/HelloWorld.jar"
      }
    }
  ]
}
```

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        "com.example.HelloWorld:pubsub:1":
          policyDescription: Allows access to publish to test/topic.
          operations:
            - "aws.greengrass#PublishToTopic"
          resources:
            - "test/topic"
Manifests:
  - Lifecycle:
      Run: |-
        java -jar {artifacts:path}/HelloWorld.jar
```

**Example 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 objeto `accessControl` que define uma política de autorização. Essa política autoriza o componente `com.example.HelloWorld` a publicar no tópico `test/topic`.    
**Configuração a ser mesclada**  

```
{
  "accessControl": {
    "aws.greengrass.ipc.pubsub": {
      "com.example.HelloWorld:pubsub:1": {
        "policyDescription": "Allows access to publish to test/topic.",
        "operations": [
          "aws.greengrass#PublishToTopic"
        ],
        "resources": [
          "test/topic"
        ]
      }
    }
  }
}
```
O comando a seguir cria uma implantação em um dispositivo principal.  

```
aws greengrassv2 create-deployment --cli-input-json file://hello-world-deployment.json
```
O arquivo `hello-world-deployment.json` contém o documento JSON a seguir.  

```
{
  "targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
  "deploymentName": "Deployment for MyGreengrassCore",
  "components": {
    "com.example.HelloWorld": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "merge": "{\"accessControl\":{\"aws.greengrass.ipc.pubsub\":{\"com.example.HelloWorld:pubsub:1\":{\"policyDescription\":\"Allows access to publish to test/topic.\",\"operations\":[\"aws.greengrass#PublishToTopic\"],\"resources\":[\"test/topic\"]}}}}"
      }
    }
  }
}
```
O comando da [CLI do Greengrass](greengrass-cli-component.md) a seguir cria uma implantação local em um dispositivo principal.  

```
sudo greengrass-cli deployment create \
  --recipeDir recipes \
  --artifactDir artifacts \
  --merge "com.example.HelloWorld=1.0.0" \
  --update-config hello-world-configuration.json
```
O arquivo `hello-world-configuration.json` contém o documento JSON a seguir.  

```
{
  "com.example.HelloWorld": {
    "MERGE": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.HelloWorld:pubsub:1": {
            "policyDescription": "Allows access to publish to test/topic.",
            "operations": [
              "aws.greengrass#PublishToTopic"
            ],
            "resources": [
              "test/topic"
            ]
          }
        }
      }
    }
  }
}
```

## Inscrever-se nos fluxos de eventos da IPC
<a name="ipc-subscribe-operations"></a>

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 de IPC. Em seguida, o cliente IPC executa as funções do manipulador de assinaturas toda vez 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\$1\$1) 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:
+ [SubscribeToTopic](ipc-publish-subscribe.md#ipc-operation-subscribetotopic)
+ [SubscribeToIoTCore](ipc-iot-core-mqtt.md#ipc-operation-subscribetoiotcore)
+ [SubscribeToComponentUpdates](ipc-component-lifecycle.md#ipc-operation-subscribetocomponentupdates)
+ [SubscribeToConfigurationUpdate](ipc-component-configuration.md#ipc-operation-subscribetoconfigurationupdate)
+ [SubscribeToValidateConfigurationUpdates](ipc-component-configuration.md#ipc-operation-subscribetovalidateconfigurationupdates)

**Topics**
+ [Definir manipuladores de assinaturas](#ipc-define-subscription-handlers)
+ [Exemplo de manipuladores de assinatura](#ipc-subscription-handler-examples)

### Definir manipuladores de assinaturas
<a name="ipc-define-subscription-handlers"></a>

Para definir um manipulador de assinatura, defina funções de retorno de chamada que manipulem 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 do Java e do Python SDKs, você pode definir essas funções sem criar uma classe de manipulador de assinatura.

------
#### [ Java ]

Se você usar o cliente IPC V1, deverá implementar a interface genérica`software.amazon.awssdk.eventstreamrpc.StreamResponseHandler<StreamEventType>`. *StreamEventType*é o tipo de mensagem de evento para a operação de assinatura. Defina as funções a seguir para lidar com mensagens de eventos, erros e encerramento de fluxo.

Se você usa o cliente IPC V2, pode definir essas funções fora de uma classe de manipulador de assinatura ou usar [expressões lambda](https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html).

`void onStreamEvent(StreamEventType event)`  
O callback que o cliente IPC chama quando recebe uma mensagem de evento, como uma mensagem MQTT ou uma notificação de atualização de componente.

`boolean onStreamError(Throwable error)`  
O callback que o cliente IPC chama quando ocorre um erro de fluxo.  
<a name="ipc-subscription-handler-on-stream-error-return-value"></a>Retorne “true” para fechar o fluxo de assinatura como resultado do erro ou retorne “false” para manter o fluxo aberto.

`void onStreamClosed()`  
O callback que o cliente IPC chama quando o fluxo fecha.

------
#### [ Python ]

Se você usar o cliente IPC V1, deverá estender a classe do manipulador de resposta de fluxo que corresponde à operação de assinatura. AWS IoT Device SDK Isso inclui uma classe de gerenciador de assinaturas para cada operação de assinatura. *StreamEventType*é o tipo de mensagem de evento para a operação de assinatura. Defina as funções a seguir para lidar com mensagens de eventos, erros e encerramento de fluxo.

Se você usa o cliente IPC V2, pode definir essas funções fora de uma classe de manipulador de assinatura ou usar [expressões lambda](https://docs.python.org/3/tutorial/controlflow.html#lambda-expressions).

`def on_stream_event(self, event: StreamEventType) -> None`  
O callback que o cliente IPC chama quando recebe uma mensagem de evento, como uma mensagem MQTT ou uma notificação de atualização de componente.

`def on_stream_error(self, error: Exception) -> bool`  
O callback que o cliente IPC chama quando ocorre um erro de fluxo.  
<a name="ipc-subscription-handler-on-stream-error-return-value"></a>Retorne “true” para fechar o fluxo de assinatura como resultado do erro ou retorne “false” para manter o fluxo aberto.

`def on_stream_closed(self) -> None`  
O callback que o cliente IPC chama quando o fluxo fecha.

------
#### [ C\$1\$1 (IPC client V1) ]

Implemente uma classe derivada da classe do manipulador de resposta de fluxo que corresponda à operação de assinatura. AWS IoT Device SDK Isso inclui uma classe base de manipulador de assinaturas para cada operação de assinatura. *StreamEventType*é o tipo de mensagem de evento para a operação de assinatura. Defina as funções a seguir para lidar com mensagens de eventos, erros e encerramento de fluxo.

`void OnStreamEvent(StreamEventType *event)`  
O callback que o cliente IPC chama quando recebe uma mensagem de evento, como uma mensagem MQTT ou uma notificação de atualização de componente.

`bool OnStreamError(OperationError *error)`  
O callback que o cliente IPC chama quando ocorre um erro de fluxo.  
<a name="ipc-subscription-handler-on-stream-error-return-value"></a>Retorne “true” para fechar o fluxo de assinatura como resultado do erro ou retorne “false” para manter o fluxo aberto.

`void OnStreamClosed()`  
O callback que o cliente IPC chama quando o fluxo fecha.

------
#### [ JavaScript ]

Implemente uma classe derivada da classe do manipulador de resposta de fluxo que corresponda à operação de assinatura. AWS IoT Device SDK Isso inclui uma classe base de manipulador de assinaturas para cada operação de assinatura. *StreamEventType*é o tipo de mensagem de evento para a operação de assinatura. Defina as funções a seguir para lidar com mensagens de eventos, erros e encerramento de fluxo.

`on(event: 'ended', listener: StreamingOperationEndedListener)`  
O callback que o cliente IPC chama quando o fluxo fecha.

`on(event: 'streamError', listener: StreamingRpcErrorListener)`  
O callback que o cliente IPC chama quando ocorre um erro de fluxo.  
<a name="ipc-subscription-handler-on-stream-error-return-value"></a>Retorne “true” para fechar o fluxo de assinatura como resultado do erro ou retorne “false” para manter o fluxo aberto.

`on(event: 'message', listener: (message: InboundMessageType) => void)`  
O callback que o cliente IPC chama quando recebe uma mensagem de evento, como uma mensagem MQTT ou uma notificação de atualização de componente.

------

### Exemplo de manipuladores de assinatura
<a name="ipc-subscription-handler-examples"></a>

O exemplo a seguir demonstra como usar a operação [SubscribeToTopic](ipc-publish-subscribe.md#ipc-operation-subscribetotopic) e um manipulador de assinaturas para assinar o sistema local de publicação e assinatura de mensagens.

------
#### [ Java (IPC client V2) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-java-v2"></a>

```
package com.aws.greengrass.docs.samples.ipc;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClientV2;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.*;

import java.nio.charset.StandardCharsets;
import java.util.Optional;

public class SubscribeToTopicV2 {

    public static void main(String[] args) {
        String topic = args[0];
        try (GreengrassCoreIPCClientV2 ipcClient = GreengrassCoreIPCClientV2.builder().build()) {
            SubscribeToTopicRequest request = new SubscribeToTopicRequest().withTopic(topic);
            GreengrassCoreIPCClientV2.StreamingResponse<SubscribeToTopicResponse,
                    SubscribeToTopicResponseHandler> response =
                    ipcClient.subscribeToTopic(request, SubscribeToTopicV2::onStreamEvent,
                            Optional.of(SubscribeToTopicV2::onStreamError),
                            Optional.of(SubscribeToTopicV2::onStreamClosed));
            SubscribeToTopicResponseHandler responseHandler = response.getHandler();
            System.out.println("Successfully subscribed to topic: " + topic);

            // Keep the main thread alive, or the process will exit.
            try {
                while (true) {
                    Thread.sleep(10000);
                }
            } catch (InterruptedException e) {
                System.out.println("Subscribe interrupted.");
            }

            // To stop subscribing, close the stream.
            responseHandler.closeStream();
        } catch (Exception e) {
            if (e.getCause() instanceof UnauthorizedError) {
                System.err.println("Unauthorized error while publishing to topic: " + topic);
            } else {
                System.err.println("Exception occurred when using IPC.");
            }
            e.printStackTrace();
            System.exit(1);
        }
    }

    public static void onStreamEvent(SubscriptionResponseMessage subscriptionResponseMessage) {
        try {
            BinaryMessage binaryMessage = subscriptionResponseMessage.getBinaryMessage();
            String message = new String(binaryMessage.getMessage(), StandardCharsets.UTF_8);
            String topic = binaryMessage.getContext().getTopic();
            System.out.printf("Received new message on topic %s: %s%n", topic, message);
        } catch (Exception e) {
            System.err.println("Exception occurred while processing subscription response " +
                    "message.");
            e.printStackTrace();
        }
    }

    public static boolean onStreamError(Throwable error) {
        System.err.println("Received a stream error.");
        error.printStackTrace();
        return false; // Return true to close stream, false to keep stream open.
    }

    public static void onStreamClosed() {
        System.out.println("Subscribe to topic stream closed.");
    }
}
```

------
#### [ Python (IPC client V2) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-python-v2"></a>

```
import sys
import time
import traceback

from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2
from awsiot.greengrasscoreipc.model import (
    SubscriptionResponseMessage,
    UnauthorizedError
)


def main():
    args = sys.argv[1:]
    topic = args[0]

    try:
        ipc_client = GreengrassCoreIPCClientV2()
        # Subscription operations return a tuple with the response and the operation.
        _, operation = ipc_client.subscribe_to_topic(topic=topic, on_stream_event=on_stream_event,
                                                     on_stream_error=on_stream_error, on_stream_closed=on_stream_closed)
        print('Successfully subscribed to topic: ' + topic)

        # Keep the main thread alive, or the process will exit.
        try:
            while True:
                time.sleep(10)
        except InterruptedError:
            print('Subscribe interrupted.')

        # To stop subscribing, close the stream.
        operation.close()
    except UnauthorizedError:
        print('Unauthorized error while subscribing to topic: ' +
              topic, file=sys.stderr)
        traceback.print_exc()
        exit(1)
    except Exception:
        print('Exception occurred', file=sys.stderr)
        traceback.print_exc()
        exit(1)


def on_stream_event(event: SubscriptionResponseMessage) -> None:
    try:
        message = str(event.binary_message.message, 'utf-8')
        topic = event.binary_message.context.topic
        print('Received new message on topic %s: %s' % (topic, message))
    except:
        traceback.print_exc()


def on_stream_error(error: Exception) -> bool:
    print('Received a stream error.', file=sys.stderr)
    traceback.print_exc()
    return False  # Return True to close stream, False to keep stream open.


def on_stream_closed() -> None:
    print('Subscribe to topic stream closed.')


if __name__ == '__main__':
    main()
```

------
#### [ C\$1\$1 (IPC client V1) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-cpp"></a>

```
#include <iostream>

#include </crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>

using namespace Aws::Crt;
using namespace Aws::Greengrass;

class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
    public:
        virtual ~SubscribeResponseHandler() {}

    private:
        void OnStreamEvent(SubscriptionResponseMessage *response) override {
            auto jsonMessage = response->GetJsonMessage();
            if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
                auto messageString = jsonMessage.value().GetMessage().value().View().WriteReadable();
                // Handle JSON message.
            } else {
                auto binaryMessage = response->GetBinaryMessage();
                if (binaryMessage.has_value() && binaryMessage.value().GetMessage().has_value()) {
                    auto messageBytes = binaryMessage.value().GetMessage().value();
                    std::string messageString(messageBytes.begin(), messageBytes.end());
                    // Handle binary message.
                }
            }
        }

        bool OnStreamError(OperationError *error) override {
            // Handle error.
            return false; // Return true to close stream, false to keep stream open.
        }

        void OnStreamClosed() override {
            // Handle close.
        }
};

class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
    void OnConnectCallback() override {
        // Handle connection to IPC service.
    }

    void OnDisconnectCallback(RpcError error) override {
        // Handle disconnection from IPC service.
    }

    bool OnErrorCallback(RpcError error) override {
        // Handle IPC service connection error.
        return true;
    }
};

int main() {
    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);
    }

    String topic("my/topic");
    int timeout = 10;

    SubscribeToTopicRequest request;
    request.SetTopic(topic);

    //SubscribeResponseHandler streamHandler;
    auto streamHandler = MakeShared<SubscribeResponseHandler>(DefaultAllocator());
    auto operation = ipcClient.NewSubscribeToTopic(streamHandler);
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (!response) {
        // Handle error.
        auto errorType = response.GetResultType();
        if (errorType == OPERATION_ERROR) {
            auto *error = response.GetOperationError();
            (void)error;
            // Handle operation error.
        } else {
            // Handle RPC error.
        }
        exit(-1);
    }

    // Keep the main thread alive, or the process will exit.
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(10));
    }

    operation->Close();
    return 0;
}
```

------
#### [ JavaScript ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-nodejs"></a>

```
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
import {SubscribeToTopicRequest, SubscriptionResponseMessage} from "aws-iot-device-sdk-v2/dist/greengrasscoreipc/model";
import {RpcError} from "aws-iot-device-sdk-v2/dist/eventstream_rpc";
 
class SubscribeToTopic {
    private ipcClient : greengrasscoreipc.Client
    private readonly topic : string;
 
    constructor() {
        // define your own constructor, e.g.
        this.topic = "<define_your_topic>";
        this.subscribeToTopic().then(r => console.log("Started workflow"));
    }
 
    private async subscribeToTopic() {
        try {
            this.ipcClient = await getIpcClient();
 
            const subscribeToTopicRequest : SubscribeToTopicRequest = {
                topic: this.topic,
            }
 
            const streamingOperation = this.ipcClient.subscribeToTopic(subscribeToTopicRequest, undefined); // conditionally apply options
 
            streamingOperation.on("message", (message: SubscriptionResponseMessage) => {
                // parse the message depending on your use cases, e.g.
                if(message.binaryMessage && message.binaryMessage.message) {
                    const receivedMessage = message.binaryMessage?.message.toString();
                }
            });
 
            streamingOperation.on("streamError", (error : RpcError) => {
                // define your own error handling logic
            })
 
            streamingOperation.on("ended", () => {
                // define your own logic
            })
 
            await streamingOperation.activate();
 
            // Keep the main thread alive, or the process will exit.
            await new Promise((resolve) => setTimeout(resolve, 10000))
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
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
    }
}
 
// starting point
const subscribeToTopic = new SubscribeToTopic();
```

------
#### [ Rust ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
use gg_sdk::{Sdk, SubscribeToTopicPayload};
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let topic = "my/topic";

    let callback = |topic: &str, payload: SubscribeToTopicPayload| match payload
    {
        SubscribeToTopicPayload::Binary(message) => {
            let message = String::from_utf8_lossy(message);
            println!("Received new message on topic {topic}: {message}");
        }
        SubscribeToTopicPayload::Json(_) => {
            println!("Received new message on topic {topic}: (JSON message)");
        }
    };

    let _sub = sdk
        .subscribe_to_topic(topic, &callback)
        .expect("Failed to subscribe to topic");

    println!("Successfully subscribed to topic: {topic}");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

------
#### [ C ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
#include <assert.h>
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <gg/types.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx, GgBuffer topic, GgObject payload, GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    if (gg_obj_type(payload) == GG_TYPE_BUF) {
        GgBuffer message = gg_obj_into_buf(payload);
        printf(
            "Received new message on topic %.*s: %.*s\n",
            (int) topic.len,
            topic.data,
            (int) message.len,
            message.data
        );
    } else {
        assert(gg_obj_type(payload) == GG_TYPE_MAP);
        printf(
            "Received new message on topic %.*s: (JSON message)\n",
            (int) topic.len,
            topic.data
        );
    }
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer topic = GG_STR("my/topic");

    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_topic(
        topic, on_subscription_response, NULL, &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to subscribe to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully subscribed to topic: %.*s\n", (int) topic.len, topic.data
    );

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the stream.
    ggipc_close_subscription(handle);
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
#include <gg/ipc/client.hpp>
#include <gg/object.hpp>
#include <unistd.h>
#include <cassert>
#include <iostream>

class ResponseHandler : public gg::ipc::LocalTopicCallback {
    void operator()(
        std::string_view topic,
        gg::Object payload,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        if (payload.index() == GG_TYPE_BUF) {
            std::cout << "Received new message on topic " << topic << ": "
                      << get<gg::Buffer>(payload) << "\n";
        } else {
            assert(payload.index() == GG_TYPE_MAP);
            std::cout << "Received new message on topic " << topic
                      << ": (JSON message)\n";
        }
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view topic = "my/topic";

    static ResponseHandler handler;
    error = client.subscribe_to_topic(topic, handler);
    if (error) {
        std::cerr << "Failed to subscribe to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to topic: " << topic << "\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

------

## Práticas recomendadas de IPC
<a name="ipc-best-practices"></a>

As práticas recomendadas para usar o IPC em componentes personalizados diferem entre o cliente IPC V1 e o cliente IPC V2. Siga as práticas recomendadas para a versão do cliente IPC que você usa.

------
#### [ IPC client V2 ]

O cliente IPC V2 executa funções de callback em um thread separado, portanto, em comparação com o cliente IPC V1, há menos diretrizes a serem seguidas ao usar a IPC e escrever funções de manipulador de assinatura.
+ <a name="ipc-best-practice-reuse-one-client"></a>**Reutilizar um cliente IPC**

  Depois de criar um cliente IPC, mantenha-o aberto e reutilize-o para todas as operações de IPC. A criação de vários clientes usa recursos extras e pode resultar em vazamentos de recursos.
+ **Processar exceções**

  O cliente IPC V2 registra exceções não detectadas nas funções do manipulador de assinaturas. Você deve capturar exceções nas funções do manipulador para lidar com erros que ocorrem no seu código.

------
#### [ IPC client V1 ]

O cliente IPC V1 usa um único thread que se comunica com o servidor IPC e chama os manipuladores de assinatura. Você deve considerar esse comportamento síncrono ao escrever funções de manipulador de assinaturas.
+ <a name="ipc-best-practice-reuse-one-client"></a>**Reutilizar um cliente IPC**

  Depois de criar um cliente IPC, mantenha-o aberto e reutilize-o para todas as operações de IPC. A criação de vários clientes usa recursos extras e pode resultar em vazamentos de recursos.
+ **Executar o código de bloqueio de forma assíncrona**

  O cliente IPC V1 não pode enviar novas solicitações ou processar novas mensagens de eventos enquanto o thread está bloqueado. Você deve executar o código de bloqueio em um encadeamento separado, executado a partir da função de manipulador. O código de bloqueio inclui `sleep` chamadas, loops que são executados continuamente e I/O solicitações síncronas que demoram para serem concluídas.
+ **Enviar novas solicitações de IPC de forma assíncrona**

  O cliente IPC V1 não pode enviar uma nova solicitação de dentro das funções do manipulador de assinatura, porque a solicitação bloqueia a função do manipulador se você esperar por uma resposta. Você deve enviar solicitações de IPC em um thread separado, executado a partir da função do manipulador.
+ **Processar exceções**

  O cliente IPC V1 não manipula exceções não detectadas nas funções do manipulador de assinaturas. Se sua função de manipulador gerar uma exceção, a assinatura será encerrada e a exceção não aparecerá nos logs do componente. Você deve capturar exceções nas funções do manipulador para manter a assinatura aberta e com erros que ocorrem no seu código.

------

# Publicar/assinar mensagens locais
<a name="ipc-publish-subscribe"></a>

O sistema de mensagens de publicação/assinatura (pubsub) permitem que você envie e receba mensagens em tópicos. Os componentes podem publicar mensagens em tópicos para enviar mensagens para outros componentes. Em seguida, os componentes inscritos nesse tópico podem agir nas mensagens que recebem.

**nota**  
Você não pode usar esse serviço de publish/subscribe IPC para publicar ou assinar o AWS IoT Core MQTT. Para obter mais informações sobre como trocar mensagens com o AWS IoT Core MQTT, consulte[Publique/assine mensagens MQTT AWS IoT Core](ipc-iot-core-mqtt.md).

**Topics**
+ [Versões mínimas do SDK](#ipc-publish-subscribe-sdk-versions)
+ [Autorização](#ipc-publish-subscribe-authorization)
+ [PublishToTopic](#ipc-operation-publishtotopic)
+ [SubscribeToTopic](#ipc-operation-subscribetotopic)
+ [Exemplos](#ipc-publish-subscribe-examples)

## Versões mínimas do SDK
<a name="ipc-publish-subscribe-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para publicar e assinar mensagens de e para tópicos locais.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK for JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-publish-subscribe-authorization"></a>

Para usar publish/subscribe mensagens locais em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente envie e receba mensagens para tópicos. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização para publish/subscribe mensagens têm as seguintes propriedades.

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


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#PublishToTopic`  |  Permite que um componente publique mensagens nos tópicos que você especificar.  |  Uma string de tópicos, como `test/topic`. Use um `*` para corresponder a qualquer combinação de caracteres em um tópico. Essa string de tópico não aceita caracteres curinga de tópico do MQTT (`#` e `+`).  | 
|  `aws.greengrass#SubscribeToTopic`  |  Permite que um componente publique mensagens nos tópicos do MQTT que você especificar.  |  Uma string de tópicos, como `test/topic`. Use um `*` para corresponder a qualquer combinação de caracteres em um tópico. <a name="ipc-local-publish-subscribe-authorization-mqtt-wildcards"></a>No [núcleo do Greengrass](greengrass-nucleus-component.md) 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`.  | 
|  `*`  |  Permite que um componente publique e assine mensagens para os tópicos que você especificar.  |  Uma string de tópicos, como `test/topic`. Use um `*` para corresponder a qualquer combinação de caracteres em um tópico. <a name="ipc-local-publish-subscribe-authorization-mqtt-wildcards"></a>No [núcleo do Greengrass](greengrass-nucleus-component.md) 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`.  | 

### Exemplos de política de autorização
<a name="ipc-publish-subscribe-authorization-policy-examples"></a>

Consulte o exemplo de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de política de autorização**  
O exemplo de política de autorização a seguir permite que um componente publique e assine em todos os tópicos.  

```
{
  "accessControl": {
    "aws.greengrass.ipc.pubsub": {
      "com.example.MyLocalPubSubComponent:pubsub:1": {
        "policyDescription": "Allows access to publish/subscribe to all topics.",
        "operations": [
          "aws.greengrass#PublishToTopic",
          "aws.greengrass#SubscribeToTopic"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}
```

## PublishToTopic
<a name="ipc-operation-publishtotopic"></a>

Publique uma mensagem em um tópico.

### Solicitação
<a name="ipc-operation-publishtotopic-request"></a>

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

`topic`  
O tópico no qual publicar a mensagem.

`publishMessage` (Python: `publish_message`)  
A mensagem a ser publicada. Esse objeto, `PublishMessage`, contém as informações a seguir. Você deve especificar `jsonMessage` ou `binaryMessage`.  <a name="ipc-publish-subscribe-message-shape"></a>  
`jsonMessage` (Python: `json_message`)  
(Opcional) Uma mensagem JSON. Esse objeto, `JsonMessage`, contém as seguintes informações:    
`message`  
A mensagem JSON como um objeto.  
`context`  <a name="ipc-publish-subscribe-message-context-variable"></a>
O contexto da mensagem, como o tópico em que a mensagem foi publicada.  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md). A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para acessar o contexto da mensagem.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-publish-subscribe.html)
O software AWS IoT Greengrass Core usa os mesmos objetos de mensagem nas `SubscribeToTopic` operações `PublishToTopic` e. O software AWS IoT Greengrass Core define esse objeto de contexto nas mensagens quando você se inscreve e ignora esse objeto de contexto nas mensagens que você publica.
Esse objeto, `MessageContext`, contém as seguintes informações:    
`topic`  
O tópico em que a mensagem foi publicada.  
`binaryMessage` (Python: `binary_message`)  
(Opcional) Uma mensagem binária. Esse objeto, `BinaryMessage`, contém as seguintes informações:    
`message`  
A mensagem binária como uma bolha.  
`context`  <a name="ipc-publish-subscribe-message-context-variable"></a>
O contexto da mensagem, como o tópico em que a mensagem foi publicada.  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md). A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para acessar o contexto da mensagem.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-publish-subscribe.html)
O software AWS IoT Greengrass Core usa os mesmos objetos de mensagem nas `SubscribeToTopic` operações `PublishToTopic` e. O software AWS IoT Greengrass Core define esse objeto de contexto nas mensagens quando você se inscreve e ignora esse objeto de contexto nas mensagens que você publica.
Esse objeto, `MessageContext`, contém as seguintes informações:    
`topic`  
O tópico em que a mensagem foi publicada.

### Resposta
<a name="ipc-operation-publishtotopic-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

### Exemplos
<a name="ipc-operation-publishtotopic-examples"></a>

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

------
#### [ Java (IPC client V2) ]

**Example Exemplo: publicar uma mensagem binária**  

```
package com.aws.greengrass.docs.samples.ipc;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClientV2;
import software.amazon.awssdk.aws.greengrass.model.BinaryMessage;
import software.amazon.awssdk.aws.greengrass.model.PublishMessage;
import software.amazon.awssdk.aws.greengrass.model.PublishToTopicRequest;
import software.amazon.awssdk.aws.greengrass.model.PublishToTopicResponse;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;

import java.nio.charset.StandardCharsets;

public class PublishToTopicV2 {

    public static void main(String[] args) {
        String topic = args[0];
        String message = args[1];
        try (GreengrassCoreIPCClientV2 ipcClient = GreengrassCoreIPCClientV2.builder().build()) {
            PublishToTopicV2.publishBinaryMessageToTopic(ipcClient, topic, message);
            System.out.println("Successfully published to topic: " + topic);
        } catch (Exception e) {
            if (e.getCause() instanceof UnauthorizedError) {
                System.err.println("Unauthorized error while publishing to topic: " + topic);
            } else {
                System.err.println("Exception occurred when using IPC.");
            }
            e.printStackTrace();
            System.exit(1);
        }
    }

    public static PublishToTopicResponse publishBinaryMessageToTopic(
            GreengrassCoreIPCClientV2 ipcClient, String topic, String message) throws InterruptedException {
        BinaryMessage binaryMessage =
                new BinaryMessage().withMessage(message.getBytes(StandardCharsets.UTF_8));
        PublishMessage publishMessage = new PublishMessage().withBinaryMessage(binaryMessage);
        PublishToTopicRequest publishToTopicRequest =
                new PublishToTopicRequest().withTopic(topic).withPublishMessage(publishMessage);
        return ipcClient.publishToTopic(publishToTopicRequest);
    }
}
```

------
#### [ Python (IPC client V2) ]

**Example Exemplo: publicar uma mensagem binária**  

```
import sys
import traceback

from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2
from awsiot.greengrasscoreipc.model import (
    PublishMessage,
    BinaryMessage
)


def main():
    args = sys.argv[1:]
    topic = args[0]
    message = args[1]

    try:
        ipc_client = GreengrassCoreIPCClientV2()
        publish_binary_message_to_topic(ipc_client, topic, message)
        print('Successfully published to topic: ' + topic)
    except Exception:
        print('Exception occurred', file=sys.stderr)
        traceback.print_exc()
        exit(1)


def publish_binary_message_to_topic(ipc_client, topic, message):
    binary_message = BinaryMessage(message=bytes(message, 'utf-8'))
    publish_message = PublishMessage(binary_message=binary_message)
    return ipc_client.publish_to_topic(topic=topic, publish_message=publish_message)


if __name__ == '__main__':
    main()
```

------
#### [ C\$1\$1 (IPC client V1) ]

**Example Exemplo: publicar uma mensagem binária**  

```
#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 {
        // Handle connection to IPC service.
    }

    void OnDisconnectCallback(RpcError error) override {
        // Handle disconnection from IPC service.
    }

    bool OnErrorCallback(RpcError error) override {
        // Handle IPC service connection error.
        return true;
    }
};

int main() {
    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);
    }

    String topic("my/topic");
    String message("Hello, World!");
    int timeout = 10;

    PublishToTopicRequest request;
    Vector<uint8_t> messageData({message.begin(), message.end()});
    BinaryMessage binaryMessage;
    binaryMessage.SetMessage(messageData);
    PublishMessage publishMessage;
    publishMessage.SetBinaryMessage(binaryMessage);
    request.SetTopic(topic);
    request.SetPublishMessage(publishMessage);

    auto operation = ipcClient.NewPublishToTopic();
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (!response) {
        // Handle error.
        auto errorType = response.GetResultType();
        if (errorType == OPERATION_ERROR) {
            auto *error = response.GetOperationError();
            (void)error;
            // Handle operation error.
        } else {
            // Handle RPC error.
        }
    }
    return 0;
}
```

------
#### [ JavaScript ]

**Example Exemplo: publicar uma mensagem binária**  

```
    
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
import {BinaryMessage, PublishMessage, PublishToTopicRequest} from "aws-iot-device-sdk-v2/dist/greengrasscoreipc/model";
 
class PublishToTopic {
    private ipcClient : greengrasscoreipc.Client
    private readonly topic : string;
    private readonly messageString : string;
 
    constructor() {
        // define your own constructor, e.g.
        this.topic = "<define_your_topic>";
        this.messageString = "<define_your_message_string>";
        this.publishToTopic().then(r => console.log("Started workflow"));
    }
 
    private async publishToTopic() {
        try {
            this.ipcClient = await getIpcClient();
 
            const binaryMessage : BinaryMessage = {
                message: this.messageString
            }
 
            const publishMessage : PublishMessage = {
                binaryMessage: binaryMessage
            }
 
            const request : PublishToTopicRequest = {
                topic: this.topic,
                publishMessage: publishMessage
            }
 
            this.ipcClient.publishToTopic(request).finally(() => console.log(`Published message ${publishMessage.binaryMessage?.message} to topic`))
 
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
 
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
    }
}
 
// starting point
const publishToTopic = new PublishToTopic();
```

------
#### [ Rust ]

**Example Exemplo: publicar uma mensagem binária**  

```
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let message = b"Hello, World";
    let topic = "my/topic";

    sdk.publish_to_topic_binary(topic, message)
        .expect("Failed to publish to topic");

    println!("Successfully published to topic: {topic}");
}
```

------
#### [ C ]

**Example Exemplo: publicar uma mensagem binária**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer message = GG_STR("Hello, World");
    GgBuffer topic = GG_STR("my/topic");

    err = ggipc_publish_to_topic_binary(topic, message);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to publish to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully published to topic: %.*s\n", (int) topic.len, topic.data
    );
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: publicar uma mensagem binária**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view message = "Hello, World";
    std::string_view topic = "my/topic";

    error = client.publish_to_topic(topic, message);
    if (error) {
        std::cerr << "Failed to publish to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully published to topic: " << topic << "\n";
}
```

------

## SubscribeToTopic
<a name="ipc-operation-subscribetotopic"></a>

Assine mensagens sobre um tópico.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `SubscriptionResponseMessage`

### Solicitação
<a name="ipc-operation-subscribetotopic-request"></a>

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

`topic`  
O tópico a ser assinado.  
No [Greengrass nucleus](greengrass-nucleus-component.md) v2.6.0 e versões posteriores, este tópico oferece suporte aos curingas do tópico MQTT (e). `#` `+`

`receiveMode` (Python: `receive_mode`)  
(Opcional) O comportamento que especifica se o componente recebe mensagens de si mesmo. Você pode alterar esse comportamento para permitir que um componente atue em suas próprias mensagens. O comportamento padrão depende se o tópico contém um curinga MQTT. Escolha uma das seguintes opções:  
+ `RECEIVE_ALL_MESSAGES`: receba todas as mensagens que correspondam ao tópico, incluindo mensagens do componente que se inscreve.

  Esse modo é a opção padrão quando você se inscreve em um tópico que não contém um curinga MQTT.
+ `RECEIVE_MESSAGES_FROM_OTHERS`: receba todas as mensagens que correspondam ao tópico, exceto as mensagens do componente que se inscreve.

  Esse modo é a opção padrão quando você se inscreve em um tópico que contém um curinga MQTT.
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md). A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para definir o modo de recepção.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-publish-subscribe.html)

### Resposta
<a name="ipc-operation-subscribetotopic-response"></a>

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

`messages`  
O fluxo de mensagens. Esse objeto, `SubscriptionResponseMessage`, contém as informações a seguir. Cada mensagem contém `jsonMessage` ou`binaryMessage`.  <a name="ipc-publish-subscribe-message-shape"></a>  
`jsonMessage` (Python: `json_message`)  
(Opcional) Uma mensagem JSON. Esse objeto, `JsonMessage`, contém as seguintes informações:    
`message`  
A mensagem JSON como um objeto.  
`context`  <a name="ipc-publish-subscribe-message-context-variable"></a>
O contexto da mensagem, como o tópico em que a mensagem foi publicada.  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md). A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para acessar o contexto da mensagem.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-publish-subscribe.html)
O software AWS IoT Greengrass Core usa os mesmos objetos de mensagem nas `SubscribeToTopic` operações `PublishToTopic` e. O software AWS IoT Greengrass Core define esse objeto de contexto nas mensagens quando você se inscreve e ignora esse objeto de contexto nas mensagens que você publica.
Esse objeto, `MessageContext`, contém as seguintes informações:    
`topic`  
O tópico em que a mensagem foi publicada.  
`binaryMessage` (Python: `binary_message`)  
(Opcional) Uma mensagem binária. Esse objeto, `BinaryMessage`, contém as seguintes informações:    
`message`  
A mensagem binária como uma bolha.  
`context`  <a name="ipc-publish-subscribe-message-context-variable"></a>
O contexto da mensagem, como o tópico em que a mensagem foi publicada.  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md). A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para acessar o contexto da mensagem.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-publish-subscribe.html)
O software AWS IoT Greengrass Core usa os mesmos objetos de mensagem nas `SubscribeToTopic` operações `PublishToTopic` e. O software AWS IoT Greengrass Core define esse objeto de contexto nas mensagens quando você se inscreve e ignora esse objeto de contexto nas mensagens que você publica.
Esse objeto, `MessageContext`, contém as seguintes informações:    
`topic`  
O tópico em que a mensagem foi publicada.

`topicName` (Python: `topic_name`)  
O tópico em que a mensagem foi publicada.  
No momento, essa propriedade não é usada. No [Greengrass nucleus](greengrass-nucleus-component.md) v2.6.0 e versões posteriores, você pode obter o `(jsonMessage|binaryMessage).context.topic` valor de a para obter o tópico em `SubscriptionResponseMessage` que a mensagem foi publicada.

### Exemplos
<a name="ipc-operation-subscribetotopic-examples"></a>

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

------
#### [ Java (IPC client V2) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-java-v2"></a>

```
package com.aws.greengrass.docs.samples.ipc;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClientV2;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.*;

import java.nio.charset.StandardCharsets;
import java.util.Optional;

public class SubscribeToTopicV2 {

    public static void main(String[] args) {
        String topic = args[0];
        try (GreengrassCoreIPCClientV2 ipcClient = GreengrassCoreIPCClientV2.builder().build()) {
            SubscribeToTopicRequest request = new SubscribeToTopicRequest().withTopic(topic);
            GreengrassCoreIPCClientV2.StreamingResponse<SubscribeToTopicResponse,
                    SubscribeToTopicResponseHandler> response =
                    ipcClient.subscribeToTopic(request, SubscribeToTopicV2::onStreamEvent,
                            Optional.of(SubscribeToTopicV2::onStreamError),
                            Optional.of(SubscribeToTopicV2::onStreamClosed));
            SubscribeToTopicResponseHandler responseHandler = response.getHandler();
            System.out.println("Successfully subscribed to topic: " + topic);

            // Keep the main thread alive, or the process will exit.
            try {
                while (true) {
                    Thread.sleep(10000);
                }
            } catch (InterruptedException e) {
                System.out.println("Subscribe interrupted.");
            }

            // To stop subscribing, close the stream.
            responseHandler.closeStream();
        } catch (Exception e) {
            if (e.getCause() instanceof UnauthorizedError) {
                System.err.println("Unauthorized error while publishing to topic: " + topic);
            } else {
                System.err.println("Exception occurred when using IPC.");
            }
            e.printStackTrace();
            System.exit(1);
        }
    }

    public static void onStreamEvent(SubscriptionResponseMessage subscriptionResponseMessage) {
        try {
            BinaryMessage binaryMessage = subscriptionResponseMessage.getBinaryMessage();
            String message = new String(binaryMessage.getMessage(), StandardCharsets.UTF_8);
            String topic = binaryMessage.getContext().getTopic();
            System.out.printf("Received new message on topic %s: %s%n", topic, message);
        } catch (Exception e) {
            System.err.println("Exception occurred while processing subscription response " +
                    "message.");
            e.printStackTrace();
        }
    }

    public static boolean onStreamError(Throwable error) {
        System.err.println("Received a stream error.");
        error.printStackTrace();
        return false; // Return true to close stream, false to keep stream open.
    }

    public static void onStreamClosed() {
        System.out.println("Subscribe to topic stream closed.");
    }
}
```

------
#### [ Python (IPC client V2) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-python-v2"></a>

```
import sys
import time
import traceback

from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2
from awsiot.greengrasscoreipc.model import (
    SubscriptionResponseMessage,
    UnauthorizedError
)


def main():
    args = sys.argv[1:]
    topic = args[0]

    try:
        ipc_client = GreengrassCoreIPCClientV2()
        # Subscription operations return a tuple with the response and the operation.
        _, operation = ipc_client.subscribe_to_topic(topic=topic, on_stream_event=on_stream_event,
                                                     on_stream_error=on_stream_error, on_stream_closed=on_stream_closed)
        print('Successfully subscribed to topic: ' + topic)

        # Keep the main thread alive, or the process will exit.
        try:
            while True:
                time.sleep(10)
        except InterruptedError:
            print('Subscribe interrupted.')

        # To stop subscribing, close the stream.
        operation.close()
    except UnauthorizedError:
        print('Unauthorized error while subscribing to topic: ' +
              topic, file=sys.stderr)
        traceback.print_exc()
        exit(1)
    except Exception:
        print('Exception occurred', file=sys.stderr)
        traceback.print_exc()
        exit(1)


def on_stream_event(event: SubscriptionResponseMessage) -> None:
    try:
        message = str(event.binary_message.message, 'utf-8')
        topic = event.binary_message.context.topic
        print('Received new message on topic %s: %s' % (topic, message))
    except:
        traceback.print_exc()


def on_stream_error(error: Exception) -> bool:
    print('Received a stream error.', file=sys.stderr)
    traceback.print_exc()
    return False  # Return True to close stream, False to keep stream open.


def on_stream_closed() -> None:
    print('Subscribe to topic stream closed.')


if __name__ == '__main__':
    main()
```

------
#### [ C\$1\$1 (IPC client V1) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-cpp"></a>

```
#include <iostream>

#include </crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>

using namespace Aws::Crt;
using namespace Aws::Greengrass;

class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
    public:
        virtual ~SubscribeResponseHandler() {}

    private:
        void OnStreamEvent(SubscriptionResponseMessage *response) override {
            auto jsonMessage = response->GetJsonMessage();
            if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
                auto messageString = jsonMessage.value().GetMessage().value().View().WriteReadable();
                // Handle JSON message.
            } else {
                auto binaryMessage = response->GetBinaryMessage();
                if (binaryMessage.has_value() && binaryMessage.value().GetMessage().has_value()) {
                    auto messageBytes = binaryMessage.value().GetMessage().value();
                    std::string messageString(messageBytes.begin(), messageBytes.end());
                    // Handle binary message.
                }
            }
        }

        bool OnStreamError(OperationError *error) override {
            // Handle error.
            return false; // Return true to close stream, false to keep stream open.
        }

        void OnStreamClosed() override {
            // Handle close.
        }
};

class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
    void OnConnectCallback() override {
        // Handle connection to IPC service.
    }

    void OnDisconnectCallback(RpcError error) override {
        // Handle disconnection from IPC service.
    }

    bool OnErrorCallback(RpcError error) override {
        // Handle IPC service connection error.
        return true;
    }
};

int main() {
    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);
    }

    String topic("my/topic");
    int timeout = 10;

    SubscribeToTopicRequest request;
    request.SetTopic(topic);

    //SubscribeResponseHandler streamHandler;
    auto streamHandler = MakeShared<SubscribeResponseHandler>(DefaultAllocator());
    auto operation = ipcClient.NewSubscribeToTopic(streamHandler);
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (!response) {
        // Handle error.
        auto errorType = response.GetResultType();
        if (errorType == OPERATION_ERROR) {
            auto *error = response.GetOperationError();
            (void)error;
            // Handle operation error.
        } else {
            // Handle RPC error.
        }
        exit(-1);
    }

    // Keep the main thread alive, or the process will exit.
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(10));
    }

    operation->Close();
    return 0;
}
```

------
#### [ JavaScript ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  <a name="ipc-operation-subscribetotopic-example-nodejs"></a>

```
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
import {SubscribeToTopicRequest, SubscriptionResponseMessage} from "aws-iot-device-sdk-v2/dist/greengrasscoreipc/model";
import {RpcError} from "aws-iot-device-sdk-v2/dist/eventstream_rpc";
 
class SubscribeToTopic {
    private ipcClient : greengrasscoreipc.Client
    private readonly topic : string;
 
    constructor() {
        // define your own constructor, e.g.
        this.topic = "<define_your_topic>";
        this.subscribeToTopic().then(r => console.log("Started workflow"));
    }
 
    private async subscribeToTopic() {
        try {
            this.ipcClient = await getIpcClient();
 
            const subscribeToTopicRequest : SubscribeToTopicRequest = {
                topic: this.topic,
            }
 
            const streamingOperation = this.ipcClient.subscribeToTopic(subscribeToTopicRequest, undefined); // conditionally apply options
 
            streamingOperation.on("message", (message: SubscriptionResponseMessage) => {
                // parse the message depending on your use cases, e.g.
                if(message.binaryMessage && message.binaryMessage.message) {
                    const receivedMessage = message.binaryMessage?.message.toString();
                }
            });
 
            streamingOperation.on("streamError", (error : RpcError) => {
                // define your own error handling logic
            })
 
            streamingOperation.on("ended", () => {
                // define your own logic
            })
 
            await streamingOperation.activate();
 
            // Keep the main thread alive, or the process will exit.
            await new Promise((resolve) => setTimeout(resolve, 10000))
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
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
    }
}
 
// starting point
const subscribeToTopic = new SubscribeToTopic();
```

------
#### [ Rust ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
use gg_sdk::{Sdk, SubscribeToTopicPayload};
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let topic = "my/topic";

    let callback = |topic: &str, payload: SubscribeToTopicPayload| match payload
    {
        SubscribeToTopicPayload::Binary(message) => {
            let message = String::from_utf8_lossy(message);
            println!("Received new message on topic {topic}: {message}");
        }
        SubscribeToTopicPayload::Json(_) => {
            println!("Received new message on topic {topic}: (JSON message)");
        }
    };

    let _sub = sdk
        .subscribe_to_topic(topic, &callback)
        .expect("Failed to subscribe to topic");

    println!("Successfully subscribed to topic: {topic}");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

------
#### [ C ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
#include <assert.h>
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <gg/types.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx, GgBuffer topic, GgObject payload, GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    if (gg_obj_type(payload) == GG_TYPE_BUF) {
        GgBuffer message = gg_obj_into_buf(payload);
        printf(
            "Received new message on topic %.*s: %.*s\n",
            (int) topic.len,
            topic.data,
            (int) message.len,
            message.data
        );
    } else {
        assert(gg_obj_type(payload) == GG_TYPE_MAP);
        printf(
            "Received new message on topic %.*s: (JSON message)\n",
            (int) topic.len,
            topic.data
        );
    }
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer topic = GG_STR("my/topic");

    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_topic(
        topic, on_subscription_response, NULL, &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to subscribe to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully subscribed to topic: %.*s\n", (int) topic.len, topic.data
    );

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the stream.
    ggipc_close_subscription(handle);
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: Inscrever-se em publish/subscribe mensagens locais**  

```
#include <gg/ipc/client.hpp>
#include <gg/object.hpp>
#include <unistd.h>
#include <cassert>
#include <iostream>

class ResponseHandler : public gg::ipc::LocalTopicCallback {
    void operator()(
        std::string_view topic,
        gg::Object payload,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        if (payload.index() == GG_TYPE_BUF) {
            std::cout << "Received new message on topic " << topic << ": "
                      << get<gg::Buffer>(payload) << "\n";
        } else {
            assert(payload.index() == GG_TYPE_MAP);
            std::cout << "Received new message on topic " << topic
                      << ": (JSON message)\n";
        }
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view topic = "my/topic";

    static ResponseHandler handler;
    error = client.subscribe_to_topic(topic, handler);
    if (error) {
        std::cerr << "Failed to subscribe to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to topic: " << topic << "\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

------

## Exemplos
<a name="ipc-publish-subscribe-examples"></a>

Use os exemplos a seguir para aprender a usar o serviço publish/subscribe IPC em seus componentes.

### publish/subscribe Editor de exemplo (Java, cliente IPC V1)
<a name="ipc-publish-subscribe-example-publisher-java"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherJava",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherJava:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": [
              "aws.greengrass#PublishToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "java -jar {artifacts:path}/PubSubPublisher.jar"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherJava
ComponentVersion: '1.0.0'
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        'com.example.PubSubPublisherJava:pubsub:1':
          policyDescription: Allows access to publish to all topics.
          operations:
            - 'aws.greengrass#PublishToTopic'
          resources:
            - '*'
Manifests:
  - Lifecycle:
      Run: |-
        java -jar {artifacts:path}/PubSubPublisher.jar
```

------

O exemplo de aplicação Java a seguir demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0 */

package com.example.ipc.pubsub;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.*;
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 PubSubPublisher {

    public static void main(String[] args) {
        String message = "Hello from the pub/sub publisher (Java).";
        String topic = "test/topic/java";

        try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) {
            GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection);

            while (true) {
                PublishToTopicRequest publishRequest = new PublishToTopicRequest();
                PublishMessage publishMessage = new PublishMessage();
                BinaryMessage binaryMessage = new BinaryMessage();
                binaryMessage.setMessage(message.getBytes(StandardCharsets.UTF_8));
                publishMessage.setBinaryMessage(binaryMessage);
                publishRequest.setPublishMessage(publishMessage);
                publishRequest.setTopic(topic);
                CompletableFuture<PublishToTopicResponse> futureResponse = ipcClient
                        .publishToTopic(publishRequest, Optional.empty()).getResponse();

                try {
                    futureResponse.get(10, TimeUnit.SECONDS);
                    System.out.println("Successfully published to topic: " + topic);
                } catch (TimeoutException e) {
                    System.err.println("Timeout occurred while publishing to topic: " + topic);
                } catch (ExecutionException e) {
                    if (e.getCause() instanceof UnauthorizedError) {
                        System.err.println("Unauthorized error while publishing to topic: " + topic);
                    } else {
                        System.err.println("Execution exception while publishing to topic: " + topic);
                    }
                    throw e;
                }
                Thread.sleep(5000);
            }
        } catch (InterruptedException e) {
            System.out.println("Publisher interrupted.");
        } catch (Exception e) {
            System.err.println("Exception occurred when using IPC.");
            e.printStackTrace();
            System.exit(1);
        }
    }
}
```

### Exemplo de publish/subscribe assinante (Java, cliente IPC V1)
<a name="ipc-publish-subscribe-example-subscriber-java"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberJava",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberJava:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": [
              "aws.greengrass#SubscribeToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "java -jar {artifacts:path}/PubSubSubscriber.jar"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubSubscriberJava
ComponentVersion: '1.0.0'
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        'com.example.PubSubSubscriberJava:pubsub:1':
          policyDescription: Allows access to subscribe to all topics.
          operations:
            - 'aws.greengrass#SubscribeToTopic'
          resources:
            - '*'
Manifests:
  - Lifecycle:
      Run: |-
        java -jar {artifacts:path}/PubSubSubscriber.jar
```

------

O exemplo de aplicação Java a seguir demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens em outros componentes.

```
/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0 */

package com.example.ipc.pubsub;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.SubscribeToTopicResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicRequest;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToTopicResponse;
import software.amazon.awssdk.aws.greengrass.model.SubscriptionResponseMessage;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;

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 PubSubSubscriber {

    public static void main(String[] args) {
        String topic = "test/topic/java";

        try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) {
            GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection);

            SubscribeToTopicRequest subscribeRequest = new SubscribeToTopicRequest();
            subscribeRequest.setTopic(topic);
            SubscribeToTopicResponseHandler operationResponseHandler = ipcClient
                    .subscribeToTopic(subscribeRequest, Optional.of(new SubscribeResponseHandler()));
            CompletableFuture<SubscribeToTopicResponse> futureResponse = operationResponseHandler.getResponse();

            try {
                futureResponse.get(10, TimeUnit.SECONDS);
                System.out.println("Successfully subscribed to topic: " + topic);
            } catch (TimeoutException e) {
                System.err.println("Timeout occurred while subscribing to topic: " + topic);
                throw e;
            } catch (ExecutionException e) {
                if (e.getCause() instanceof UnauthorizedError) {
                    System.err.println("Unauthorized error while subscribing to topic: " + topic);
                } else {
                    System.err.println("Execution exception while subscribing to topic: " + topic);
                }
                throw e;
            }

            // Keep the main thread alive, or the process will exit.
            try {
                while (true) {
                    Thread.sleep(10000);
                }
            } catch (InterruptedException e) {
                System.out.println("Subscribe interrupted.");
            }
        } catch (Exception e) {
            System.err.println("Exception occurred when using IPC.");
            e.printStackTrace();
            System.exit(1);
        }
    }

    private static class SubscribeResponseHandler implements StreamResponseHandler<SubscriptionResponseMessage> {

        @Override
        public void onStreamEvent(SubscriptionResponseMessage subscriptionResponseMessage) {
            try {
                String message = new String(subscriptionResponseMessage.getBinaryMessage()
                        .getMessage(), StandardCharsets.UTF_8);
                System.out.println("Received new message: " + message);
            } catch (Exception e) {
                e.printStackTrace();
            }
        }

        @Override
        public boolean onStreamError(Throwable error) {
            System.err.println("Received a stream error.");
            error.printStackTrace();
            return false; // Return true to close stream, false to keep stream open.
        }

        @Override
        public void onStreamClosed() {
            System.out.println("Subscribe to topic stream closed.");
        }
    }
}
```

### publish/subscribe Editor de exemplo (Python, cliente IPC V1)
<a name="ipc-publish-subscribe-example-publisher-python"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherPython",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherPython:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": [
              "aws.greengrass#PublishToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "python3 -m pip install --user awsiotsdk",
        "Run": "python3 -u {artifacts:path}/pubsub_publisher.py"
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "install": "py -3 -m pip install --user awsiotsdk",
        "Run": "py -3 -u {artifacts:path}/pubsub_publisher.py"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherPython
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        com.example.PubSubPublisherPython:pubsub:1:
          policyDescription: Allows access to publish to all topics.
          operations:
            - aws.greengrass#PublishToTopic
          resources:
            - "*"
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install: python3 -m pip install --user awsiotsdk
      Run: python3 -u {artifacts:path}/pubsub_publisher.py
  - Platform:
      os: windows
    Lifecycle:
      install: py -3 -m pip install --user awsiotsdk
      Run: py -3 -u {artifacts:path}/pubsub_publisher.py
```

------

O exemplo de aplicação Python a seguir demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
import concurrent.futures
import sys
import time
import traceback

import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
    PublishToTopicRequest,
    PublishMessage,
    BinaryMessage,
    UnauthorizedError
)

                    
topic = "test/topic/python"
message = "Hello from the pub/sub publisher (Python)."
TIMEOUT = 10

try:
    ipc_client = awsiot.greengrasscoreipc.connect()

    while True:
        request = PublishToTopicRequest()
        request.topic = topic
        publish_message = PublishMessage()
        publish_message.binary_message = BinaryMessage()
        publish_message.binary_message.message = bytes(message, "utf-8")
        request.publish_message = publish_message
        operation = ipc_client.new_publish_to_topic()
        operation.activate(request)
        future_response = operation.get_response()

        try:
            future_response.result(TIMEOUT)
            print('Successfully published to topic: ' + topic)
        except concurrent.futures.TimeoutError:
            print('Timeout occurred while publishing to topic: ' + topic, file=sys.stderr)
        except UnauthorizedError as e:
            print('Unauthorized error while publishing to topic: ' + topic, file=sys.stderr)
            raise e
        except Exception as e:
            print('Exception while publishing to topic: ' + topic, file=sys.stderr)
            raise e
        time.sleep(5)
except InterruptedError:
    print('Publisher interrupted.')
except Exception:
    print('Exception occurred when using IPC.', file=sys.stderr)
    traceback.print_exc()
    exit(1)
```

### Exemplo de publish/subscribe assinante (Python, cliente IPC V1)
<a name="ipc-publish-subscribe-example-subscriber-python"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberPython",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberPython:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": [
              "aws.greengrass#SubscribeToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "python3 -m pip install --user awsiotsdk",
        "Run": "python3 -u {artifacts:path}/pubsub_subscriber.py"
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "install": "py -3 -m pip install --user awsiotsdk",
        "Run": "py -3 -u {artifacts:path}/pubsub_subscriber.py"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubSubscriberPython
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        com.example.PubSubSubscriberPython:pubsub:1:
          policyDescription: Allows access to subscribe to all topics.
          operations:
            - aws.greengrass#SubscribeToTopic
          resources:
            - "*"
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install: python3 -m pip install --user awsiotsdk
      Run: python3 -u {artifacts:path}/pubsub_subscriber.py
  - Platform:
      os: windows
    Lifecycle:
      install: py -3 -m pip install --user awsiotsdk
      Run: py -3 -u {artifacts:path}/pubsub_subscriber.py
```

------

O exemplo de aplicação Python a seguir demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens em outros componentes.

```
import concurrent.futures
import sys
import time
import traceback

import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
    SubscribeToTopicRequest,
    SubscriptionResponseMessage,
    UnauthorizedError
)

topic = "test/topic/python"
TIMEOUT = 10

                    
class StreamHandler(client.SubscribeToTopicStreamHandler):
    def __init__(self):
        super().__init__()

    def on_stream_event(self, event: SubscriptionResponseMessage) -> None:
        try:
            message = str(event.binary_message.message, "utf-8")
            print("Received new message: " + message)
        except:
            traceback.print_exc()

    def on_stream_error(self, error: Exception) -> bool:
        print("Received a stream error.", file=sys.stderr)
        traceback.print_exc()
        return False  # Return True to close stream, False to keep stream open.

    def on_stream_closed(self) -> None:
        print('Subscribe to topic stream closed.')


try:
    ipc_client = awsiot.greengrasscoreipc.connect()

    request = SubscribeToTopicRequest()
    request.topic = topic
    handler = StreamHandler()
    operation = ipc_client.new_subscribe_to_topic(handler)
    operation.activate(request)
    future_response = operation.get_response()
    
    try:
        future_response.result(TIMEOUT)
        print('Successfully subscribed to topic: ' + topic)
    except concurrent.futures.TimeoutError as e:
        print('Timeout occurred while subscribing to topic: ' + topic, file=sys.stderr)
        raise e
    except UnauthorizedError as e:
        print('Unauthorized error while subscribing to topic: ' + topic, file=sys.stderr)
        raise e
    except Exception as e:
        print('Exception while subscribing to topic: ' + topic, file=sys.stderr)
        raise e

    # Keep the main thread alive, or the process will exit.
    try:
        while True:
            time.sleep(10)
    except InterruptedError:
        print('Subscribe interrupted.')
except Exception:
    print('Exception occurred when using IPC.', file=sys.stderr)
    traceback.print_exc()
    exit(1)
```

### publish/subscribe Editor de exemplo (C\$1\$1, cliente IPC V1)
<a name="ipc-publish-subscribe-example-publisher-cpp"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherCpp:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": [
              "aws.greengrass#PublishToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "{artifacts:path}/greengrassv2_pubsub_publisher"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubPublisherCpp/1.0.0/greengrassv2_pubsub_publisher",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubPublisherCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        com.example.PubSubPublisherCpp:pubsub:1:
          policyDescription: Allows access to publish to all topics.
          operations:
            - aws.greengrass#PublishToTopic
          resources:
            - "*"
Manifests:
  - Lifecycle:
      Run: "{artifacts:path}/greengrassv2_pubsub_publisher"
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubPublisherCpp/1.0.0/greengrassv2_pubsub_publisher
        Permission:
          Execute: OWNER
```

------

O exemplo de aplicação C\$1\$1 a seguir demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
#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() {
    String message("Hello from the pub/sub publisher (C++).");
    String topic("test/topic/cpp");
    int timeout = 10;

    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);
    }

    while (true) {
        PublishToTopicRequest request;
        Vector<uint8_t> messageData({message.begin(), message.end()});
        BinaryMessage binaryMessage;
        binaryMessage.SetMessage(messageData);
        PublishMessage publishMessage;
        publishMessage.SetBinaryMessage(binaryMessage);
        request.SetTopic(topic);
        request.SetPublishMessage(publishMessage);

        auto operation = ipcClient.NewPublishToTopic();
        auto activate = operation->Activate(request, nullptr);
        activate.wait();

        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);
        }

        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);
        }

        std::this_thread::sleep_for(std::chrono::seconds(5));
    }

    return 0;
}
```

### Exemplo de publish/subscribe assinante (C\$1\$1, cliente IPC V1)
<a name="ipc-publish-subscribe-example-subscriber-cpp"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberCpp:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": [
              "aws.greengrass#SubscribeToTopic"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "{artifacts:path}/greengrassv2_pub_sub_subscriber"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pub_sub_subscriber",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PubSubSubscriberCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to messages.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.pubsub:
        com.example.PubSubSubscriberCpp:pubsub:1:
          policyDescription: Allows access to subscribe to all topics.
          operations:
            - aws.greengrass#SubscribeToTopic
          resources:
            - "*"
Manifests:
  - Lifecycle:
      Run: "{artifacts:path}/greengrassv2_pub_sub_subscriber"
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pub_sub_subscriber
        Permission:
          Execute: OWNER
```

------

O exemplo de aplicação C\$1\$1 a seguir demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens em outros componentes.

```
#include <iostream>

#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>

using namespace Aws::Crt;
using namespace Aws::Greengrass;

class SubscribeResponseHandler : public SubscribeToTopicStreamHandler {
    public:
        virtual ~SubscribeResponseHandler() {}

    private:
        void OnStreamEvent(SubscriptionResponseMessage *response) override {
            auto jsonMessage = response->GetJsonMessage();
            if (jsonMessage.has_value() && jsonMessage.value().GetMessage().has_value()) {
                auto messageString = jsonMessage.value().GetMessage().value().View().WriteReadable();
                std::cout << "Received new message: " << messageString << std::endl;
            } else {
                auto binaryMessage = response->GetBinaryMessage();
                if (binaryMessage.has_value() && binaryMessage.value().GetMessage().has_value()) {
                    auto messageBytes = binaryMessage.value().GetMessage().value();
                    std::string messageString(messageBytes.begin(), messageBytes.end());
                    std::cout << "Received new message: " << messageString << std::endl;
                }
            }
        }

        bool OnStreamError(OperationError *error) override {
            std::cout << "Received an operation error: ";
            if (error->GetMessage().has_value()) {
                std::cout << error->GetMessage().value();
            }
            std::cout << std::endl;
            return false; // Return true to close stream, false to keep stream open.
        }

        void OnStreamClosed() override {
            std::cout << "Subscribe to topic stream closed." << std::endl;
        }
};

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() {
    String topic("test/topic/cpp");
    int timeout = 10;

    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);
    }

    SubscribeToTopicRequest request;
    request.SetTopic(topic);
    auto streamHandler = MakeShared<SubscribeResponseHandler>(DefaultAllocator());
    auto operation = ipcClient.NewSubscribeToTopic(streamHandler);
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (response) {
        std::cout << "Successfully subscribed to topic: " << topic << std::endl;
    } else {
        // An error occurred.
        std::cout << "Failed to subscribe 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);
    }

    // Keep the main thread alive, or the process will exit.
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(10));
    }

    operation->Close();
    return 0;
}
```

### publish/subscribe Editor de exemplo (Rust)
<a name="ipc-publish-subscribe-example-publisher-rust"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherRust",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherRust:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/publish_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubPublisherRust/1.0.0/publish_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo a seguir do aplicativo Rust demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let message = b"Hello, World";
    let topic = "my/topic";

    sdk.publish_to_topic_binary(topic, message)
        .expect("Failed to publish to topic");

    println!("Successfully published to topic: {topic}");
}
```

### Exemplo de publish/subscribe assinante (Rust)
<a name="ipc-publish-subscribe-example-subscriber-rust"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberRust",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberRust:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/subscribe_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberRust/1.0.0/subscribe_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo a seguir do aplicativo Rust demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens de outros componentes.

```
use gg_sdk::{Sdk, SubscribeToTopicPayload};
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let topic = "my/topic";

    let callback = |topic: &str, payload: SubscribeToTopicPayload| match payload
    {
        SubscribeToTopicPayload::Binary(message) => {
            let message = String::from_utf8_lossy(message);
            println!("Received new message on topic {topic}: {message}");
        }
        SubscribeToTopicPayload::Json(_) => {
            println!("Received new message on topic {topic}: (JSON message)");
        }
    };

    let _sub = sdk
        .subscribe_to_topic(topic, &callback)
        .expect("Failed to subscribe to topic");

    println!("Successfully subscribed to topic: {topic}");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

### Exemplo de publish/subscribe editor (C)
<a name="ipc-publish-subscribe-example-publisher-c"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherC",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherC:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_publish_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubPublisherC/1.0.0/sample_publish_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C a seguir demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer message = GG_STR("Hello, World");
    GgBuffer topic = GG_STR("my/topic");

    err = ggipc_publish_to_topic_binary(topic, message);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to publish to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully published to topic: %.*s\n", (int) topic.len, topic.data
    );
}
```

### Exemplo de publish/subscribe assinante (C)
<a name="ipc-publish-subscribe-example-subscriber-c"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberC",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberC:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_subscribe_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberC/1.0.0/sample_subscribe_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C a seguir demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens de outros componentes.

```
#include <assert.h>
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <gg/types.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx, GgBuffer topic, GgObject payload, GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    if (gg_obj_type(payload) == GG_TYPE_BUF) {
        GgBuffer message = gg_obj_into_buf(payload);
        printf(
            "Received new message on topic %.*s: %.*s\n",
            (int) topic.len,
            topic.data,
            (int) message.len,
            message.data
        );
    } else {
        assert(gg_obj_type(payload) == GG_TYPE_MAP);
        printf(
            "Received new message on topic %.*s: (JSON message)\n",
            (int) topic.len,
            topic.data
        );
    }
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer topic = GG_STR("my/topic");

    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_topic(
        topic, on_subscription_response, NULL, &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to subscribe to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully subscribed to topic: %.*s\n", (int) topic.len, topic.data
    );

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the stream.
    ggipc_close_subscription(handle);
}
```

### publish/subscribe Editor de exemplo (C\$1\$1, SDK de componentes)
<a name="ipc-publish-subscribe-example-publisher-cpp-component-sdk"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubPublisherCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubPublisherCpp:pubsub:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_cpp_publish_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubPublisherCpp/1.0.0/sample_cpp_publish_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicação C\$1\$1 a seguir demonstra como usar o serviço IPC de publicação/assinatura para publicar mensagens em outros componentes.

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view message = "Hello, World";
    std::string_view topic = "my/topic";

    error = client.publish_to_topic(topic, message);
    if (error) {
        std::cerr << "Failed to publish to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully published to topic: " << topic << "\n";
}
```

### Exemplo de publish/subscribe assinante (C\$1\$1, Component SDK)
<a name="ipc-publish-subscribe-example-subscriber-cpp-component-sdk"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PubSubSubscriberCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to messages.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.pubsub": {
          "com.example.PubSubSubscriberCpp:pubsub:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToTopic"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_cpp_subscribe_to_topic"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.PubSubSubscriberCpp/1.0.0/sample_cpp_subscribe_to_topic",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C\$1\$1 a seguir demonstra como usar o serviço IPC de publicação/assinatura para assinar mensagens de outros componentes.

```
#include <gg/ipc/client.hpp>
#include <gg/object.hpp>
#include <unistd.h>
#include <cassert>
#include <iostream>

class ResponseHandler : public gg::ipc::LocalTopicCallback {
    void operator()(
        std::string_view topic,
        gg::Object payload,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        if (payload.index() == GG_TYPE_BUF) {
            std::cout << "Received new message on topic " << topic << ": "
                      << get<gg::Buffer>(payload) << "\n";
        } else {
            assert(payload.index() == GG_TYPE_MAP);
            std::cout << "Received new message on topic " << topic
                      << ": (JSON message)\n";
        }
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view topic = "my/topic";

    static ResponseHandler handler;
    error = client.subscribe_to_topic(topic, handler);
    if (error) {
        std::cerr << "Failed to subscribe to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to topic: " << topic << "\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

# Publique/assine mensagens MQTT AWS IoT Core
<a name="ipc-iot-core-mqtt"></a>

O serviço IPC de mensagens AWS IoT Core MQTT permite que você envie e receba mensagens MQTT de e para. AWS IoT Core Os componentes podem publicar mensagens AWS IoT Core e assinar tópicos para atuar nas mensagens MQTT de outras fontes. Para obter mais informações sobre a AWS IoT Core implementação do MQTT, consulte [MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html) no Guia do *AWS IoT Core Desenvolvedor*.

**nota**  
Esse serviço IPC de mensagens MQTT permite que você troque mensagens com. AWS IoT Core Para obter mais informações sobre como trocar mensagens entre componentes, consulte [Publicar/assinar mensagens locais](ipc-publish-subscribe.md).

**Topics**
+ [Versões mínimas do SDK](#ipc-iot-core-mqtt-sdk-versions)
+ [Autorização](#ipc-iot-core-mqtt-authorization)
+ [PublishToIoTCore](#ipc-operation-publishtoiotcore)
+ [SubscribeToIoTCore](#ipc-operation-subscribetoiotcore)
+ [Exemplos](#ipc-iot-core-mqtt-examples)

## Versões mínimas do SDK
<a name="ipc-iot-core-mqtt-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para publicar e assinar mensagens MQTT de AWS IoT Core e para.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-iot-core-mqtt-authorization"></a>

Para usar mensagens AWS IoT Core MQTT em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente envie e receba mensagens sobre tópicos. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização para mensagens AWS IoT Core MQTT têm as seguintes propriedades.

**Identificador de serviço IPC:** `aws.greengrass.ipc.mqttproxy`


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#PublishToIoTCore`  |  Permite que um componente publique mensagens AWS IoT Core nos tópicos do MQTT que você especificar.  |  Uma sequência de tópicos, como `test/topic` ou `*` para permitir o acesso a todos os tópicos. Você pode usar curingas de tópico do MQTT (`#` e `+`) para combinar vários recursos.  | 
|  `aws.greengrass#SubscribeToIoTCore`  |  Permite que um componente assine mensagens dos AWS IoT Core tópicos que você especificar.  |  Uma sequência de tópicos, como `test/topic` ou `*` para permitir o acesso a todos os tópicos. Você pode usar curingas de tópico do MQTT (`#` e `+`) para combinar vários recursos.  | 
|  `*`  |  Permite que um componente publique e assine mensagens AWS IoT Core MQTT para os tópicos que você especificar.  |  Uma sequência de tópicos, como `test/topic` ou `*` para permitir o acesso a todos os tópicos. Você pode usar curingas de tópico do MQTT (`#` e `+`) para combinar vários recursos.  | 

### Caracteres curingas do MQTT nas políticas de autorização do AWS IoT Core MQTT
<a name="ipc-iot-core-mqtt-authorization-mqtt-wildcards"></a>

Você pode usar curingas do MQTT nas políticas de autorização do AWS IoT Core MQTT IPC. Os componentes podem publicar e assinar tópicos que correspondam ao filtro de tópicos permitido em uma política de autorização. 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/#`, e publicar e se inscrever no `test/topic/filter`.

### Variáveis de receita nas políticas de autorização do AWS IoT Core MQTT
<a name="ipc-iot-core-mqtt-authorization-recipe-variables"></a>

Se você usa a versão 2.6.0 ou posterior do [núcleo do Greengrass](greengrass-nucleus-component.md), pode 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 tópicos que contenham seu próprio nome. Por exemplo, você pode permitir que um componente acesse o seguinte recurso do tópico.

```
devices/{iot:thingName}/messages
```

Para obter mais informações, consulte [Variáveis da fórmula](component-recipe-reference.md#recipe-variables) e [Usar variáveis de fórmula em atualizações de mesclagem](update-component-configurations.md#merge-configuration-update-recipe-variables).

### Exemplos de política de autorização
<a name="ipc-iot-core-mqtt-authorization-policy-examples"></a>

Consulte os exemplos de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de política de autorização com acesso irrestrito**  
O exemplo de política de autorização a seguir permite que um componente publique e assine em todos os tópicos.  

```
{
  "accessControl": {
    "aws.greengrass.ipc.mqttproxy": {
      "com.example.MyIoTCorePubSubComponent:mqttproxy:1": {
        "policyDescription": "Allows access to publish/subscribe to all topics.",
        "operations": [
          "aws.greengrass#PublishToIoTCore",
          "aws.greengrass#SubscribeToIoTCore"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}
```

```
---
accessControl:
  aws.greengrass.ipc.mqttproxy:
    com.example.MyIoTCorePubSubComponent:mqttproxy:1:
      policyDescription: Allows access to publish/subscribe to all topics.
      operations:
        - aws.greengrass#PublishToIoTCore
        - aws.greengrass#SubscribeToIoTCore
      resources:
        - "*"
```

**Example Exemplo de política de autorização com acesso limitado**  
O exemplo de política de autorização a seguir permite que um componente publique e assine dois tópicos chamados `factory/1/events` e `factory/1/actions`.  

```
{
  "accessControl": {
    "aws.greengrass.ipc.mqttproxy": {
      "com.example.MyIoTCorePubSubComponent:mqttproxy:1": {
        "policyDescription": "Allows access to publish/subscribe to factory 1 topics.",
        "operations": [
          "aws.greengrass#PublishToIoTCore",
          "aws.greengrass#SubscribeToIoTCore"
        ],
        "resources": [
          "factory/1/actions",
          "factory/1/events"
        ]
      }
    }
  }
}
```

```
---
accessControl:
  aws.greengrass.ipc.mqttproxy:
    "com.example.MyIoTCorePubSubComponent:mqttproxy:1":
      policyDescription: Allows access to publish/subscribe to factory 1 topics.
      operations:
        - aws.greengrass#PublishToIoTCore
        - aws.greengrass#SubscribeToIoTCore
      resources:
        - factory/1/actions
        - factory/1/events
```

**Example Exemplo de política de autorização para um grupo de dispositivos principais**  
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](greengrass-nucleus-component.md). O núcleo do Greengrass v2.6.0 adiciona suporte para a maioria das [variáveis de fórmula](component-recipe-reference.md#recipe-variables), como `{iot:thingName}`, em configurações de componentes.
O exemplo de política de autorização a seguir permite que um componente publique e assine um tópico que contém o nome do dispositivo principal que executa o componente.  

```
{
  "accessControl": {
    "aws.greengrass.ipc.mqttproxy": {
      "com.example.MyIoTCorePubSubComponent:mqttproxy:1": {
        "policyDescription": "Allows access to publish/subscribe to all topics.",
        "operations": [
          "aws.greengrass#PublishToIoTCore",
          "aws.greengrass#SubscribeToIoTCore"
        ],
        "resources": [
          "factory/1/devices/{iot:thingName}/controls"
        ]
      }
    }
  }
}
```

```
---
accessControl:
  aws.greengrass.ipc.mqttproxy:
    "com.example.MyIoTCorePubSubComponent:mqttproxy:1":
      policyDescription: Allows access to publish/subscribe to all topics.
      operations:
        - aws.greengrass#PublishToIoTCore
        - aws.greengrass#SubscribeToIoTCore
      resources:
        - factory/1/devices/{iot:thingName}/controls
```

## PublishToIoTCore
<a name="ipc-operation-publishtoiotcore"></a>

Publica uma mensagem MQTT AWS IoT Core em um tópico.

Quando você publica mensagens MQTT no AWS IoT Core, há uma cota de 100 transações por segundo. Se você exceder essa cota, as mensagens serão enfileiradas para processamento no dispositivo Greengrass. Há também uma cota de 512 Kb de dados por segundo e uma cota de 20.000 publicações por segundo em toda a conta (2.000 em algumas). Regiões da AWS Para obter mais informações sobre limites de agentes de mensagens do MQTT no AWS IoT Core, consulte [Agente de mensagens e limites e cotas de protocolo do AWS IoT Core](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#message-broker-limits). 

Se você exceder essas cotas, o dispositivo Greengrass limita a publicação de mensagens a. AWS IoT Core As mensagens são armazenadas em um spooler na memória. Por padrão, a memória alocada para o spooler é de 2,5 Mb. Se o spooler ficar cheio, novas mensagens serão rejeitadas. Você pode aumentar o tamanho do spooler. Para obter mais informações, consulte a [Configuração](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration) documentação do [Greengrass nucleus](greengrass-nucleus-component.md). Para evitar preencher o spooler e precisar aumentar a memória alocada, limite as solicitações de publicação a no máximo 100 solicitações por segundo.

Quando sua aplicação precisar enviar mensagens em uma taxa maior ou maiores, considere usar o [Gerenciador de fluxos](stream-manager-component.md) para enviar mensagens para o Kinesis Data Streams. O componente gerenciador de fluxos foi projetado para transferir dados de alto volume para a Nuvem AWS. Para obter mais informações, consulte [Gerenciar fluxos de dados no nos dispositivos principais do Greengrass](manage-data-streams.md).

### Solicitação
<a name="ipc-operation-publishtoiotcore-request"></a>

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

`topicName` (Python: `topic_name`)  
O tópico no qual publicar a mensagem.

`qos`  <a name="ipc-iot-core-mqtt-qos"></a>
O QoS do MQTT a ser usado. Esse enumerador, `QOS`, tem os seguintes valores:  
+ `AT_MOST_ONCE`: QoS 0. A mensagem do MQTT é entregue no máximo uma vez.
+ `AT_LEAST_ONCE`: QoS 1. A mensagem do MQTT é entregue pelo menos uma vez.

`payload`  
(Opcional) A carga útil da mensagem como um blob.

Os recursos a seguir estão disponíveis para a versão 2.10.0 e versões posteriores do [Greengrass nucleus](greengrass-nucleus-component.md) ao usar o MQTT 5. Esses recursos são ignoradas quando você usa o MQTT 3.1.1. A tabela a seguir lista a versão mínima do SDK do AWS IoT dispositivo que você deve usar para acessar esses recursos.


| SDK | Versão mínima | 
| --- | --- | 
| [AWS IoT Device SDK for Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2) | v1.15.0 | 
| [AWS IoT Device SDK for Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2) | v1.13.0 | 
| [AWS IoT Device SDK for C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2) | v1.24.0 | 
| [AWS IoT Device SDK for JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  | v1.13.0 | 

`payloadFormat`  
(Opcional) O formato da carga útil da mensagem. Se você não definir o `payloadFormat`, presume-se que o tipo seja `BYTES`. O enumerador tem os seguintes valores:   
+ `BYTES`: o conteúdo da carga útil é um blob binário.
+ `UTF8`— O conteúdo da carga é uma UTF8 sequência de caracteres.

`retain`  
(Opcional) Indica se a opção de retenção do MQTT deve ser definida como `true` ao publicar.

`userProperties`  
(Opcional) Uma lista de `UserProperty` objetos específicos da aplicação a serem enviados. O objeto `UserProperty` é definido da seguinte maneira:  

```
UserProperty:
  key: string
  value: string
```

`messageExpiryIntervalSeconds`  
(Opcional) O número de segundos antes de a mensagem expirar e ser excluída pelo servidor. Se esse valor não for definido, a mensagem não expira.

`correlationData`  
(Opcional) Informações adicionadas à solicitação que podem ser usadas para associar uma solicitação a uma resposta.

`responseTopic`  
(Opcional) O tópico que deve ser usado para a mensagem de resposta.

`contentType`  
(Opcional) Um identificador específico da aplicação do tipo de conteúdo da mensagem.

### Resposta
<a name="ipc-operation-publishtoiotcore-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

### Exemplos
<a name="ipc-operation-publishtoiotcore-examples"></a>

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

------
#### [ Java (IPC client V2) ]

**Example Exemplo: publicar uma mensagem**  

```
package com.aws.greengrass.docs.samples.ipc;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClientV2;
import software.amazon.awssdk.aws.greengrass.model.PublishToIoTCoreRequest;
import software.amazon.awssdk.aws.greengrass.model.QOS;
import java.nio.charset.StandardCharsets;

public class PublishToIoTCore {

    public static void main(String[] args) {
        String topic = args[0];
        String message = args[1];
        QOS qos = QOS.get(args[2]);

        try (GreengrassCoreIPCClientV2 ipcClientV2 = GreengrassCoreIPCClientV2.builder().build()) {
            ipcClientV2.publishToIoTCore(new PublishToIoTCoreRequest()
                    .withTopicName(topic)
                    .withPayload(message.getBytes(StandardCharsets.UTF_8))
                    .withQos(qos));
            System.out.println("Successfully published to topic: " + topic);
        } catch (Exception e) {
            System.err.println("Exception occurred.");
            e.printStackTrace();
            System.exit(1);
        }
    }
}
```

------
#### [ Python (IPC client V2) ]

**Example Exemplo: publicar uma mensagem**  
Este exemplo pressupõe que você esteja usando a versão 1.5.4 ou posterior do for AWS IoT Device SDK Python v2. 

```
import awsiot.greengrasscoreipc.clientv2 as clientV2
                    
topic = 'my/topic'
qos = '1'
payload = 'Hello, World'

ipc_client = clientV2.GreengrassCoreIPCClientV2()
resp = ipc_client.publish_to_iot_core(topic_name=topic, qos=qos, payload=payload)
ipc_client.close()
```

------
#### [ Java (IPC client V1) ]

**Example Exemplo: publicar uma mensagem**  
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](interprocess-communication.md#ipc-service-connect).

```
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.PublishToIoTCoreResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.PublishToIoTCoreRequest;
import software.amazon.awssdk.aws.greengrass.model.PublishToIoTCoreResponse;
import software.amazon.awssdk.aws.greengrass.model.QOS;
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 PublishToIoTCore {

    public static final int TIMEOUT_SECONDS = 10;

    public static void main(String[] args) {
        String topic = args[0];
        String message = args[1];
        QOS qos = QOS.get(args[2]);
        try (EventStreamRPCConnection eventStreamRPCConnection =
                     IPCUtils.getEventStreamRpcConnection()) {
            GreengrassCoreIPCClient ipcClient =
                    new GreengrassCoreIPCClient(eventStreamRPCConnection);
            PublishToIoTCoreResponseHandler responseHandler =
                    PublishToIoTCore.publishBinaryMessageToTopic(ipcClient, topic, message, qos);
            CompletableFuture<PublishToIoTCoreResponse> futureResponse =
                    responseHandler.getResponse();
            try {
                futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
                System.out.println("Successfully published to topic: " + topic);
            } catch (TimeoutException e) {
                System.err.println("Timeout occurred while publishing to topic: " + topic);
            } catch (ExecutionException e) {
                if (e.getCause() instanceof UnauthorizedError) {
                    System.err.println("Unauthorized error while publishing to topic: " + topic);
                } 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 PublishToIoTCoreResponseHandler publishBinaryMessageToTopic(GreengrassCoreIPCClient greengrassCoreIPCClient, String topic, String message, QOS qos) {
        PublishToIoTCoreRequest publishToIoTCoreRequest = new PublishToIoTCoreRequest();
        publishToIoTCoreRequest.setTopicName(topic);
        publishToIoTCoreRequest.setPayload(message.getBytes(StandardCharsets.UTF_8));
        publishToIoTCoreRequest.setQos(qos);
        return greengrassCoreIPCClient.publishToIoTCore(publishToIoTCoreRequest, Optional.empty());
    }
}
```

------
#### [ Python (IPC client V1) ]

**Example Exemplo: publicar uma mensagem**  
Este exemplo pressupõe que você esteja usando a versão 1.5.4 ou posterior do for AWS IoT Device SDK Python v2. 

```
import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
    QOS,
    PublishToIoTCoreRequest
)

TIMEOUT = 10

ipc_client = awsiot.greengrasscoreipc.connect()
                    
topic = "my/topic"
message = "Hello, World"
qos = QOS.AT_LEAST_ONCE

request = PublishToIoTCoreRequest()
request.topic_name = topic
request.payload = bytes(message, "utf-8")
request.qos = qos
operation = ipc_client.new_publish_to_iot_core()
operation.activate(request)
future_response = operation.get_response()
future_response.result(TIMEOUT)
```

------
#### [ C\$1\$1 (IPC client V1) ]

**Example Exemplo: publicar uma mensagem**  

```
#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 {
        // Handle connection to IPC service.
    }

    void OnDisconnectCallback(RpcError error) override {
        // Handle disconnection from IPC service.
    }

    bool OnErrorCallback(RpcError error) override {
        // Handle IPC service connection error.
        return true;
    }
};

int main() {
    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);
    }

    String message("Hello, World!");
    String topic("my/topic");
    QOS qos = QOS_AT_MOST_ONCE;
    int timeout = 10;

    PublishToIoTCoreRequest request;
    Vector<uint8_t> messageData({message.begin(), message.end()});
    request.SetTopicName(topic);
    request.SetPayload(messageData);
    request.SetQos(qos);

    auto operation = ipcClient.NewPublishToIoTCore();
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (!response) {
        // Handle error.
        auto errorType = response.GetResultType();
        if (errorType == OPERATION_ERROR) {
            auto *error = response.GetOperationError();
            (void)error;
            // Handle operation error.
        } else {
            // Handle RPC error.
        }
    }

    return 0;
}
```

------
#### [ JavaScript ]

**Example Exemplo: publicar uma mensagem**  

```
    
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
import {QOS, PublishToIoTCoreRequest} from "aws-iot-device-sdk-v2/dist/greengrasscoreipc/model";
 
class PublishToIoTCore {
    private ipcClient: greengrasscoreipc.Client
    private readonly topic: string;
 
    constructor() {
        // define your own constructor, e.g.
        this.topic = "<define_your_topic>";
        this.publishToIoTCore().then(r => console.log("Started workflow"));
    }
 
    private async publishToIoTCore() {
        try {
            const request: PublishToIoTCoreRequest = {
                topicName: this.topic,
                qos: QOS.AT_LEAST_ONCE, // you can change this depending on your use case
            }
 
            this.ipcClient = await getIpcClient();
 
            await this.ipcClient.publishToIoTCore(request);
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
 
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
    }
}
 
// starting point
const publishToIoTCore = new PublishToIoTCore();
```

------
#### [ Rust ]

**Example Exemplo: publicar uma mensagem**  

```
use gg_sdk::{Qos, Sdk};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let message = b"Hello, World";
    let topic = "my/topic";
    let qos = Qos::AtLeastOnce;

    sdk.publish_to_iot_core(topic, message, qos)
        .expect("Failed to publish to topic");

    println!("Successfully published to topic: {topic}");
}
```

------
#### [ C ]

**Example Exemplo: publicar uma mensagem**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer message = GG_STR("Hello, World");
    GgBuffer topic = GG_STR("my/topic");
    uint8_t qos = 1;

    err = ggipc_publish_to_iot_core(topic, message, qos);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to publish to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully published to topic: %.*s\n", (int) topic.len, topic.data
    );
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: publicar uma mensagem**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view message = "Hello, World";
    std::string_view topic = "my/topic";
    uint8_t qos = 1;

    error = client.publish_to_iot_core(topic, message, qos);
    if (error) {
        std::cerr << "Failed to publish to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully published to topic: " << topic << "\n";
}
```

------

## SubscribeToIoTCore
<a name="ipc-operation-subscribetoiotcore"></a>

Assine as mensagens do MQTT a partir AWS IoT Core de um tópico ou filtro de tópicos. O software AWS IoT Greengrass principal remove as assinaturas quando o componente chega ao fim de seu ciclo de vida.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `IoTCoreMessage`

### Solicitação
<a name="ipc-operation-subscribetoiotcore-request"></a>

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

`topicName` (Python: `topic_name`)  
O tópico a ser assinado. Você pode usar curingas de tópicos do MQTT (`#` e `+`) para se inscrever em vários tópicos.

`qos`  <a name="ipc-iot-core-mqtt-qos"></a>
O QoS do MQTT a ser usado. Esse enumerador, `QOS`, tem os seguintes valores:  
+ `AT_MOST_ONCE`: QoS 0. A mensagem do MQTT é entregue no máximo uma vez.
+ `AT_LEAST_ONCE`: QoS 1. A mensagem do MQTT é entregue pelo menos uma vez.

### Resposta
<a name="ipc-operation-subscribetoiotcore-response"></a>

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

`messages`  
O fluxo de mensagens do MQTT. Esse objeto, `IoTCoreMessage`, contém as seguintes informações:    
`message`  
A mensagem do MQTT. Esse objeto, `MQTTMessage`, contém as seguintes informações:    
`topicName` (Python: `topic_name`)  
O tópico em que a mensagem foi publicada.  
`payload`  
(Opcional) A carga útil da mensagem como um blob.
Os recursos a seguir estão disponíveis para a versão 2.10.0 e versões posteriores do [Greengrass nucleus](greengrass-nucleus-component.md) ao usar o MQTT 5. Esses recursos são ignoradas quando você usa o MQTT 3.1.1. A tabela a seguir lista a versão mínima do SDK do AWS IoT dispositivo que você deve usar para acessar esses recursos.      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-iot-core-mqtt.html)  
`payloadFormat`  
(Opcional) O formato da carga útil da mensagem. Se você não definir o `payloadFormat`, presume-se que o tipo seja `BYTES`. O enumerador tem os seguintes valores:   
+ `BYTES`: o conteúdo da carga útil é um blob binário.
+ `UTF8`— O conteúdo da carga é uma UTF8 sequência de caracteres.  
`retain`  
(Opcional) Indica se a opção de retenção do MQTT deve ser definida como `true` ao publicar.  
`userProperties`  
(Opcional) Uma lista de `UserProperty` objetos específicos da aplicação a serem enviados. O objeto `UserProperty` é definido da seguinte maneira:  

```
UserProperty:
  key: string
  value: string
```  
`messageExpiryIntervalSeconds`  
(Opcional) O número de segundos antes de a mensagem expirar e ser excluída pelo servidor. Se esse valor não for definido, a mensagem não expira.  
`correlationData`  
(Opcional) Informações adicionadas à solicitação que podem ser usadas para associar uma solicitação a uma resposta.  
`responseTopic`  
(Opcional) O tópico que deve ser usado para a mensagem de resposta.  
`contentType`  
(Opcional) Um identificador específico da aplicação do tipo de conteúdo da mensagem.

### Exemplos
<a name="ipc-operation-subscribetoiotcore-examples"></a>

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

------
#### [ Java (IPC client V2) ]

**Example Exemplo: inscrever-se em mensagens**  

```
package com.aws.greengrass.docs.samples.ipc;

import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClientV2;
import software.amazon.awssdk.aws.greengrass.SubscribeToIoTCoreResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.QOS;
import software.amazon.awssdk.aws.greengrass.model.IoTCoreMessage;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToIoTCoreRequest;
import software.amazon.awssdk.aws.greengrass.model.SubscribeToIoTCoreResponse;

import java.nio.charset.StandardCharsets;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.Function;


public class SubscribeToIoTCore {

    public static void main(String[] args) {
        String topic = args[0];
        QOS qos = QOS.get(args[1]);

        Consumer<IoTCoreMessage> onStreamEvent = ioTCoreMessage ->
                System.out.printf("Received new message on topic %s: %s%n",
                        ioTCoreMessage.getMessage().getTopicName(),
                        new String(ioTCoreMessage.getMessage().getPayload(), StandardCharsets.UTF_8));

        Optional<Function<Throwable, Boolean>> onStreamError =
                Optional.of(e -> {
                    System.err.println("Received a stream error.");
                    e.printStackTrace();
                    return false;
                });

        Optional<Runnable> onStreamClosed = Optional.of(() ->
                System.out.println("Subscribe to IoT Core stream closed."));

        try (GreengrassCoreIPCClientV2 ipcClientV2 = GreengrassCoreIPCClientV2.builder().build()) {
            SubscribeToIoTCoreRequest request = new SubscribeToIoTCoreRequest()
                    .withTopicName(topic)
                    .withQos(qos);

            GreengrassCoreIPCClientV2.StreamingResponse<SubscribeToIoTCoreResponse, SubscribeToIoTCoreResponseHandler>
                    streamingResponse = ipcClientV2.subscribeToIoTCore(request, onStreamEvent, onStreamError, onStreamClosed);

            streamingResponse.getResponse();
            System.out.println("Successfully subscribed to topic: " + topic);

            // Keep the main thread alive, or the process will exit.
            while (true) {
                Thread.sleep(10000);
            }

            // To stop subscribing, close the stream.
            streamingResponse.getHandler().closeStream();
        } catch (InterruptedException e) {
            System.out.println("Subscribe interrupted.");
        } catch (Exception e) {
            System.err.println("Exception occurred.");
            e.printStackTrace();
            System.exit(1);
        }
    }
}
```

------
#### [ Python (IPC client V2) ]

**Example Exemplo: inscrever-se em mensagens**  
Este exemplo pressupõe que você esteja usando a versão 1.5.4 ou posterior do for AWS IoT Device SDK Python v2. 

```
import threading
import traceback

import awsiot.greengrasscoreipc.clientv2 as clientV2
                    
topic = 'my/topic'
qos = '1'

def on_stream_event(event):
    try:
        topic_name = event.message.topic_name
        message = str(event.message.payload, 'utf-8')
        print(f'Received new message on topic {topic_name}:  {message}')
    except:
        traceback.print_exc()

def on_stream_error(error):
    # Return True to close stream, False to keep stream open.
    return True  

def on_stream_closed():
    pass

ipc_client = clientV2.GreengrassCoreIPCClientV2()
resp, operation = ipc_client.subscribe_to_iot_core(
    topic_name=topic,
    qos=qos, 
    on_stream_event=on_stream_event,
    on_stream_error=on_stream_error,
    on_stream_closed=on_stream_closed
)

# Keep the main thread alive, or the process will exit.
event = threading.Event()
event.wait()

# To stop subscribing, close the operation stream.
operation.close()
ipc_client.close()
```

------
#### [ Java (IPC client V1) ]

**Example Exemplo: inscrever-se em mensagens**  
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](interprocess-communication.md#ipc-service-connect).

```
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.SubscribeToIoTCoreResponseHandler;
import software.amazon.awssdk.aws.greengrass.model.*;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import software.amazon.awssdk.eventstreamrpc.StreamResponseHandler;

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 SubscribeToIoTCore {

    public static final int TIMEOUT_SECONDS = 10;

    public static void main(String[] args) {
        String topic = args[0];
        QOS qos = QOS.get(args[1]);
        try (EventStreamRPCConnection eventStreamRPCConnection =
                     IPCUtils.getEventStreamRpcConnection()) {
            GreengrassCoreIPCClient ipcClient =
                    new GreengrassCoreIPCClient(eventStreamRPCConnection);
            StreamResponseHandler<IoTCoreMessage> streamResponseHandler =
                    new SubscriptionResponseHandler();
            SubscribeToIoTCoreResponseHandler responseHandler =
                    SubscribeToIoTCore.subscribeToIoTCore(ipcClient, topic, qos,
                            streamResponseHandler);
            CompletableFuture<SubscribeToIoTCoreResponse> futureResponse =
                    responseHandler.getResponse();
            try {
                futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
                System.out.println("Successfully subscribed to topic: " + topic);
            } catch (TimeoutException e) {
                System.err.println("Timeout occurred while subscribing to topic: " + topic);
            } catch (ExecutionException e) {
                if (e.getCause() instanceof UnauthorizedError) {
                    System.err.println("Unauthorized error while subscribing to topic: " + topic);
                } else {
                    throw e;
                }
            }

            // Keep the main thread alive, or the process will exit.
            try {
                while (true) {
                    Thread.sleep(10000);
                }
            } catch (InterruptedException e) {
                System.out.println("Subscribe interrupted.");
            }

            // To stop subscribing, close the stream.
            responseHandler.closeStream();
        } 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 SubscribeToIoTCoreResponseHandler subscribeToIoTCore(GreengrassCoreIPCClient greengrassCoreIPCClient, String topic, QOS qos, StreamResponseHandler<IoTCoreMessage> streamResponseHandler) {
        SubscribeToIoTCoreRequest subscribeToIoTCoreRequest = new SubscribeToIoTCoreRequest();
        subscribeToIoTCoreRequest.setTopicName(topic);
        subscribeToIoTCoreRequest.setQos(qos);
        return greengrassCoreIPCClient.subscribeToIoTCore(subscribeToIoTCoreRequest,
                Optional.of(streamResponseHandler));
    }

    public static class SubscriptionResponseHandler implements StreamResponseHandler<IoTCoreMessage> {

        @Override
        public void onStreamEvent(IoTCoreMessage ioTCoreMessage) {
            try {
                String topic = ioTCoreMessage.getMessage().getTopicName();
                String message = new String(ioTCoreMessage.getMessage().getPayload(),
                        StandardCharsets.UTF_8);
                System.out.printf("Received new message on topic %s: %s%n", topic, message);
            } catch (Exception e) {
                System.err.println("Exception occurred while processing subscription response " +
                        "message.");
                e.printStackTrace();
            }
        }

        @Override
        public boolean onStreamError(Throwable error) {
            System.err.println("Received a stream error.");
            error.printStackTrace();
            return false;
        }

        @Override
        public void onStreamClosed() {
            System.out.println("Subscribe to IoT Core stream closed.");
        }
    }
}
```

------
#### [ Python (IPC client V1) ]

**Example Exemplo: inscrever-se em mensagens**  
Este exemplo pressupõe que você esteja usando a versão 1.5.4 ou posterior do for AWS IoT Device SDK Python v2. 

```
import time
import traceback

import awsiot.greengrasscoreipc
import awsiot.greengrasscoreipc.client as client
from awsiot.greengrasscoreipc.model import (
    IoTCoreMessage,
    QOS,
    SubscribeToIoTCoreRequest
)

TIMEOUT = 10

ipc_client = awsiot.greengrasscoreipc.connect()

class StreamHandler(client.SubscribeToIoTCoreStreamHandler):
    def __init__(self):
        super().__init__()

    def on_stream_event(self, event: IoTCoreMessage) -> None:
        try:
            message = str(event.message.payload, "utf-8")
            topic_name = event.message.topic_name
            # Handle message.
        except:
            traceback.print_exc()

    def on_stream_error(self, error: Exception) -> bool:
        # Handle error.
        return True  # Return True to close stream, False to keep stream open.

    def on_stream_closed(self) -> None:
        # Handle close.
        pass


topic = "my/topic"
qos = QOS.AT_MOST_ONCE

request = SubscribeToIoTCoreRequest()
request.topic_name = topic
request.qos = qos
handler = StreamHandler()
operation = ipc_client.new_subscribe_to_iot_core(handler)
operation.activate(request)
future_response = operation.get_response() 
future_response.result(TIMEOUT)

# Keep the main thread alive, or the process will exit.
while True:
    time.sleep(10)
                  
# To stop subscribing, close the operation stream.
operation.close()
```

------
#### [ C\$1\$1 (IPC client V1) ]

**Example Exemplo: inscrever-se em mensagens**  

```
#include <iostream>

#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>

using namespace Aws::Crt;
using namespace Aws::Greengrass;

class IoTCoreResponseHandler : public SubscribeToIoTCoreStreamHandler {

    public:
        virtual ~IoTCoreResponseHandler() {}

    private:
        void OnStreamEvent(IoTCoreMessage *response) override {
            auto message = response->GetMessage();
            if (message.has_value() && message.value().GetPayload().has_value()) {
                auto messageBytes = message.value().GetPayload().value();
                std::string messageString(messageBytes.begin(), messageBytes.end());
                std::string topicName = message.value().GetTopicName().value().c_str();
                // Handle message.
            }
        }

        bool OnStreamError(OperationError *error) override {
            // Handle error.
            return false; // Return true to close stream, false to keep stream open.
        }

        void OnStreamClosed() override {
            // Handle close.
        }
};

class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
    void OnConnectCallback() override {
        // Handle connection to IPC service.
    }

    void OnDisconnectCallback(RpcError error) override {
        // Handle disconnection from IPC service.
    }

    bool OnErrorCallback(RpcError error) override {
        // Handle IPC service connection error.
        return true;
    }
};

int main() {
    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);
    }

    String topic("my/topic");
    QOS qos = QOS_AT_MOST_ONCE;
    int timeout = 10;

    SubscribeToIoTCoreRequest request;
    request.SetTopicName(topic);
    request.SetQos(qos);
    auto streamHandler = MakeShared<IoTCoreResponseHandler>(DefaultAllocator());
    auto operation = ipcClient.NewSubscribeToIoTCore(streamHandler);
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (!response) {
        // Handle error.
        auto errorType = response.GetResultType();
        if (errorType == OPERATION_ERROR) {
            auto *error = response.GetOperationError();
            (void)error;
            // Handle operation error.
        } else {
            // Handle RPC error.
        }
        exit(-1);
    }

    // Keep the main thread alive, or the process will exit.
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(10));
    }

    operation->Close();
    return 0;
}
```

------
#### [ JavaScript ]

**Example Exemplo: inscrever-se em mensagens**  

```
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
import {IoTCoreMessage, QOS, SubscribeToIoTCoreRequest} from "aws-iot-device-sdk-v2/dist/greengrasscoreipc/model";
import {RpcError} from "aws-iot-device-sdk-v2/dist/eventstream_rpc";
 
class SubscribeToIoTCore {
    private ipcClient: greengrasscoreipc.Client
    private readonly topic: string;
 
    constructor() {
        // define your own constructor, e.g.
        this.topic = "<define_your_topic>";
        this.subscribeToIoTCore().then(r => console.log("Started workflow"));
    }
 
    private async subscribeToIoTCore() {
        try {
            const request: SubscribeToIoTCoreRequest = {
                topicName: this.topic,
                qos: QOS.AT_LEAST_ONCE, // you can change this depending on your use case
            }
 
            this.ipcClient = await getIpcClient();
 
            const streamingOperation = this.ipcClient.subscribeToIoTCore(request);
 
            streamingOperation.on('message', (message: IoTCoreMessage) => {
                // parse the message depending on your use cases, e.g.
                if (message.message && message.message.payload) {
                    const receivedMessage = message.message.payload.toString();
                }
            });
 
            streamingOperation.on('streamError', (error : RpcError) => {
                // define your own error handling logic
            });
 
            streamingOperation.on('ended', () => {
                // define your own logic
            });
 
            await streamingOperation.activate();
 
            // Keep the main thread alive, or the process will exit.
            await new Promise((resolve) => setTimeout(resolve, 10000))
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
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
    }
}
 
// starting point
const subscribeToIoTCore = new SubscribeToIoTCore();
```

------
#### [ Rust ]

**Example Exemplo: inscrever-se em mensagens**  

```
use gg_sdk::{Qos, Sdk};
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let topic = "my/topic";
    let qos = Qos::AtLeastOnce;

    let callback = |topic: &str, payload: &[u8]| {
        let message = String::from_utf8_lossy(payload);
        println!("Received new message on topic {topic}: {message}");
    };

    let _sub = sdk
        .subscribe_to_iot_core(topic, qos, &callback)
        .expect("Failed to subscribe to topic");

    println!("Successfully subscribed to topic: {topic}");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

------
#### [ C ]

**Example Exemplo: inscrever-se em mensagens**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx, GgBuffer topic, GgBuffer payload, GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    printf(
        "Received new message on topic %.*s: %.*s\n",
        (int) topic.len,
        topic.data,
        (int) payload.len,
        payload.data
    );
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer topic = GG_STR("my/topic");
    uint8_t qos = 1;

    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_iot_core(
        topic, qos, on_subscription_response, NULL, &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to subscribe to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully subscribed to topic: %.*s\n", (int) topic.len, topic.data
    );

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the subscription handle.
    ggipc_close_subscription(handle);
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: inscrever-se em mensagens**  

```
#include <gg/ipc/client.hpp>
#include <unistd.h>
#include <iostream>

class ResponseHandler : public gg::ipc::IotTopicCallback {
    void operator()(
        std::string_view topic,
        gg::Buffer payload,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        std::cout << "Received new message on topic " << topic << ": "
                  << payload << "\n";
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view topic = "my/topic";
    uint8_t qos = 1;

    static ResponseHandler handler;
    error = client.subscribe_to_iot_core(topic, qos, handler);
    if (error) {
        std::cerr << "Failed to subscribe to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to topic: " << topic << "\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

------

## Exemplos
<a name="ipc-iot-core-mqtt-examples"></a>

Use os exemplos a seguir para aprender a usar o serviço AWS IoT Core MQTT IPC em seus componentes.

### Exemplo de editor AWS IoT Core MQTT (C\$1\$1, cliente IPC V1)
<a name="ipc-iot-core-mqtt-example-publisher-cpp"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCorePublisherCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes MQTT messages to IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCorePublisherCpp:mqttproxy:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": [
              "aws.greengrass#PublishToIoTCore"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "{artifacts:path}/greengrassv2_iotcore_publisher"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCorePublisherCpp/1.0.0/greengrassv2_iotcore_publisher",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IoTCorePublisherCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that publishes MQTT messages to IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.mqttproxy:
        com.example.IoTCorePublisherCpp:mqttproxy:1:
          policyDescription: Allows access to publish to all topics.
          operations:
            - aws.greengrass#PublishToIoTCore
          resources:
            - "*"
Manifests:
  - Lifecycle:
      Run: "{artifacts:path}/greengrassv2_iotcore_publisher"
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCorePublisherCpp/1.0.0/greengrassv2_iotcore_publisher
        Permission:
          Execute: OWNER
```

------

O exemplo de aplicativo C\$1\$1 a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para publicar mensagens no. AWS IoT Core

```
#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() {
    String message("Hello from the Greengrass IPC MQTT publisher (C++).");
    String topic("test/topic/cpp");
    QOS qos = QOS_AT_LEAST_ONCE;
    int timeout = 10;

    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);
    }

    while (true) {
        PublishToIoTCoreRequest request;
        Vector<uint8_t> messageData({message.begin(), message.end()});
        request.SetTopicName(topic);
        request.SetPayload(messageData);
        request.SetQos(qos);

        auto operation = ipcClient.NewPublishToIoTCore();
        auto activate = operation->Activate(request, nullptr);
        activate.wait();

        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);
        }

        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);
        }

        std::this_thread::sleep_for(std::chrono::seconds(5));
    }

    return 0;
}
```

### Exemplo de assinante AWS IoT Core MQTT (C\$1\$1, cliente IPC V1)
<a name="ipc-iot-core-mqtt-example-subscriber-cpp"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCoreSubscriberCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to MQTT messages from IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCoreSubscriberCpp:mqttproxy:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": [
              "aws.greengrass#SubscribeToIoTCore"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Lifecycle": {
        "Run": "{artifacts:path}/greengrassv2_iotcore_subscriber"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCoreSubscriberCpp/1.0.0/greengrassv2_iotcore_subscriber",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IoTCoreSubscriberCpp
ComponentVersion: 1.0.0
ComponentDescription: A component that subscribes to MQTT messages from IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    accessControl:
      aws.greengrass.ipc.mqttproxy:
        com.example.IoTCoreSubscriberCpp:mqttproxy:1:
          policyDescription: Allows access to subscribe to all topics.
          operations:
            - aws.greengrass#SubscribeToIoTCore
          resources:
            - "*"
Manifests:
  - Lifecycle:
      Run: "{artifacts:path}/greengrassv2_iotcore_subscriber"
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCoreSubscriberCpp/1.0.0/greengrassv2_iotcore_subscriber
        Permission:
          Execute: OWNER
```

------

O exemplo de aplicativo C\$1\$1 a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para assinar mensagens do. AWS IoT Core

```
#include <iostream>

#include <aws/crt/Api.h>
#include <aws/greengrass/GreengrassCoreIpcClient.h>

using namespace Aws::Crt;
using namespace Aws::Greengrass;

class IoTCoreResponseHandler : public SubscribeToIoTCoreStreamHandler {

    public:
        virtual ~IoTCoreResponseHandler() {}

    private:

        void OnStreamEvent(IoTCoreMessage *response) override {
            auto message = response->GetMessage();
            if (message.has_value() && message.value().GetPayload().has_value()) {
                auto messageBytes = message.value().GetPayload().value();
                std::string messageString(messageBytes.begin(), messageBytes.end());
                std::string messageTopic = message.value().GetTopicName().value().c_str();
                std::cout << "Received new message on topic: " << messageTopic << std::endl;
                std::cout << "Message: " << messageString << std::endl;
            }
        }

        bool OnStreamError(OperationError *error) override {
            std::cout << "Received an operation error: ";
            if (error->GetMessage().has_value()) {
                std::cout << error->GetMessage().value();
            }
            std::cout << std::endl;
            return false; // Return true to close stream, false to keep stream open.
        }

        void OnStreamClosed() override {
            std::cout << "Subscribe to IoT Core stream closed." << std::endl;
        }
};

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() {
    String topic("test/topic/cpp");
    QOS qos = QOS_AT_LEAST_ONCE;
    int timeout = 10;

    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);
    }

    SubscribeToIoTCoreRequest request;
    request.SetTopicName(topic);
    request.SetQos(qos);
    auto streamHandler = MakeShared<IoTCoreResponseHandler>(DefaultAllocator());
    auto operation = ipcClient.NewSubscribeToIoTCore(streamHandler);
    auto activate = operation->Activate(request, nullptr);
    activate.wait();

    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);
    }

    auto response = responseFuture.get();
    if (response) {
        std::cout << "Successfully subscribed to topic: " << topic << std::endl;
    } else {
        // An error occurred.
        std::cout << "Failed to subscribe 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);
    }

    // Keep the main thread alive, or the process will exit.
    while (true) {
        std::this_thread::sleep_for(std::chrono::seconds(10));
    }

    operation->Close();
    return 0;
}
```

### Exemplo de editor AWS IoT Core MQTT (Rust)
<a name="ipc-iot-core-mqtt-example-publisher-rust"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCorePublisherRust",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes MQTT messages to IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCorePublisherRust:mqttproxy:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/publish_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCorePublisherRust/1.0.0/publish_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo a seguir do aplicativo Rust demonstra como usar o serviço AWS IoT Core MQTT IPC para publicar mensagens no. AWS IoT Core

```
use gg_sdk::{Qos, Sdk};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let message = b"Hello, World";
    let topic = "my/topic";
    let qos = Qos::AtLeastOnce;

    sdk.publish_to_iot_core(topic, message, qos)
        .expect("Failed to publish to topic");

    println!("Successfully published to topic: {topic}");
}
```

### Exemplo de assinante AWS IoT Core MQTT (Rust)
<a name="ipc-iot-core-mqtt-example-subscriber-rust"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCoreSubscriberRust",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to MQTT messages from IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCoreSubscriberRust:mqttproxy:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/subscribe_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCoreSubscriberRust/1.0.0/subscribe_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo a seguir do aplicativo Rust demonstra como usar o serviço AWS IoT Core MQTT IPC para assinar mensagens do. AWS IoT Core

```
use gg_sdk::{Qos, Sdk};
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let topic = "my/topic";
    let qos = Qos::AtLeastOnce;

    let callback = |topic: &str, payload: &[u8]| {
        let message = String::from_utf8_lossy(payload);
        println!("Received new message on topic {topic}: {message}");
    };

    let _sub = sdk
        .subscribe_to_iot_core(topic, qos, &callback)
        .expect("Failed to subscribe to topic");

    println!("Successfully subscribed to topic: {topic}");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

### Exemplo de editor AWS IoT Core MQTT (C)
<a name="ipc-iot-core-mqtt-example-publisher-c"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCorePublisherC",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes MQTT messages to IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCorePublisherC:mqttproxy:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_publish_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCorePublisherC/1.0.0/sample_publish_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para publicar mensagens no. AWS IoT Core

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer message = GG_STR("Hello, World");
    GgBuffer topic = GG_STR("my/topic");
    uint8_t qos = 1;

    err = ggipc_publish_to_iot_core(topic, message, qos);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to publish to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully published to topic: %.*s\n", (int) topic.len, topic.data
    );
}
```

### Exemplo de assinante AWS IoT Core MQTT (C)
<a name="ipc-iot-core-mqtt-example-subscriber-c"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCoreSubscriberC",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to MQTT messages from IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCoreSubscriberC:mqttproxy:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_subscribe_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCoreSubscriberC/1.0.0/sample_subscribe_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para assinar mensagens do. AWS IoT Core

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx, GgBuffer topic, GgBuffer payload, GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    printf(
        "Received new message on topic %.*s: %.*s\n",
        (int) topic.len,
        topic.data,
        (int) payload.len,
        payload.data
    );
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer topic = GG_STR("my/topic");
    uint8_t qos = 1;

    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_iot_core(
        topic, qos, on_subscription_response, NULL, &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to subscribe to topic: %.*s\n",
            (int) topic.len,
            topic.data
        );
        exit(-1);
    }

    printf(
        "Successfully subscribed to topic: %.*s\n", (int) topic.len, topic.data
    );

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the subscription handle.
    ggipc_close_subscription(handle);
}
```

### Exemplo de editor AWS IoT Core MQTT (C\$1\$1, SDK de componentes)
<a name="ipc-iot-core-mqtt-example-publisher-cpp-component-sdk"></a>

O exemplo de receita a seguir permite que o componente seja publicado em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCorePublisherCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that publishes MQTT messages to IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCorePublisherCpp:mqttproxy:1": {
            "policyDescription": "Allows access to publish to all topics.",
            "operations": ["aws.greengrass#PublishToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_cpp_publish_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCorePublisherCpp/1.0.0/sample_cpp_publish_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C\$1\$1 a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para publicar mensagens no. AWS IoT Core

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view message = "Hello, World";
    std::string_view topic = "my/topic";
    uint8_t qos = 1;

    error = client.publish_to_iot_core(topic, message, qos);
    if (error) {
        std::cerr << "Failed to publish to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully published to topic: " << topic << "\n";
}
```

### Exemplo de assinante do AWS IoT Core MQTT (C\$1\$1, Component SDK)
<a name="ipc-iot-core-mqtt-example-subscriber-cpp-component-sdk"></a>

O exemplo de receita a seguir permite que o componente seja inscrito em todos os tópicos.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IoTCoreSubscriberCpp",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that subscribes to MQTT messages from IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.IoTCoreSubscriberCpp:mqttproxy:1": {
            "policyDescription": "Allows access to subscribe to all topics.",
            "operations": ["aws.greengrass#SubscribeToIoTCore"],
            "resources": ["*"]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "runtime": "*"
      },
      "Lifecycle": {
        "run": "{artifacts:path}/sample_cpp_subscribe_to_iot_core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.IoTCoreSubscriberCpp/1.0.0/sample_cpp_subscribe_to_iot_core",
          "Permission": {
            "Execute": "OWNER"
          }
        }
      ]
    }
  ]
}
```

O exemplo de aplicativo C\$1\$1 a seguir demonstra como usar o serviço AWS IoT Core MQTT IPC para assinar mensagens do. AWS IoT Core

```
#include <gg/ipc/client.hpp>
#include <unistd.h>
#include <iostream>

class ResponseHandler : public gg::ipc::IotTopicCallback {
    void operator()(
        std::string_view topic,
        gg::Buffer payload,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        std::cout << "Received new message on topic " << topic << ": "
                  << payload << "\n";
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view topic = "my/topic";
    uint8_t qos = 1;

    static ResponseHandler handler;
    error = client.subscribe_to_iot_core(topic, qos, handler);
    if (error) {
        std::cerr << "Failed to subscribe to topic: " << topic << "\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to topic: " << topic << "\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

# Interaja com o ciclo de vida dos componentes
<a name="ipc-component-lifecycle"></a>

Use o serviço IPC do ciclo de vida do componente para:
+ Atualize o estado do componente no dispositivo principal.
+ Assine as atualizações do estado do componente.
+ Evite que o núcleo interrompa o componente para aplicar uma atualização durante uma implantação.
+ Pausa e retomada dos processos dos componentes.

**Topics**
+ [Versões mínimas do SDK](#ipc-component-lifecycle-sdk-versions)
+ [Autorização](#ipc-component-lifecycle-authorization)
+ [UpdateState](#ipc-operation-updatestate)
+ [SubscribeToComponentUpdates](#ipc-operation-subscribetocomponentupdates)
+ [DeferComponentUpdate](#ipc-operation-defercomponentupdate)
+ [PauseComponent](#ipc-operation-pausecomponent)
+ [ResumeComponent](#ipc-operation-resumecomponent)

## Versões mínimas do SDK
<a name="ipc-component-lifecycle-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para interagir com o ciclo de vida do componente.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-component-lifecycle-authorization"></a>

Para pausar ou retomar outros componentes a partir de um componente personalizado, você deve definir políticas de autorização que permitam que seu componente gerencie outros componentes. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização para gerenciamento do ciclo de vida dos componentes têm as seguintes propriedades.

**Identificador de serviço IPC:** `aws.greengrass.ipc.lifecycle`


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#PauseComponent`  |  Permite que um componente pause os componentes que você especificar.  |  Um nome de componente ou `*` para permitir o acesso a todos os componentes.  | 
|  `aws.greengrass#ResumeComponent`  |  Permite que um componente retome os componentes que você especificar.  |  Um nome de componente ou `*` para permitir o acesso a todos os componentes.  | 
|  `*`  |  Permite que um componente pause e retome os componentes que você especificar.  |  Um nome de componente ou `*` para permitir o acesso a todos os componentes.  | 

### Exemplos de política de autorização
<a name="ipc-component-lifecycle-authorization-policy-examples"></a>

Consulte o exemplo de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de política de autorização**  
O exemplo de política de autorização a seguir permite que um componente pause e retome todos os componentes.  

```
{
  "accessControl": {
    "aws.greengrass.ipc.lifecycle": {
      "com.example.MyLocalLifecycleComponent:lifecycle:1": {
        "policyDescription": "Allows access to pause/resume all components.",
        "operations": [
          "aws.greengrass#PauseComponent",
          "aws.greengrass#ResumeComponent"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}
```

## UpdateState
<a name="ipc-operation-updatestate"></a>

Atualize o estado do componente no dispositivo principal.

### Solicitação
<a name="ipc-operation-updatestate-request"></a>

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

`state`  
O estado a ser definido. Esse enumerador, `LifecycleState`, tem os seguintes valores:  
+ `RUNNING`
+ `ERRORED`

### Resposta
<a name="ipc-operation-updatestate-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

### Exemplos
<a name="ipc-operation-updatestate-examples"></a>

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

------
#### [ Rust ]

**Example Exemplo: estado de atualização**  

```
use gg_sdk::{ComponentState, Sdk};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    // Update component state to RUNNING
    sdk.update_state(ComponentState::Running)
        .expect("Failed to update component state");

    println!("Successfully updated component state to RUNNING.");
}
```

------
#### [ C ]

**Example Exemplo: estado de atualização**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    // Update component state to RUNNING
    err = ggipc_update_state(GG_COMPONENT_STATE_RUNNING);
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to update component state.\n");
        exit(-1);
    }

    printf("Successfully updated component state to RUNNING.\n");
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: estado de atualização**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    // Update component state to RUNNING
    error = client.update_component_state(GG_COMPONENT_STATE_RUNNING);
    if (error) {
        std::cerr << "Failed to update component state.\n";
        exit(-1);
    }

    std::cout << "Successfully updated component state to RUNNING.\n";
}
```

------

## SubscribeToComponentUpdates
<a name="ipc-operation-subscribetocomponentupdates"></a>

Inscreva-se para receber notificações antes que o software AWS IoT Greengrass Core atualize um componente. A notificação especifica se o núcleo será reiniciado ou não como parte da atualização.

O núcleo envia notificações de atualização somente se a política de atualização de componentes da implantação especificar a notificação dos componentes. O comportamento padrão é notificar componentes. Para obter mais informações, consulte [Criar implantações](create-deployments.md) e o [DeploymentComponentUpdatePolicy](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_DeploymentComponentUpdatePolicy.html)objeto que você pode fornecer ao chamar a [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html)operação.

**Importante**  
As implantações locais não notificam os componentes antes das atualizações.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `ComponentUpdatePolicyEvents`

**dica**  
Você pode seguir um tutorial para aprender como desenvolver um componente que adia condicionalmente as atualizações de componentes. Para obter mais informações, consulte [Tutorial: Desenvolver um componente do Greengrass que adia as atualizações de componentes](defer-component-updates-tutorial.md).

### Solicitação
<a name="ipc-operation-subscribetocomponentupdates-request"></a>

A solicitação dessa operação não tem nenhum parâmetro.

### Resposta
<a name="ipc-operation-subscribetocomponentupdates-response"></a>

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

`messages`  
O fluxo de mensagens de notificação. Esse objeto, `ComponentUpdatePolicyEvents`, contém as seguintes informações:    
`preUpdateEvent` (Python: `pre_update_event`)  
(Opcional) Um evento que indica que o núcleo deseja atualizar um componente. Você pode responder com a [DeferComponentUpdate](#ipc-operation-defercomponentupdate) operação para confirmar ou adiar a atualização até que seu componente esteja pronto para ser reiniciado. Esse objeto, `PreComponentUpdateEvent`, contém as seguintes informações:    
`deploymentId` (Python: `deployment_id`)  
O ID da AWS IoT Greengrass implantação que atualiza o componente.  
`isGgcRestarting` (Python: `is_ggc_restarting`)  
Se o núcleo precisa ou não reiniciar para aplicar a atualização.  
`postUpdateEvent` (Python: `post_update_event`)  
(Opcional) Um evento que indica que o núcleo atualizou um componente. Esse objeto, `PostComponentUpdateEvent`, contém as seguintes informações:    
`deploymentId` (Python: `deployment_id`)  
O ID da AWS IoT Greengrass implantação que atualizou o componente.  
Esse recurso requer a versão 2.7.0 ou posterior do componente do Greengrass nucleus.

## DeferComponentUpdate
<a name="ipc-operation-defercomponentupdate"></a>

Reconheça ou adie uma atualização de componente que você descobriu com[SubscribeToComponentUpdates](#ipc-operation-subscribetocomponentupdates). Você especifica a quantidade de tempo de espera antes que o núcleo verifique novamente se seu componente está pronto para permitir que a atualização do componente continue. Você também pode usar essa operação para informar ao núcleo que seu componente está pronto para a atualização.

Se um componente não responder à notificação de atualização do componente, o núcleo aguardará a quantidade de tempo especificada na política de atualização de componentes da implantação. Após esse tempo limite, o núcleo prossegue com a implantação. O tempo limite padrão da atualização do componente é 60 segundos. Para obter mais informações, consulte [Criar implantações](create-deployments.md) e o [DeploymentComponentUpdatePolicy](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_DeploymentComponentUpdatePolicy.html)objeto que você pode fornecer ao chamar a [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html)operação.

**dica**  
Você pode seguir um tutorial para aprender como desenvolver um componente que adia condicionalmente as atualizações de componentes. Para obter mais informações, consulte [Tutorial: Desenvolver um componente do Greengrass que adia as atualizações de componentes](defer-component-updates-tutorial.md).

### Solicitação
<a name="ipc-operation-defercomponentupdate-request"></a>

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

`deploymentId` (Python: `deployment_id`)  
O ID da AWS IoT Greengrass implantação a ser adiada.

`message`  
(Opcional) O nome do componente para o qual adiar as atualizações.  
O padrão é o nome do componente que faz a solicitação.

`recheckAfterMs` (Python: `recheck_after_ms`)  
A quantidade de tempo em milissegundos para adiar a atualização. O núcleo espera por esse período de tempo e depois envia outro `PreComponentUpdateEvent` que você pode descobrir com. [SubscribeToComponentUpdates](#ipc-operation-subscribetocomponentupdates)  
Especifique `0` para confirmar a atualização. Isso informa ao núcleo que seu componente está pronto para a atualização.  
O padrão é zero milissegundos, o que significa confirmar a atualização.

### Resposta
<a name="ipc-operation-defercomponentupdate-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

## PauseComponent
<a name="ipc-operation-pausecomponent"></a>

Esse recurso está disponível para a versão 2.4.0 e posterior do componente de núcleo do [Greengrass](greengrass-nucleus-component.md). AWS IoT Greengrass atualmente não oferece suporte a esse recurso nos dispositivos principais do Windows. 

Pausa dos processos de um componente no dispositivo principal. Para retomar um componente, use a [ResumeComponent](#ipc-operation-resumecomponent)operação.

Você pode pausar somente componentes genéricos. Se você tentar pausar qualquer outro tipo de componente, essa operação lançará um. `InvalidRequestError`

**nota**  
Essa operação não pode pausar processos em contêineres, como contêineres Docker. [Para pausar e retomar um contêiner do Docker, você pode usar os comandos docker pause [e docker unpause](https://docs.docker.com/engine/reference/commandline/pause/).](https://docs.docker.com/engine/reference/commandline/unpause/)

Essa operação não pausa dependências de componentes ou componentes que dependem do componente que você pausa. Considere esse comportamento ao pausar um componente que é uma dependência de outro componente, pois o componente dependente pode encontrar problemas quando sua dependência é pausada.

Quando você reinicia ou desliga um componente pausado, como por meio de uma implantação, o núcleo do Greengrass retoma o componente e executa seu ciclo de vida de desligamento. Para obter mais informações sobre a reinicialização de um componente, consulte [RestartComponent](ipc-local-deployments-components.md#ipc-operation-restartcomponent).

**Importante**  
Para usar essa operação, você deve definir uma política de autorização que conceda permissão para usar essa operação. Para obter mais informações, consulte [Autorização](#ipc-component-lifecycle-authorization).

### Versões mínimas do SDK
<a name="ipc-operation-pausecomponent-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para pausar e retomar componentes.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.4.3  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.6.2  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.13.1  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

### Solicitação
<a name="ipc-operation-defercomponentupdate-request"></a>

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

`componentName` (Python: `component_name`)  
O nome do componente a ser pausa, que deve ser um componente genérico. Para obter mais informações, consulte [Tipos de componentes](develop-greengrass-components.md#component-types).

### Resposta
<a name="ipc-operation-defercomponentupdate-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

## ResumeComponent
<a name="ipc-operation-resumecomponent"></a>

Esse recurso está disponível para a versão 2.4.0 e posterior do componente de núcleo do [Greengrass](greengrass-nucleus-component.md). AWS IoT Greengrass atualmente não oferece suporte a esse recurso nos dispositivos principais do Windows. 

Retomada dos processos de um componente no dispositivo principal. Para pausar um componente, use a [PauseComponent](#ipc-operation-pausecomponent)operação.

Você pode retomar somente os componentes pausados. Se você tentar retomar um componente que não está pausado, essa operação gera um. `InvalidRequestError`

**Importante**  
Para usar essa operação, você deve definir uma política de autorização que conceda permissão para fazer isso. Para obter mais informações, consulte [Autorização](#ipc-component-lifecycle-authorization).

### Versões mínimas do SDK
<a name="ipc-operation-resumecomponent-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para pausar e retomar componentes.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.4.3  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.6.2  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.13.1  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

### Solicitação
<a name="ipc-operation-defercomponentupdate-request"></a>

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

`componentName` (Python: `component_name`)  
O nome do componente a ser retomado.

### Resposta
<a name="ipc-operation-defercomponentupdate-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

# Interagir com a configuração do componente
<a name="ipc-component-configuration"></a>

O serviço IPC de configuração do componente permite que você faça o seguinte:
+ Obtenha e defina os parâmetros de configuração do componente.
+ Inscreva-se para receber atualizações de configuração de componentes.
+ Valide as atualizações de configuração dos componentes antes que o núcleo as aplique.

**Topics**
+ [Versões mínimas do SDK](#ipc-component-configuration-sdk-versions)
+ [GetConfiguration](#ipc-operation-getconfiguration)
+ [UpdateConfiguration](#ipc-operation-updateconfiguration)
+ [SubscribeToConfigurationUpdate](#ipc-operation-subscribetoconfigurationupdate)
+ [SubscribeToValidateConfigurationUpdates](#ipc-operation-subscribetovalidateconfigurationupdates)
+ [SendConfigurationValidityReport](#ipc-operation-sendconfigurationvalidityreport)

## Versões mínimas do SDK
<a name="ipc-component-configuration-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para interagir com a configuração do componente.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## GetConfiguration
<a name="ipc-operation-getconfiguration"></a>

Obtém um valor de configuração para um componente no dispositivo principal. Você especifica o caminho da chave para o qual obter um valor de configuração.

### Solicitação
<a name="ipc-operation-getconfiguration-request"></a>

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

`componentName` (Python: `component_name`)  <a name="ipc-configuration-request-component-name"></a>
(Opcional) O nome do componente.  
O padrão é o nome do componente que faz a solicitação.

`keyPath` (Python: `key_path`)  
O caminho principal para o arquivo de configuração. Especifique uma lista em que cada entrada seja a chave para um único nível no objeto de configuração. Por exemplo, especifique `["mqtt", "port"]` para obter o valor de `port` na configuração a seguir.  

```
{
  "mqtt": {
    "port": 443
  }
}
```
Para obter a configuração completa do componente, especifique uma lista vazia.

### Resposta
<a name="ipc-operation-getconfiguration-response"></a>

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

`componentName` (Python: `component_name`)  <a name="ipc-configuration-response-component-name"></a>
O nome do componente.

`value`  
A configuração solicitada como um objeto.

### Exemplos
<a name="ipc-operation-getconfiguration-examples"></a>

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

------
#### [ Rust ]

**Example Exemplo: Obter configuração**  

```
use core::mem::MaybeUninit;
use gg_sdk::{Sdk, UnpackedObject};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    // Get a configuration value at key path ["mqtt", "port"]
    let mut buf = [MaybeUninit::uninit(); 1024];

    let value = sdk
        .get_config(&["mqtt", "port"], None, &mut buf)
        .expect("Failed to get configuration");

    if let UnpackedObject::I64(port) = value.unpack() {
        println!("Configuration value: {port}");
    }
}
```

------
#### [ C ]

**Example Exemplo: Obter configuração**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    // Get a configuration value at key path ["mqtt", "port"]
    uint8_t response_mem[1024];
    GgObject value;

    err = ggipc_get_config(
        GG_BUF_LIST(GG_STR("mqtt"), GG_STR("port")),
        NULL, // component_name (NULL = current component)
        GG_BUF(response_mem),
        &value
    );
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to get configuration.\n");
        exit(-1);
    }

    if (gg_obj_type(value) == GG_TYPE_I64) {
        printf("Configuration value: %" PRId64 "\n", gg_obj_into_i64(value));
    } else if (gg_obj_type(value) == GG_TYPE_BUF) {
        GgBuffer buf = gg_obj_into_buf(value);
        printf("Configuration value: %.*s\n", (int) buf.len, buf.data);
    } else {
        printf("Configuration value is of unexpected type.\n");
    }
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: Obter configuração**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    // Get a configuration value at key path ["mqtt", "port"]
    std::array key_path = { gg::Buffer { "mqtt" }, gg::Buffer { "port" } };
    int64_t value = 0;

    error = client.get_config(key_path, std::nullopt, value);
    if (error) {
        std::cerr << "Failed to get configuration.\n";
        exit(-1);
    }

    std::cout << "Configuration value: " << value << "\n";
}
```

------

## UpdateConfiguration
<a name="ipc-operation-updateconfiguration"></a>

Atualiza um valor de configuração para esse componente no dispositivo principal.

### Solicitação
<a name="ipc-operation-updateconfiguration-request"></a>

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

`keyPath` (Python: `key_path`)  
(Opcional) O caminho da chave para o nó do contêiner (o objeto) a ser atualizado. Especifique uma lista em que cada entrada seja a chave para um único nível no objeto de configuração. Por exemplo, especifique o caminho da chave `["mqtt"]` e o valor de mesclagem `{ "port": 443 }` para definir o valor `port` na configuração a seguir.  

```
{
  "mqtt": {
    "port": 443
  }
}
```
O caminho da chave deve especificar um nó de contêiner (um objeto) na configuração. Se o nó não existir na configuração do componente, essa operação o cria e define seu valor para o objeto em`valueToMerge`.  
O padrão é a raiz do objeto de configuração.

`timestamp`  
O tempo atual da época do Unix em milissegundos. Essa operação usa esse carimbo de data/hora para resolver atualizações simultâneas na chave. Se a chave na configuração do componente tiver um timestamp maior do que o timestamp na solicitação, a solicitação falhará.

`valueToMerge` (Python: `value_to_merge`)  
O objeto de configuração a ser mesclado no local especificado por você. `keyPath` Para obter mais informações, consulte [Atualizar configurações do componente](update-component-configurations.md).

### Resposta
<a name="ipc-operation-updateconfiguration-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

### Exemplos
<a name="ipc-operation-updateconfiguration-examples"></a>

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

------
#### [ Rust ]

**Example Exemplo: configuração de atualização**  

```
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    // Update configuration value at key path ["mqtt", "port"] to 443
    sdk.update_config(&["mqtt", "port"], None, 443)
        .expect("Failed to update configuration");

    println!("Successfully updated configuration.");
}
```

------
#### [ C ]

**Example Exemplo: configuração de atualização**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    // Update configuration value at key path ["mqtt", "port"] to 443
    err = ggipc_update_config(
        GG_BUF_LIST(GG_STR("mqtt"), GG_STR("port")),
        NULL, // timestamp (NULL = current time)
        gg_obj_i64(443)
    );
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to update configuration.\n");
        exit(-1);
    }

    printf("Successfully updated configuration.\n");
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: configuração de atualização**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    // Update configuration value at key path ["mqtt", "port"] to 443
    std::array key_path = { gg::Buffer { "mqtt" }, gg::Buffer { "port" } };

    error = client.update_config(key_path, 443);
    if (error) {
        std::cerr << "Failed to update configuration.\n";
        exit(-1);
    }

    std::cout << "Successfully updated configuration.\n";
}
```

------

## SubscribeToConfigurationUpdate
<a name="ipc-operation-subscribetoconfigurationupdate"></a>

Assina para receber notificações quando a configuração de um componente é atualizada. Ao assinar uma chave, você recebe uma notificação quando algum filho dessa chave é atualizado.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `ConfigurationUpdateEvents`

### Solicitação
<a name="ipc-operation-subscribetoconfigurationupdate-request"></a>

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

`componentName` (Python: `component_name`)  <a name="ipc-configuration-request-component-name"></a>
(Opcional) O nome do componente.  
O padrão é o nome do componente que faz a solicitação.

`keyPath` (Python: `key_path`)  
O caminho principal para o valor de configuração para o qual se inscrever. Especifique uma lista em que cada entrada seja a chave para um único nível no objeto de configuração. Por exemplo, especifique `["mqtt", "port"]` para obter o valor de `port` na configuração a seguir.  

```
{
  "mqtt": {
    "port": 443
  }
}
```
Para assinar as atualizações de todos os valores na configuração do componente, especifique uma lista vazia.

### Resposta
<a name="ipc-operation-subscribetoconfigurationupdate-response"></a>

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

`messages`  
O fluxo de mensagens de notificação. Esse objeto, `ConfigurationUpdateEvents`, contém as seguintes informações:    
`configurationUpdateEvent` (Python: `configuration_update_event`)  
O evento de atualização da configuração. Esse objeto, `ConfigurationUpdateEvent`, contém as seguintes informações:    
`componentName` (Python: `component_name`)  <a name="ipc-configuration-response-component-name"></a>
O nome do componente.  
`keyPath` (Python: `key_path`)  
O caminho principal para o valor de configuração que foi atualizado.

### Exemplos
<a name="ipc-operation-subscribetoconfigurationupdate-examples"></a>

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

------
#### [ Rust ]

**Example Exemplo: Inscrever-se para receber atualizações de configuração**  

```
use gg_sdk::Sdk;
use std::{thread, time::Duration};

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    // Subscribe to configuration updates for key path ["mqtt"]
    let callback = |component_name: &str, key_path: &[&str]| {
        println!(
            "Received configuration update for component: {component_name}"
        );
        println!("Key path: {key_path:?}");
    };

    let _sub = sdk
        .subscribe_to_configuration_update(None, &["mqtt"], &callback)
        .expect("Failed to subscribe to configuration updates");

    println!("Successfully subscribed to configuration updates.");

    // Keep the main thread alive, or the process will exit.
    loop {
        thread::sleep(Duration::from_secs(10));
    }
}
```

------
#### [ C ]

**Example Exemplo: Inscrever-se para receber atualizações de configuração**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/object.h>
#include <gg/sdk.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

static void on_subscription_response(
    void *ctx,
    GgBuffer component_name,
    GgList key_path,
    GgIpcSubscriptionHandle handle
) {
    (void) ctx;
    (void) handle;

    printf(
        "Received configuration update for component: %.*s\n",
        (int) component_name.len,
        component_name.data
    );

    printf("Key path: [");
    for (size_t i = 0; i < key_path.len; i++) {
        if (i > 0) {
            printf(", ");
        }
        GgObject *obj = &key_path.items[i];
        if (gg_obj_type(*obj) == GG_TYPE_BUF) {
            GgBuffer key = gg_obj_into_buf(*obj);
            printf("\"%.*s\"", (int) key.len, key.data);
        }
    }
    printf("]\n");
}

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    // Subscribe to configuration updates for key path ["mqtt"]
    GgIpcSubscriptionHandle handle;
    err = ggipc_subscribe_to_configuration_update(
        NULL, // component_name (NULL = current component)
        GG_BUF_LIST(GG_STR("mqtt")),
        on_subscription_response,
        NULL,
        &handle
    );
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to subscribe to configuration updates.\n");
        exit(-1);
    }

    printf("Successfully subscribed to configuration updates.\n");

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }

    // To stop subscribing, close the stream.
    ggipc_close_subscription(handle);
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: Inscrever-se para receber atualizações de configuração**  

```
#include <gg/ipc/client.hpp>
#include <unistd.h>
#include <iostream>

class ResponseHandler : public gg::ipc::ConfigurationUpdateCallback {
    void operator()(
        std::string_view component_name,
        gg::List key_path,
        gg::ipc::Subscription &handle
    ) override {
        (void) handle;
        std::cout << "Received configuration update for component: "
                  << component_name << "\n";
        std::cout << "Key path: [";
        for (size_t i = 0; i < key_path.size(); i++) {
            if (i > 0) {
                std::cout << ", ";
            }
            std::cout << "\"" << get<gg::Buffer>(key_path[i]) << "\"";
        }
        std::cout << "]\n";
    }
};

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    // Subscribe to configuration updates for key path ["mqtt"]
    std::array key_path = { gg::Buffer { "mqtt" } };

    static ResponseHandler handler;
    error = client.subscribe_to_configuration_update(
        key_path, std::nullopt, handler
    );
    if (error) {
        std::cerr << "Failed to subscribe to configuration updates.\n";
        exit(-1);
    }

    std::cout << "Successfully subscribed to configuration updates.\n";

    // Keep the main thread alive, or the process will exit.
    while (1) {
        sleep(10);
    }
}
```

------

## SubscribeToValidateConfigurationUpdates
<a name="ipc-operation-subscribetovalidateconfigurationupdates"></a>

Inscreva-se para receber notificações antes das atualizações de configuração desse componente. Isso permite que os componentes validem as atualizações de suas próprias configurações. Use a [SendConfigurationValidityReport](#ipc-operation-sendconfigurationvalidityreport) operação para dizer ao núcleo se a configuração é válida ou não.

**Importante**  
As implantações locais não notificam os componentes sobre atualizações.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `ValidateConfigurationUpdateEvents`

### Solicitação
<a name="ipc-operation-subscribetovalidateconfigurationupdates-request"></a>

A solicitação dessa operação não tem nenhum parâmetro.

### Resposta
<a name="ipc-operation-subscribetovalidateconfigurationupdates-response"></a>

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

`messages`  
O fluxo de mensagens de notificação. Esse objeto, `ValidateConfigurationUpdateEvents`, contém as seguintes informações:    
`validateConfigurationUpdateEvent` (Python: `validate_configuration_update_event`)  
O evento de atualização da configuração. Esse objeto, `ValidateConfigurationUpdateEvent`, contém as seguintes informações:    
`deploymentId` (Python: `deployment_id`)  
O ID da AWS IoT Greengrass implantação que atualiza o componente.  
`configuration`  
O objeto que contém a nova configuração.

## SendConfigurationValidityReport
<a name="ipc-operation-sendconfigurationvalidityreport"></a>

Diga ao núcleo se uma atualização de configuração desse componente é válida ou não. A implantação falhará se você informar ao núcleo que a nova configuração não é válida. Use a [SubscribeToValidateConfigurationUpdates](#ipc-operation-subscribetovalidateconfigurationupdates) operação para se inscrever para validar as atualizações de configuração.

Se um componente não responder a uma notificação de atualização de configuração de validação, o núcleo aguardará a quantidade de tempo especificada na política de validação de configuração da implantação. Após esse tempo limite, o núcleo prossegue com a implantação. O tempo limite padrão para validação de componentes é de 20 segundos. Para obter mais informações, consulte [Criar implantações](create-deployments.md) e o [DeploymentConfigurationValidationPolicy](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_DeploymentConfigurationValidationPolicy.html)objeto que você pode fornecer ao chamar a [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html)operação.

### Solicitação
<a name="ipc-operation-sendconfigurationvalidityreport-request"></a>

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

`configurationValidityReport` (Python: `configuration_validity_report`)  
O relatório que informa ao núcleo se a atualização da configuração é válida ou não. Esse objeto, `ConfigurationValidityReport`, contém as seguintes informações:    
`status`  
O status de validade. Esse enumerador, `ConfigurationValidityStatus`, tem os seguintes valores:  
+ `ACCEPTED`: a configuração é válida e o núcleo pode aplicá-la a esse componente.
+ `REJECTED`: a configuração não é válida e a implantação falha.  
`deploymentId` (Python: `deployment_id`)  
O ID da AWS IoT Greengrass implantação que solicitou a atualização da configuração.  
`message`  
(Opcional) Uma mensagem que informa por que a configuração não é válida.

### Resposta
<a name="ipc-operation-sendconfigurationvalidityreport-response"></a>

Essa operação não fornece nenhuma informação em sua resposta.

# Recuperar valores de segredos
<a name="ipc-secret-manager"></a>

Use o serviço IPC do gerenciador de segredos para recuperar valores secretos dos segredos no dispositivo principal. Você usa o [componente gerenciador de segredos](secret-manager-component.md) para implantar segredos criptografados nos dispositivos principais. Em seguida, você pode usar uma operação IPC para descriptografar o segredo e usar seu valor em seus componentes personalizados.

**Topics**
+ [Versões mínimas do SDK](#ipc-secret-manager-sdk-versions)
+ [Autorização](#ipc-secret-manager-authorization)
+ [GetSecretValue](#ipc-operation-getsecretvalue)
+ [Exemplos](#ipc-secret-manager-examples)

## Versões mínimas do SDK
<a name="ipc-secret-manager-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para recuperar valores secretos de segredos no dispositivo principal.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-secret-manager-authorization"></a>

Para usar o gerenciador de segredos em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente obtenha o valor dos segredos que você armazena no dispositivo principal. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização do gerenciador de segredo têm as seguintes propriedades.

**Identificador de serviço IPC:** `aws.greengrass.SecretManager`


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#GetSecretValue` ou `*`  |  Permite que um componente obtenha o valor dos segredos criptografados no dispositivo principal.  |  Um ARN secreto do Secrets Manager, ou `*` para permitir acesso a todos os segredos.  | 

### Exemplos de política de autorização
<a name="ipc-secret-manager-authorization-policy-examples"></a>

Consulte o exemplo de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de política de autorização**  
O exemplo de política de autorização a seguir permite que um componente obtenha o valor de qualquer segredo no dispositivo principal.  
Recomendamos que, em um ambiente de produção, você reduza o escopo da política de autorização para que o componente recupere somente os segredos que ele usa. Você pode alterar o `*` caractere curinga para uma lista de segredos ARNs ao implantar o componente.

```
{
  "accessControl": {
    "aws.greengrass.SecretManager": {
      "com.example.MySecretComponent:secrets:1": {
        "policyDescription": "Allows access to a secret.",
        "operations": [
          "aws.greengrass#GetSecretValue"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}
```

## GetSecretValue
<a name="ipc-operation-getsecretvalue"></a>

Obtém o valor de um segredo que você armazena no dispositivo principal.

Essa operação é semelhante à operação do Secrets Manager que você pode usar para obter o valor de um segredo na Nuvem AWS. Para obter mais informações, consulte [GetSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) na *Referência de APIs do AWS Secrets Manager *.

### Solicitação
<a name="ipc-operation-getsecretvalue-request"></a>

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

`refresh` (Python: `refresh`)  
(opcional): se o segredo solicitado deve ser sincronizado com o valor mais recente do AWS Secrets Manager serviço.  
Quando definido como verdadeiro, o gerenciador secreto solicitará AWS Secrets Manager ao serviço o valor mais recente do rótulo secreto especificado e retornará esse valor como resposta. Caso contrário, o valor secreto que foi armazenado localmente será retornado.  
 Esse parâmetro não funcionará em conjunto com o parâmetro `versionId` na solicitação. Esse parâmetro funciona quando usado em conjunto com o Nucleus 2.13.0 e versões posteriores.

`secretId` (Python: `secret_id`)  
O nome do segredo a ser obtido. É possível especificar o nome de recurso da Amazon (ARN) ou o nome amigável do segredo.

`versionId` (Python: `version_id`)  
(Opcional) O ID da versão do segredo a ser obtido.  
É possível especificar `versionId` ou `versionStage`.  
Se você não especificar `versionId` ou `versionStage`, essa operação usará como padrão a versão com o rótulo `AWSCURRENT`.

`versionStage` (Python: `version_stage`)  
(Opcional) O rótulo de preparação da versão a ser obtida.  
É possível especificar `versionId` ou `versionStage`.  
Se você não especificar `versionId` ou `versionStage`, essa operação usará como padrão a versão com o rótulo `AWSCURRENT`.

### Resposta
<a name="ipc-operation-getsecretvalue-response"></a>

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

`secretId` (Python: `secret_id`)  
O ID do segredo.

`versionId` (Python: `version_id`)  
O ID dessa versão do segredo.

`versionStage` (Python: `version_stage`)  
A lista de etiquetas de preparação anexadas a essa versão do segredo.

`secretValue` (Python: `secret_value`)  
O valor dessa versão do segredo. Esse objeto, `SecretValue`, contém as informações a seguir.    
`secretString` (Python: `secret_string`)  
A parte descriptografada das informações secretas protegidas que você forneceu ao Secrets Manager como uma string.  
`secretBinary` (Python: `secret_binary`)  
(Opcional) A parte descriptografada das informações secretas protegidas que você forneceu ao Secrets Manager como dados binários na forma de uma matriz de bytes. Essa propriedade contém os dados binários como uma string codificada em base64.  
Essa propriedade não será usada se você criou o segredo no console do Secrets Manager.

### Exemplos
<a name="ipc-operation-getsecretvalue-examples"></a>

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

------
#### [ Java (IPC client V1) ]

**Example Exemplo: Obter um valor de segredo**  
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](interprocess-communication.md#ipc-service-connect).

```
package com.aws.greengrass.docs.samples.ipc;

import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GetSecretValueResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueRequest;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueResponse;
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 GetSecretValue {

    public static final int TIMEOUT_SECONDS = 10;

    public static void main(String[] args) {
        String secretArn = args[0];
        String versionStage = args[1];
        try (EventStreamRPCConnection eventStreamRPCConnection =
                     IPCUtils.getEventStreamRpcConnection()) {
            GreengrassCoreIPCClient ipcClient =
                    new GreengrassCoreIPCClient(eventStreamRPCConnection);
            GetSecretValueResponseHandler responseHandler =
                    GetSecretValue.getSecretValue(ipcClient, secretArn, versionStage);
            CompletableFuture<GetSecretValueResponse> futureResponse =
                    responseHandler.getResponse();
            try {
                GetSecretValueResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
                response.getSecretValue().postFromJson();
                String secretString = response.getSecretValue().getSecretString();
                System.out.println("Successfully retrieved secret value: " + secretString);
            } catch (TimeoutException e) {
                System.err.println("Timeout occurred while retrieving secret: " + secretArn);
            } catch (ExecutionException e) {
                if (e.getCause() instanceof UnauthorizedError) {
                    System.err.println("Unauthorized error while retrieving secret: " + secretArn);
                } 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 GetSecretValueResponseHandler getSecretValue(GreengrassCoreIPCClient greengrassCoreIPCClient, String secretArn, String versionStage) {
        GetSecretValueRequest getSecretValueRequest = new GetSecretValueRequest();
        getSecretValueRequest.setSecretId(secretArn);
        getSecretValueRequest.setVersionStage(versionStage);
        return greengrassCoreIPCClient.getSecretValue(getSecretValueRequest, Optional.empty());
    }
}
```

------
#### [ Python (IPC client V1) ]

**Example Exemplo: Obter um valor de segredo**  
Este exemplo pressupõe que você esteja usando a versão 1.5.4 ou posterior do for AWS IoT Device SDK Python v2. 

```
import json

import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
    GetSecretValueRequest,
    GetSecretValueResponse,
    UnauthorizedError
)

secret_id = 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-abcdef'
TIMEOUT = 10

ipc_client = awsiot.greengrasscoreipc.connect()

request = GetSecretValueRequest()
request.secret_id = secret_id
request.version_stage = 'AWSCURRENT'
operation = ipc_client.new_get_secret_value()
operation.activate(request)
future_response = operation.get_response()
response = future_response.result(TIMEOUT)
secret_json = json.loads(response.secret_value.secret_string)
# Handle secret value.
```

------
#### [ JavaScript ]

**Example Exemplo: Obter um valor de segredo**  

```
import {
    GetSecretValueRequest,
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
 
class GetSecretValue {
    private readonly secretId : string;
    private readonly versionStage : string;
    private ipcClient : greengrasscoreipc.Client
 
    constructor() {
        this.secretId = "<define_your_own_secretId>"
        this.versionStage = "<define_your_own_versionStage>"
 
        this.getSecretValue().then(r => console.log("Started workflow"));
    }
 
    private async getSecretValue() {
        try {
            this.ipcClient = await getIpcClient();
 
            const getSecretValueRequest : GetSecretValueRequest = {
                secretId: this.secretId,
                versionStage: this.versionStage,
            };
 
            const result = await this.ipcClient.getSecretValue(getSecretValueRequest);
            const secretString = result.secretValue.secretString;
            console.log("Successfully retrieved secret value: " + secretString)
        } catch (e) {
            // parse the error depending on your use cases
            throw e
        }
    }
}
 
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 getSecretValue = new GetSecretValue();
```

------

## Exemplos
<a name="ipc-secret-manager-examples"></a>

Use os exemplos a seguir para aprender a usar o serviço IPC do gerenciador secreto em seus componentes.

### Exemplo: segredo de impressão (Python, cliente IPC V1)
<a name="ipc-secret-manager-example-print-secret-python"></a>

Esse componente de exemplo imprime o valor de um segredo que você implanta no dispositivo principal.

**Importante**  
Esse componente de exemplo imprime o valor de um segredo, portanto, use-o somente com segredos que armazenam dados de teste. Não use esse componente para imprimir o valor de um segredo que armazena informações importantes.

**Topics**
+ [Fórmula](#ipc-secret-manager-example-print-secret-python-recipe)
+ [Artefatos](#ipc-secret-manager-example-print-secret-python-artifacts)
+ [Usage](#ipc-secret-manager-example-print-secret-python-usage)

#### Fórmula
<a name="ipc-secret-manager-example-print-secret-python-recipe"></a>

O exemplo de fórmula a seguir define um parâmetro secreto de configuração do ARN e permite que o componente obtenha o valor de qualquer segredo no dispositivo principal.

**nota**  <a name="ipc-secret-manager-authorization-policy-resource-wildcard"></a>
Recomendamos que, em um ambiente de produção, você reduza o escopo da política de autorização para que o componente recupere somente os segredos que ele usa. Você pode alterar o `*` caractere curinga para uma lista de segredos ARNs ao implantar o componente.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PrintSecret",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "Prints the value of an AWS Secrets Manager secret.",
  "ComponentPublisher": "Amazon",
  "ComponentDependencies": {
    "aws.greengrass.SecretManager": {
      "VersionRequirement": "^2.0.0",
      "DependencyType": "HARD"
    }
  },
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "SecretArn": "",
      "accessControl": {
        "aws.greengrass.SecretManager": {
          "com.example.PrintSecret:secrets:1": {
            "policyDescription": "Allows access to a secret.",
            "operations": [
              "aws.greengrass#GetSecretValue"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "python3 -m pip install --user awsiotsdk",
        "Run": "python3 -u {artifacts:path}/print_secret.py \"{configuration:/SecretArn}\""
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "install": "py -3 -m pip install --user awsiotsdk",
        "Run": "py -3 -u {artifacts:path}/print_secret.py \"{configuration:/SecretArn}\""
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PrintSecret
ComponentVersion: 1.0.0
ComponentDescription: Prints the value of a Secrets Manager secret.
ComponentPublisher: Amazon
ComponentDependencies:
  aws.greengrass.SecretManager:
    VersionRequirement: "^2.0.0"
    DependencyType: HARD
ComponentConfiguration:
  DefaultConfiguration:
    SecretArn: ''
    accessControl:
      aws.greengrass.SecretManager:
        com.example.PrintSecret:secrets:1:
          policyDescription: Allows access to a secret.
          operations:
            - aws.greengrass#GetSecretValue
          resources:
            - "*"
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install: python3 -m pip install --user awsiotsdk
      Run: python3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
  - Platform:
      os: windows
    Lifecycle:
      install: py -3 -m pip install --user awsiotsdk
      Run: py -3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
```

------

#### Artefatos
<a name="ipc-secret-manager-example-print-secret-python-artifacts"></a>

O exemplo de aplicação Python a seguir demonstra como usar o serviço IPC do gerenciador de segredos para obter o valor de um segredo no dispositivo principal.

```
import concurrent.futures
import json
import sys
import traceback

import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
    GetSecretValueRequest,
    GetSecretValueResponse,
    UnauthorizedError
)

TIMEOUT = 10

if len(sys.argv) == 1:
    print('Provide SecretArn in the component configuration.', file=sys.stdout)
    exit(1)

secret_id = sys.argv[1]

try:
    ipc_client = awsiot.greengrasscoreipc.connect()

    request = GetSecretValueRequest()
    request.secret_id = secret_id
    operation = ipc_client.new_get_secret_value()
    operation.activate(request)
    future_response = operation.get_response()

    try:
        response = future_response.result(TIMEOUT)
        secret_json = json.loads(response.secret_value.secret_string)
        print('Successfully got secret: ' + secret_id)
        print('Secret value: ' + str(secret_json))
    except concurrent.futures.TimeoutError:
        print('Timeout occurred while getting secret: ' + secret_id, file=sys.stderr)
    except UnauthorizedError as e:
        print('Unauthorized error while getting secret: ' + secret_id, file=sys.stderr)
        raise e
    except Exception as e:
        print('Exception while getting secret: ' + secret_id, file=sys.stderr)
        raise e
except Exception:
    print('Exception occurred when using IPC.', file=sys.stderr)
    traceback.print_exc()
    exit(1)
```

#### Usage
<a name="ipc-secret-manager-example-print-secret-python-usage"></a>

Você pode usar esse componente de exemplo com o [componente gerenciador de segredos](secret-manager-component.md) para implantar e imprimir o valor de um segredo em seu dispositivo principal.

**Para criar, implantar e imprimir um segredo de teste**

1. Criar um segredo do Secrets Manager com dados de teste.

------
#### [ Linux or Unix ]

   ```
   aws secretsmanager create-secret \
     --name MyTestGreengrassSecret \
     --secret-string '{"my-secret-key": "my-secret-value"}'
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   aws secretsmanager create-secret ^
     --name MyTestGreengrassSecret ^
     --secret-string '{"my-secret-key": "my-secret-value"}'
   ```

------
#### [ PowerShell ]

   ```
   aws secretsmanager create-secret `
     --name MyTestGreengrassSecret `
     --secret-string '{"my-secret-key": "my-secret-value"}'
   ```

------

   Salve o ARN do segredo para usar nas próximas etapas

   Para obter mais informações, consulte [Criar um segredo](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) no *Guia do usuário do AWS Secrets Manager *.

1. Implante o [componente do gerenciador secreto](secret-manager-component.md) (`aws.greengrass.SecretManager`) com a seguinte atualização de mesclagem de configuração. Especifique o ARN do segredo criado anteriormente.

   ```
   {
     "cloudSecrets": [
       {
         "arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef"
       }
     ]
   }
   ```

   Para obter mais informações, consulte [Implemente AWS IoT Greengrass componentes em dispositivos](manage-deployments.md) ou o comando de implantação da [CLI do Greengrass](gg-cli-deployment.md).

1. Crie e implante o componente de exemplo nesta seção com a seguinte atualização de mesclagem de configuração. Especifique o ARN do segredo criado anteriormente.

   ```
   {
     "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret",
     "accessControl": {
       "aws.greengrass.SecretManager": {
         "com.example.PrintSecret:secrets:1": {
           "policyDescription": "Allows access to a secret.",
           "operations": [
             "aws.greengrass#GetSecretValue"
           ],
           "resources": [
             "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef"
           ]
         }
       }
     }
   }
   ```

   Para obter mais informações, consulte [Criar componentes do AWS IoT Greengrass](create-components.md).

1. Visualize os registros do software AWS IoT Greengrass principal para verificar se as implantações foram bem-sucedidas e veja o registro do `com.example.PrintSecret` componente para ver o valor secreto impresso. Para obter mais informações, consulte [Monitore AWS IoT Greengrass logs](monitor-logs.md).

# Interagir com sombras locais
<a name="ipc-local-shadows"></a>

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](shadow-manager-component.md) 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 publish/subscribe IPC para assinar eventos de sombra. Para obter mais informações sobre como usar o publish/subscribe serviço, consulte [Publicar/assinar mensagens locais](ipc-publish-subscribe.md) o.

**nota**  <a name="note-requirement-enable-shadow-manager-client-devices"></a>
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](work-with-client-device-shadows.md).

**Topics**
+ [Versões mínimas do SDK](#ipc-local-shadows-sdk-versions)
+ [Autorização](#ipc-local-shadow-authorization)
+ [GetThingShadow](#ipc-operation-getthingshadow)
+ [UpdateThingShadow](#ipc-operation-updatethingshadow)
+ [DeleteThingShadow](#ipc-operation-deletethingshadow)
+ [ListNamedShadowsForThing](#ipc-operation-listnamedshadowsforthing)

## Versões mínimas do SDK
<a name="ipc-local-shadows-sdk-versions"></a>

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 | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.4.0  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.6.0  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-local-shadow-authorization"></a>

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](interprocess-communication.md#ipc-authorization-policies).

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 | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#GetThingShadow`  |  Permite que um componente recupere a sombra de um objeto.  |  Uma das seguintes strings:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-local-shadows.html)  | 
|  `aws.greengrass#UpdateThingShadow`  |  Permite que um componente atualize a sombra de um objeto.  |  Uma das seguintes strings:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-local-shadows.html)  | 
|  `aws.greengrass#DeleteThingShadow`  |  Permite que um componente exclua a sombra de um objeto.  |  Uma das seguintes strings:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-local-shadows.html)  | 
|  `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 | Description | 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: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-local-shadows.html) O valor do prefixo do tópico `shadowTopicPrefix` depende do tipo de sombra:  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/greengrass/v2/developerguide/ipc-local-shadows.html) Use `*` para permitir o acesso a todos os tópicos. <a name="ipc-local-publish-subscribe-authorization-mqtt-wildcards"></a>No [núcleo do Greengrass](greengrass-nucleus-component.md) 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
<a name="ipc-local-shadow-authorization-recipe-variables"></a>

[Se você usar a versão 2.6.0 ou posterior do núcleo do [Greengrass e definir a opção de [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)configuração do núcleo](greengrass-nucleus-component.md) do Greengrass como`true`, poderá usar a variável de receita nas políticas de autorização. `{iot:thingName}`](component-recipe-reference.md#recipe-variables) 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
<a name="ipc-local-shadow-authorization-policy-examples"></a>

Consulte os exemplos de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo: permitir que um grupo de dispositivos principais interaja com sombras locais**  
 <a name="phrase-example-uses-recipe-variables-in-configuration"></a>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](greengrass-nucleus-component.md). O núcleo do Greengrass v2.6.0 adiciona suporte para a maioria das [variáveis de fórmula](component-recipe-reference.md#recipe-variables), como `{iot:thingName}`, em configurações de componentes. Para habilitar esse recurso, defina a opção de [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)configuraçã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](#ipc-local-shadows-authorization-example-single-device).
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"
        ]
      }
    }
  }
}
```

```
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
```

**Example Exempo: permitir que um grupo de dispositivos principais interaja com sombras do dispositivo locais.**  
Esse recurso requer o [núcleo do Greengrass](greengrass-nucleus-component.md) v2.6.0 ou posterior, o [gerenciador de sombras](shadow-manager-component.md) v2.2.0 ou posterior e a [ponte MQTT](mqtt-bridge-component.md) 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](work-with-client-device-shadows.md#enable-shadow-manager-client-devices).
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`.  
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](work-with-client-device-shadows.md).

```
{
  "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*"
        ]
      }    
    }
  }
}
```

```
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*
```<a name="ipc-local-shadows-authorization-example-single-device"></a>

**Example 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"
        ]
      }
    }
  }
}
```

```
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
```<a name="interact-with-shadows-react-example-authorization-policies"></a>

**Example Exemplo: permitir que um grupo de dispositivos principais reaja às mudanças locais do estado de sombra**  
 <a name="phrase-example-uses-recipe-variables-in-configuration"></a>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](greengrass-nucleus-component.md). O núcleo do Greengrass v2.6.0 adiciona suporte para a maioria das [variáveis de fórmula](component-recipe-reference.md#recipe-variables), como `{iot:thingName}`, em configurações de componentes. Para habilitar esse recurso, defina a opção de [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)configuraçã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](#interact-with-shadows-react-example-authorization-policy-single-device).
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"
        ]
      }
    }
  }
}
```

```
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
```<a name="interact-with-shadows-react-example-authorization-policy-single-device"></a>

**Example 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"
        ]
      }
    }
  }
}
```

```
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
<a name="ipc-operation-getthingshadow"></a>

Obtém a sombra do objeto especificado.

### Solicitação
<a name="ipc-operation-getthingshadow-request"></a>

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

`thingName` (Python: `thing_name`)  <a name="ipc-local-shadows-thing-name"></a>
O nome da coisa.  
Tipo: `string`

`shadowName` (Python: `shadow_name`)  <a name="ipc-local-shadows-shadow-name"></a>
O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia (`""`).  
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 name="ipc-operation-getthingshadow-response"></a>

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
<a name="ipc-operation-getthingshadow-errors"></a>

Essa operação não pode retornar os erros a seguir.

`InvalidArgumentsError`  <a name="ipc-invalidargumentserror"></a>
<a name="ipc-invalidargumentserror-para"></a>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`  <a name="ipc-resourcenotfounderror"></a>
Não foi possível encontrar o documento paralelo local.

`ServiceError`  <a name="ipc-serviceerror"></a>
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 name="ipc-unauthorizederror"></a>
A política de autorização do componente não inclui as permissões necessárias para essa operação.

### Exemplos
<a name="ipc-operation-getthingshadow-examples"></a>

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

------
#### [ Java (IPC client V1) ]

**Example Exemplo: obter uma sombra de coisa**  
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](interprocess-communication.md#ipc-service-connect).

```
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) ]

**Example 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 ]

**Example 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
<a name="ipc-operation-updatethingshadow"></a>

Atualiza a sombra da coisa especificada. Se a sombra não existir, ela será criada.

### Solicitação
<a name="ipc-operation-updatethingshadow-request"></a>

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

`thingName` (Python: `thing_name`)  <a name="ipc-local-shadows-thing-name"></a>
O nome da coisa.  
Tipo: `string`

`shadowName` (Python: `shadow_name`)  <a name="ipc-local-shadows-shadow-name"></a>
O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia (`""`).  
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` 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 name="ipc-operation-updatethingshadow-response"></a>

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
<a name="ipc-operation-updatethingshadow-errors"></a>

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`  
<a name="ipc-invalidargumentserror-para"></a>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`  <a name="ipc-serviceerror"></a>
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 name="ipc-unauthorizederror"></a>
A política de autorização do componente não inclui as permissões necessárias para essa operação.

### Exemplos
<a name="ipc-operation-updatethingshadow-examples"></a>

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

------
#### [ Java (IPC client V1) ]

**Example Exemplo: atualizar a sombra de um objeto.**  
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](interprocess-communication.md#ipc-service-connect).

```
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) ]

**Example 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 ]

**Example 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
<a name="ipc-operation-deletethingshadow"></a>

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 name="ipc-operation-deletethingshadow-request"></a>

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

`thingName` (Python: `thing_name`)  <a name="ipc-local-shadows-thing-name"></a>
O nome da coisa.  
Tipo: `string`

`shadowName` (Python: `shadow_name`)  <a name="ipc-local-shadows-shadow-name"></a>
O nome do shadow. Para especificar a sombra clássica da coisa, defina esse parâmetro como uma string vazia (`""`).  
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 name="ipc-operation-deletethingshadow-response"></a>

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

`payload`  
Um documento de estado de resposta vazio.

### Erros
<a name="ipc-operation-deletethingshadow-errors"></a>

Essa operação não pode retornar os erros a seguir.

`InvalidArgumentsError`  <a name="ipc-invalidargumentserror"></a>
<a name="ipc-invalidargumentserror-para"></a>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`  <a name="ipc-resourcenotfounderror"></a>
Não foi possível encontrar o documento paralelo local.

`ServiceError`  <a name="ipc-serviceerror"></a>
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 name="ipc-unauthorizederror"></a>
A política de autorização do componente não inclui as permissões necessárias para essa operação.

### Exemplos
<a name="ipc-operation-deletethingshadow-examples"></a>

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

------
#### [ Java (IPC client V1) ]

**Example Exemplo: excluir a sombra de um objeto.**  
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](interprocess-communication.md#ipc-service-connect).

```
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) ]

**Example 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 ]

**Example 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
<a name="ipc-operation-listnamedshadowsforthing"></a>

Liste as sombras com nome para a coisa especificada.

### Solicitação
<a name="ipc-operation-listnamedshadowsforthing-request"></a>

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

`thingName` (Python: `thing_name`)  <a name="ipc-local-shadows-thing-name"></a>
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 name="ipc-operation-listnamedshadowsforthing-response"></a>

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
<a name="ipc-operation-listnamedshadowsforthing-errors"></a>

Essa operação não pode retornar os erros a seguir.

`InvalidArgumentsError`  <a name="ipc-invalidargumentserror"></a>
<a name="ipc-invalidargumentserror-para"></a>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`  <a name="ipc-resourcenotfounderror"></a>
Não foi possível encontrar o documento paralelo local.

`ServiceError`  <a name="ipc-serviceerror"></a>
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 name="ipc-unauthorizederror"></a>
A política de autorização do componente não inclui as permissões necessárias para essa operação.

### Exemplos
<a name="ipc-operation-listnamedshadowsforthing-examples"></a>

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

------
#### [ Java (IPC client V1) ]

**Example Exemplo: listar sombras de uma coisa nomeada**  
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](interprocess-communication.md#ipc-service-connect).

```
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) ]

**Example 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 ]

**Example 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();
```

------

# Gerenciar implantações e componentes locais
<a name="ipc-local-deployments-components"></a>

**nota**  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md).

Use o serviço Greengrass CLI IPC para gerenciar implantações locais e componentes do Greengrass no dispositivo principal.

Para usar essas operações de IPC, inclua a versão 2.6.0 ou posterior do componente [Greengrass CLI](greengrass-cli-component.md) como uma dependência em seu componente personalizado. Em seguida, você pode usar as operações de IPC em seus componentes personalizados para fazer o seguinte:
+ Crie implantações locais para modificar e configurar os componentes do Greengrass no dispositivo principal.
+ Reinicie e interrompa os componentes do Greengrass no dispositivo principal.
+ Gere uma senha que você possa usar para entrar no [console de depuração local](local-debug-console-component.md).

**Topics**
+ [Versões mínimas do SDK](#ipc-local-deployments-components-sdk-versions)
+ [Autorização](#ipc-local-deployments-components-authorization)
+ [CreateLocalDeployment](#ipc-operation-createlocaldeployment)
+ [ListLocalDeployments](#ipc-operation-listlocaldeployments)
+ [GetLocalDeploymentStatus](#ipc-operation-getlocaldeploymentstatus)
+ [ListComponents](#ipc-operation-listcomponents)
+ [GetComponentDetails](#ipc-operation-getcomponentdetails)
+ [RestartComponent](#ipc-operation-restartcomponent)
+ [StopComponent](#ipc-operation-stopcomponent)
+ [CreateDebugPassword](#ipc-operation-createdebugpassword)

## Versões mínimas do SDK
<a name="ipc-local-deployments-components-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para interagir com o serviço Greengrass CLI IPC.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.2.10  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.5.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.17.0  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-local-deployments-components-authorization"></a>

Para usar o serviço Greengrass CLI IPC em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente gerencie implantações e componentes locais. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização da CLI do Greengrass têm as seguintes propriedades.

**Identificador de serviço IPC:** `aws.greengrass.Cli`


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#CreateLocalDeployment`  |  Permite que um componente crie uma implantação local no dispositivo principal.  |  `*`  | 
|  `aws.greengrass#ListLocalDeployments`  |  Permite que um componente liste implantações locais no dispositivo principal.  |  `*`  | 
|  `aws.greengrass#GetLocalDeploymentStatus`  |  Permite que um componente obtenha o status de uma implantação local no dispositivo principal.  |  Um ID de implantação local ou `*` para permitir o acesso a todas as implantações locais.  | 
|  `aws.greengrass#ListComponents`  |  Permite que um componente liste componentes no dispositivo principal.  |  `*`  | 
|  `aws.greengrass#GetComponentDetails`  |  Permite que um componente obtenha detalhes sobre um componente no dispositivo principal.  |  Um nome de componente, como `com.example.HelloWorld`, ou `*` para permitir o acesso a todos os componentes.  | 
|  `aws.greengrass#RestartComponent`  |  Permite que um componente reinicie um componente no dispositivo principal.  |  Um nome de componente, como `com.example.HelloWorld`, ou `*` para permitir o acesso a todos os componentes.  | 
|  `aws.greengrass#StopComponent`  |  Permite que um componente interrompa um componente no dispositivo principal.  |  Um nome de componente, como `com.example.HelloWorld`, ou `*` para permitir o acesso a todos os componentes.  | 
|  `aws.greengrass#CreateDebugPassword`  |  Permite que um componente gere uma senha para usar para entrar no [componente do console de depuração local](local-debug-console-component.md).  |  `*`  | 

**Example Exemplo de política de autorização**  
O exemplo de políticas de autorização a seguir permite que um componente crie implantações locais, visualize todas as implantações e componentes locais e reinicie e interrompa um componente chamado. `com.example.HelloWorld`  

```
{
  "accessControl": {
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:1": {
        "policyDescription": "Allows access to create local deployments and view deployments and components.",
        "operations": [
          "aws.greengrass#CreateLocalDeployment",
          "aws.greengrass#ListLocalDeployments",
          "aws.greengrass#GetLocalDeploymentStatus",
          "aws.greengrass#ListComponents",
          "aws.greengrass#GetComponentDetails"
        ],
        "resources": [
          "*"
        ]
      }
    },
    "aws.greengrass.Cli": {
      "com.example.MyLocalManagerComponent:cli:2": {
        "policyDescription": "Allows access to restart and stop the Hello World component.",
        "operations": [
          "aws.greengrass#RestartComponent",
          "aws.greengrass#StopComponent"
        ],
        "resources": [
          "com.example.HelloWorld"
        ]
      }
    }
  }
}
```

## CreateLocalDeployment
<a name="ipc-operation-createlocaldeployment"></a>

Crie ou atualize uma implantação local usando fórmulas de componentes, artefatos e argumentos de runtime especificados.

Essa operação fornece a mesma funcionalidade do [comando deployment create](gg-cli-deployment.md#deployment-create) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-createlocaldeployment-request"></a>

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

`recipeDirectoryPath` (Python: `recipe_directory_path`)  
(Opcional) O caminho absoluto para a pasta que contém arquivos de fórmulas de componentes.

`artifactDirectoryPath` (Python: `artifact_directory_path`)  
(Opcional) O caminho absoluto para a pasta que contém os arquivos de artefato a serem incluídos na implantação. A pasta de artefatos deve conter a seguinte estrutura de pastas:  

```
/path/to/artifact/folder/component-name/component-version/artifacts
```

`rootComponentVersionsToAdd` (Python: `root_component_versions_to_add`)  
(Opcional) As versões dos componentes a serem instaladas no dispositivo principal. Esse objeto, `ComponentToVersionMap`, é um mapa que contém os seguintes pares de chave-valor:    
`key`  
O nome do componente.  
`value`  
A versão do componente.

`rootComponentsToRemove` (Python: `root_components_to_remove`)  
(Opcional) Os componentes a serem desinstalados do dispositivo principal. Especifique uma lista em que cada entrada seja o nome de um componente.

`componentToConfiguration` (Python: `component_to_configuration`)  
(Opcional) As atualizações de configuração para cada componente na implantação. Esse objeto, `ComponentToConfiguration`, é um mapa que contém os seguintes pares de chave-valor:    
`key`  
O nome do componente.  
`value`  
O objeto JSON da atualização de configuração do componente. O objeto JSON deve ter o seguinte formato.  

```
{ 
  "MERGE": {
    "config-key": "config-value"
  },
  "RESET": [
    "path/to/reset/"
  ]
}
```
Para obter mais informações sobre atualizações de configuração, consulte [Atualizar configurações do componente](update-component-configurations.md).

`componentToRunWithInfo` (Python: `component_to_run_with_info`)  
(Opcional) A configuração de runtime para cada componente na implantação. Essa configuração inclui o usuário do sistema que possui os processos de cada componente e os limites do sistema a serem aplicados a cada componente. Esse objeto, `ComponentToRunWithInfo`, é um mapa que contém os seguintes pares de chave-valor:    
`key`  
O nome do componente.  
`value`  
A configuração de runtime do componente. Se você omitir um parâmetro de configuração de tempo de execução, o software AWS IoT Greengrass Core usará os valores padrão que você configura no núcleo do [Greengrass](greengrass-nucleus-component.md). Esse objeto, `RunWithInfo`, contém as seguintes informações:    
`posixUser` (Python: `posix_user`)  
(Opcional) <a name="deployment-posix-user-definition"></a>O usuário do sistema POSIX e, como opção, o grupo a ser usado para executar este componente em dispositivos principais do Linux. O usuário e o grupo, se especificados, devem existir em cada dispositivo principal do Linux. Especifique o usuário e o grupo separando-os por dois pontos (`:`), no seguinte formato: `user:group`. O grupo é opcional. Se você não especificar um grupo, o software AWS IoT Greengrass Core usará o grupo primário para o usuário. Para obter mais informações, consulte [Configurar o usuário que executa os componentes](configure-greengrass-core-v2.md#configure-component-user).   
`windowsUser` (Python: `windows_user`)  
(Opcional) <a name="deployment-windows-user-definition"></a>O usuário do Windows a ser usado para executar esse componente nos dispositivos essenciais do Windows. O usuário deve existir em cada dispositivo principal do Windows, e seu nome e senha devem ser armazenados na instância do Gerenciador de Credenciais da LocalSystem conta. Para obter mais informações, consulte [Configurar o usuário que executa os componentes](configure-greengrass-core-v2.md#configure-component-user).   
`systemResourceLimits` (Python: `system_resource_limits`)  
(Opcional) <a name="deployment-system-resource-limits-definition"></a>Os limites de recursos do sistema a serem aplicados aos processos desse componente. Você pode aplicar limites de recursos do sistema a componentes Lambda genéricos e não conteinerizados. Para obter mais informações, consulte [Configurar limites de recursos do sistema para componentes](configure-greengrass-core-v2.md#configure-component-system-resource-limits).   
AWS IoT Greengrass atualmente não oferece suporte a esse recurso nos dispositivos principais do Windows.   
Esse objeto, `SystemResourceLimits`, contém as seguintes informações:    
`cpus`  
(Opcional) <a name="system-resource-limits-cpu-definition-this"></a>A quantidade máxima de tempo de CPU que os processos deste componente podem usar no dispositivo principal. O tempo total da CPU de um dispositivo essencial é equivalente ao número de núcleos da CPU do dispositivo. Por exemplo, em um dispositivo principal com quatro núcleos da CPU, é possível definir esse valor como `2` a fim de limitar os processos do componente para 50% de uso em cada núcleo da CPU. Em um dispositivo com um núcleo da CPU, você pode definir esse valor como `0.25` a fim de limitar os processos do componente para 25% de uso da CPU. Se você definir esse valor como um número maior que o número de núcleos de CPU, o software AWS IoT Greengrass Core não limitará o uso da CPU do componente.   
`memory`  
(Opcional) <a name="system-resource-limits-memory-definition-this"></a>A quantidade máxima de RAM (em kilobytes) que os processos desse componente podem usar no dispositivo principal. 

`groupName` (Python: `group_name`)  
(Opcional) O nome do grupo de objetos a ser direcionado com essa implantação.

### Resposta
<a name="ipc-operation-createlocaldeployment-response"></a>

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

`deploymentId` (Python: `deployment_id`)  
O ID da implantação local que a solicitação criou.

## ListLocalDeployments
<a name="ipc-operation-listlocaldeployments"></a>

Obtém o status das últimas 10 implantações locais.

Essa operação fornece a mesma funcionalidade do [comando de lista de implantação](gg-cli-deployment.md#deployment-list) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-listlocaldeployments-request"></a>

A solicitação dessa operação não tem nenhum parâmetro.

### Resposta
<a name="ipc-operation-listlocaldeployments-response"></a>

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

`localDeployments` (Python: `local_deployments`)  
A lista de implantações locais. Cada objeto nessa lista é um objeto `LocalDeployment`, que contém as seguintes informações:  <a name="ipc-local-deployment-object-shape"></a>  
`deploymentId` (Python: `deployment_id`)  
O ID da implantação local.  
`status`  
O status da implantação local. Esse enumerador, `DeploymentStatus`, tem os seguintes valores:  
+ `QUEUED`
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`

## GetLocalDeploymentStatus
<a name="ipc-operation-getlocaldeploymentstatus"></a>

Obtém o status de uma implantação local.

Essa operação fornece a mesma funcionalidade do [comando de status de implantação](gg-cli-deployment.md#deployment-status) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-getlocaldeploymentstatus-request"></a>

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

`deploymentId` (Python: `deployment_id`)  
O ID da implantação local a ser obtida.

### Resposta
<a name="ipc-operation-getlocaldeploymentstatus-response"></a>

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

`deployment`  
A implantação local. Esse objeto, `LocalDeployment`, contém as seguintes informações:  <a name="ipc-local-deployment-object-shape"></a>  
`deploymentId` (Python: `deployment_id`)  
O ID da implantação local.  
`status`  
O status da implantação local. Esse enumerador, `DeploymentStatus`, tem os seguintes valores:  
+ `QUEUED`
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`

## ListComponents
<a name="ipc-operation-listcomponents"></a>

Obtém o nome, a versão, o status e a configuração de cada componente raiz no dispositivo principal. Um *componente raiz* é um componente que você especifica em uma implantação. Essa resposta não inclui componentes que são instalados como dependências de outros componentes.

Essa operação fornece a mesma funcionalidade do [comando de lista de componentes](gg-cli-component.md#component-list) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-listcomponents-request"></a>

A solicitação dessa operação não tem nenhum parâmetro.

### Resposta
<a name="ipc-operation-listcomponents-response"></a>

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

`components`  
A lista de componentes raiz no dispositivo essencial. Cada objeto nessa lista é um objeto `ComponentDetails`, que contém as seguintes informações:  <a name="ipc-component-details-object-shape"></a>  
`componentName` (Python: `component_name`)  
O nome do componente.  
`version`  
A versão do componente.  
`state`  
O estado do componente. Esse estado pode ser um dos seguintes:  
+ `BROKEN`
+ `ERRORED`
+ `FINISHED`
+ `INSTALLED`
+ `NEW`
+ `RUNNING`
+ `STARTING`
+ `STOPPING`  
`configuration`  
A configuração do componente como um objeto JSON.

## GetComponentDetails
<a name="ipc-operation-getcomponentdetails"></a>

Obtém a versão, o status e a configuração de um componente no dispositivo principal.

Essa operação fornece a mesma funcionalidade do [comando de detalhes do componente](gg-cli-component.md#component-details) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-getcomponentdetails-request"></a>

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

`componentName` (Python: `component_name`)  
O nome do componente a ser obtido.

### Resposta
<a name="ipc-operation-getcomponentdetails-response"></a>

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

`componentDetails` (Python: `component_details`)  
Os detalhes do componente. Esse objeto, `ComponentDetails`, contém as seguintes informações:  <a name="ipc-component-details-object-shape"></a>  
`componentName` (Python: `component_name`)  
O nome do componente.  
`version`  
A versão do componente.  
`state`  
O estado do componente. Esse estado pode ser um dos seguintes:  
+ `BROKEN`
+ `ERRORED`
+ `FINISHED`
+ `INSTALLED`
+ `NEW`
+ `RUNNING`
+ `STARTING`
+ `STOPPING`  
`configuration`  
A configuração do componente como um objeto JSON.

## RestartComponent
<a name="ipc-operation-restartcomponent"></a>

Reinicia um componente no dispositivo essencial.

**nota**  
Embora você possa reiniciar qualquer componente, recomendamos que você reinicie somente [componentes genéricos](develop-greengrass-components.md#component-types).

Essa operação fornece a mesma funcionalidade do [comando de reinicialização do componente](gg-cli-component.md#component-restart) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-restartcomponent-request"></a>

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

`componentName` (Python: `component_name`)  
O nome do componente.

### Resposta
<a name="ipc-operation-restartcomponent-response"></a>

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

`restartStatus` (Python: `restart_status`)  
O status da solicitação de reinicialização. O status da solicitação pode ser um dos seguintes:  
+ `SUCCEEDED`
+ `FAILED`

`message`  
Uma mensagem sobre por que o componente falhou na reinicialização, se a solicitação falhou.

### Exemplos
<a name="ipc-operation-restartcomponent-examples"></a>

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

------
#### [ Rust ]

**Example Exemplo: reiniciar um componente**  

```
use gg_sdk::Sdk;

fn main() {
    let sdk = Sdk::init();
    sdk.connect().expect("Failed to establish IPC connection");

    let component_name = "com.example.HelloWorld";

    sdk.restart_component(component_name)
        .expect("Failed to restart component");

    println!("Successfully requested restart for component: {component_name}");
}
```

------
#### [ C ]

**Example Exemplo: reiniciar um componente**  

```
#include <gg/error.h>
#include <gg/ipc/client.h>
#include <gg/sdk.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    gg_sdk_init();

    GgError err = ggipc_connect();
    if (err != GG_ERR_OK) {
        fprintf(stderr, "Failed to establish IPC connection.\n");
        exit(-1);
    }

    GgBuffer component_name = GG_STR("com.example.HelloWorld");

    err = ggipc_restart_component(component_name);
    if (err != GG_ERR_OK) {
        fprintf(
            stderr,
            "Failed to restart component: %.*s\n",
            (int) component_name.len,
            component_name.data
        );
        exit(-1);
    }

    printf(
        "Successfully requested restart for component: %.*s\n",
        (int) component_name.len,
        component_name.data
    );
}
```

------
#### [ C\$1\$1 (Component SDK) ]

**Example Exemplo: reiniciar um componente**  

```
#include <gg/ipc/client.hpp>
#include <iostream>

int main() {
    auto &client = gg::ipc::Client::get();

    auto error = client.connect();
    if (error) {
        std::cerr << "Failed to establish IPC connection.\n";
        exit(-1);
    }

    std::string_view component_name = "com.example.HelloWorld";

    error = client.restart_component(component_name);
    if (error) {
        std::cerr << "Failed to restart component: " << component_name << "\n";
        exit(-1);
    }

    std::cout << "Successfully requested restart for component: "
              << component_name << "\n";
}
```

------

## StopComponent
<a name="ipc-operation-stopcomponent"></a>

Interrompe os processos de um componente no dispositivo essencial.

**nota**  
Embora você possa interromper qualquer componente, recomendamos que você interrompa somente [os componentes genéricos](develop-greengrass-components.md#component-types).

Essa operação fornece a mesma funcionalidade do [comando de parada do componente](gg-cli-component.md#component-stop) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-stopcomponent-request"></a>

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

`componentName` (Python: `component_name`)  
O nome do componente.

### Resposta
<a name="ipc-operation-stopcomponent-response"></a>

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

`stopStatus` (Python: `stop_status`)  
O status da solicitação de interrupção. O status da solicitação pode ser um dos seguintes:  
+ `SUCCEEDED`
+ `FAILED`

`message`  
Uma mensagem sobre o motivo pelo qual o componente não foi interrompido, se a solicitação falhou.

## CreateDebugPassword
<a name="ipc-operation-createdebugpassword"></a>

Gera uma senha aleatória que você pode usar para entrar no [componente local do console de depuração](local-debug-console-component.md). A senha expira 8 horas depois de ser gerada.

Essa operação fornece a mesma funcionalidade do [get-debug-password comando](gg-cli-get-debug-password.md) na CLI do Greengrass.

### Solicitação
<a name="ipc-operation-createdebugpassword-request"></a>

A solicitação dessa operação não tem nenhum parâmetro.

### Resposta
<a name="ipc-operation-createdebugpassword-response"></a>

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

`username`  
O nome de usuário a ser usado para fazer login.

`password`  
A senha a ser usada para fazer login.

`passwordExpiration` (Python: `password_expiration`)  
A hora em que a senha expira.

`certificateSHA256Hash` (Python: `certificate_sha256_hash`)  
A impressão digital SHA-256 do certificado autoassinado que o console de depuração local usa quando o HTTPS está ativado. Ao abrir o console de depuração local, use essa impressão digital para verificar se o certificado é legítimo e se a conexão é segura.

`certificateSHA1Hash` (Python: `certificate_sha1_hash`)  
A impressão digital SHA-1 do certificado autoassinado que o console de depuração local usa quando o HTTPS está ativado. Ao abrir o console de depuração local, use essa impressão digital para verificar se o certificado é legítimo e se a conexão é segura.

# Autentique e autorize dispositivos cliente
<a name="ipc-client-device-auth"></a>

**nota**  
Esse recurso está disponível para a versão 2.6.0 e posterior do [componente de núcleo do Greengrass](greengrass-nucleus-component.md).

Use o serviço IPC de autenticação de dispositivo cliente para desenvolver um componente de intermediário local personalizado no qual dispositivos IoT locais, como dispositivos cliente, possam se conectar.

Para usar essas operações de IPC, inclua a versão 2.2.0 ou posterior do componente de [autenticação do dispositivo cliente como uma dependência em seu componente](client-device-auth-component.md) personalizado. Em seguida, você pode usar as operações de IPC em seus componentes personalizados para fazer o seguinte:
+ Verifique a identidade dos dispositivos cliente que se conectam ao dispositivo núcleo.
+ Crie uma sessão para que um dispositivo cliente se conecte ao dispositivo principal.
+ Verifique se um dispositivo cliente tem permissão para realizar uma ação.
+ Receba uma notificação quando o certificado do servidor do dispositivo principal for alterado.

**Topics**
+ [Versões mínimas do SDK](#ipc-client-device-auth-sdk-versions)
+ [Autorização](#ipc-client-device-auth-authorization)
+ [VerifyClientDeviceIdentity](#ipc-operation-verifyclientdeviceidentity)
+ [GetClientDeviceAuthToken](#ipc-operation-getclientdeviceauthtoken)
+ [AuthorizeClientDeviceAction](#ipc-operation-authorizeclientdeviceaction)
+ [SubscribeToCertificateUpdates](#ipc-operation-subscribetocertificateupdates)

## Versões mínimas do SDK
<a name="ipc-client-device-auth-sdk-versions"></a>

A tabela a seguir lista as versões mínimas do AWS IoT Device SDK que você deve usar para interagir com o serviço IPC de autenticação do dispositivo cliente.


| SDK | Versão mínima | 
| --- | --- | 
|  [AWS IoT Device SDK para Java v2](https://github.com/aws/aws-iot-device-sdk-java-v2)  |  v1.9.3  | 
|  [AWS IoT Device SDK para Python v2](https://github.com/aws/aws-iot-device-sdk-python-v2)  |  v1.11.3  | 
|  [AWS IoT Device SDK para C\$1\$1 v2](https://github.com/aws/aws-iot-device-sdk-cpp-v2)  |  v1.18.3  | 
|  [AWS IoT Device SDK para JavaScript v2](https://github.com/aws/aws-iot-device-sdk-js-v2)  |  v1.12.0  | 

## Autorização
<a name="ipc-client-device-auth-authorization"></a>

Para usar o serviço IPC de autenticação do dispositivo cliente em um componente personalizado, você deve definir políticas de autorização que permitam que seu componente execute essas operações. Para obter informações sobre a definição de políticas de autorização, consulte [Autorizar componentes a realizar operações de IPC](interprocess-communication.md#ipc-authorization-policies).

As políticas de autorização para autenticação e autorização do dispositivo cliente têm as seguintes propriedades.

**Identificador de serviço IPC:** `aws.greengrass.clientdevices.Auth`


| Operation | Description | Recursos | 
| --- | --- | --- | 
|  `aws.greengrass#VerifyClientDeviceIdentity`  |  Permite que um componente verifique a identidade de um dispositivo cliente.  |  `*`  | 
|  `aws.greengrass#GetClientDeviceAuthToken`  |  Permite que um componente valide as credenciais de um dispositivo cliente e crie uma sessão para esse dispositivo cliente.  |  `*`  | 
|  `aws.greengrass#AuthorizeClientDeviceAction`  |  Permite que um componente verifique se um dispositivo cliente tem permissão para realizar uma ação.  |  `*`  | 
|  `aws.greengrass#SubscribeToCertificateUpdates`  |  Permite que um componente receba notificações quando o certificado do servidor do dispositivo principal é alterado.  |  `*`  | 
|  `*`  |  Permite que um componente execute todas as operações do serviço IPC de autenticação do dispositivo cliente.  |  `*`  | 

### Exemplos de política de autorização
<a name="ipc-client-device-auth-authorization-policy-examples"></a>

Consulte o exemplo de política de autorização a seguir para configurar políticas de autorização para seus componentes.

**Example Exemplo de política de autorização**  
O exemplo de política de autorização a seguir permite que um componente execute todas as operações IPC de autenticação do dispositivo cliente.  

```
{
  "accessControl": {
    "aws.greengrass.clientdevices.Auth": {
      "com.example.MyLocalBrokerComponent:clientdevices:1": {
        "policyDescription": "Allows access to authenticate and authorize client devices.",
        "operations": [
          "aws.greengrass#VerifyClientDeviceIdentity",
          "aws.greengrass#GetClientDeviceAuthToken",
          "aws.greengrass#AuthorizeClientDeviceAction",
          "aws.greengrass#SubscribeToCertificateUpdates"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}
```

## VerifyClientDeviceIdentity
<a name="ipc-operation-verifyclientdeviceidentity"></a>

Verifique a identidade de um dispositivo cliente. Essa operação verifica se o dispositivo cliente AWS IoT é válido.

### Solicitação
<a name="ipc-operation-verifyclientdeviceidentity-request"></a>

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

`credential`  
As credenciais do dispositivo cliente. Esse objeto, `ClientDeviceCredential`, contém as seguintes informações:    
`clientDeviceCertificate` (Python: `client_device_certificate`)  
O certificado do dispositivo X.509 do dispositivo cliente.

### Resposta
<a name="ipc-operation-verifyclientdeviceidentity-response"></a>

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

`isValidClientDevice` (Python: `is_valid_client_device`)  
Se a identidade do dispositivo cliente é válida.

## GetClientDeviceAuthToken
<a name="ipc-operation-getclientdeviceauthtoken"></a>

Valida as credenciais de um dispositivo cliente e cria uma sessão para o dispositivo cliente. Essa operação retorna um token de sessão que você pode usar em solicitações subsequentes para [autorizar ações do dispositivo cliente](#ipc-operation-authorizeclientdeviceaction).

Para conectar com êxito um dispositivo cliente, o [componente de autenticação do dispositivo cliente](client-device-auth-component.md#client-device-auth-component-configuration) deve conceder a `mqtt:connect` permissão para o ID do cliente que o dispositivo cliente usa.

### Solicitação
<a name="ipc-operation-getclientdeviceauthtoken-request"></a>

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

`credential`  
As credenciais do dispositivo cliente. Esse objeto, `CredentialDocument`, contém as seguintes informações:    
`mqttCredential` (Python: `mqtt_credential`)  
As credenciais MQTT do dispositivo cliente. Especifique o ID do cliente e o certificado que o dispositivo cliente usa para se conectar. Esse objeto, `MQTTCredential`, contém as seguintes informações:    
`clientId` (Python: `client_id`)  
O ID do cliente usado para conectar.  
`certificatePem` (Python: `certificate_pem`)  
O certificado do dispositivo X.509 a ser usado para se conectar.  
`username`  
No momento, essa propriedade não é usada.  
`password`  
No momento, essa propriedade não é usada.

### Resposta
<a name="ipc-operation-getclientdeviceauthtoken-response"></a>

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

`clientDeviceAuthToken` (Python: `client_device_auth_token`)  
O token da sessão para o dispositivo cliente. Você pode usar esse token de sessão em solicitações subsequentes para autorizar as ações desse dispositivo cliente.

## AuthorizeClientDeviceAction
<a name="ipc-operation-authorizeclientdeviceaction"></a>

Verifique se um dispositivo cliente tem permissão para realizar uma ação em um recurso. *As políticas de autorização do dispositivo cliente* especificam as permissões que os dispositivos cliente podem executar enquanto conectados a um dispositivo principal. Você define as políticas de autorização do dispositivo cliente ao configurar o [componente de autenticação do dispositivo cliente](client-device-auth-component.md#client-device-auth-component-configuration).

### Solicitação
<a name="ipc-operation-authorizeclientdeviceaction-request"></a>

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

`clientDeviceAuthToken` (Python: `client_device_auth_token`)  
O token da sessão para o dispositivo cliente.

`operation`  
A operação a ser autorizada.

`resource`  
O recurso em que o dispositivo cliente executa a operação.

### Resposta
<a name="ipc-operation-authorizeclientdeviceaction-response"></a>

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

`isAuthorized` (Python: `is_authorized`)  
Se o dispositivo cliente está autorizado a realizar a operação no recurso.

## SubscribeToCertificateUpdates
<a name="ipc-operation-subscribetocertificateupdates"></a>

Inscreva-se para receber o novo certificado de servidor do dispositivo principal sempre que ele for rotacionado. Quando o certificado do servidor muda, os agentes devem recarregar usando o novo certificado do servidor.

Por padrão, o [componente de autenticação do dispositivo cliente](client-device-auth-component.md) alterna os certificados do servidor a cada 7 dias. Você pode configurar o intervalo de rotação entre 2 e 10 dias.

<a name="ipc-subscribe-operation-note"></a>Essa operação é uma operação de assinatura em que você assina um fluxo de mensagens de eventos. Para usar essa operação, defina um manipulador de resposta de fluxo com funções que manipulam mensagens de eventos, erros e encerramento de fluxo. Para obter mais informações, consulte [Inscrever-se nos fluxos de eventos da IPC](interprocess-communication.md#ipc-subscribe-operations).

**Tipo de mensagem do evento:** `CertificateUpdateEvent`

### Solicitação
<a name="ipc-operation-subscribetocertificateupdates-request"></a>

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

`certificateOptions` (Python: `certificate_options`)  
Os tipos de atualizações de certificado a serem assinadas. Esse objeto, `CertificateOptions`, contém as seguintes informações:    
`certificateType` (Python: `certificate_type`)  
O tipo de atualização de certificado em que se inscreve. Escolha a seguinte opção:  
+ `SERVER`

### Resposta
<a name="ipc-operation-subscribetocertificateupdates-response"></a>

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

`messages`  
O fluxo de mensagens. Esse objeto, `CertificateUpdateEvent`, contém as seguintes informações:    
`certificateUpdate` (Python: `certificate_update`)  
As informações sobre o novo certificado. Esse objeto, `CertificateUpdate`, contém as seguintes informações:    
`certificate`  
O certificado.  
`privateKey` (Python: `private_key`)  
A chave privada do certificado.  
`publicKey` (Python: `public_key`)  
A chave pública do certificado.  
`caCertificates` (Python: `ca_certificates`)  
A lista de certificados de autoridade de certificação (certificate authority, CA) na cadeia de certificados de CA do certificado.