Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

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

# Configuração de mensagens e interações do Kit de Ferramentas CDK
<a name="toolkit-library-configure-messages"></a>

A Biblioteca do Kit de Ferramentas CDK da AWS fornece a interface ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/IIoHost/) ` para personalizar a forma como as mensagens e interações são tratadas durante as operações do CDK, permitindo que você controle a exibição do andamento da implantação, das mensagens de erro e dos avisos do usuário para melhor integração com a experiência do usuário da sua aplicação.

Antes de realizar operações como implantação ou síntese, você precisa entender como o Kit de Ferramentas CDK se comunica com os usuários. A interface `IIoHost` serve como canal de comunicação entre o Kit de Ferramentas CDK e sua aplicação, gerenciando tanto as mensagens enviadas quanto as respostas recebidas do usuário.

Quando o Kit de Ferramentas CDK executa operações, ele se comunica por meio de dois mecanismos principais:
+  **Mensagens**: saídas informativas que notificam você sobre o andamento da operação (como “Iniciando a implantação” ou “Recurso criado”).
+  **Solicitações**: pontos de decisão que exigem entrada ou confirmação (como “Deseja implantar essas alterações?”) , dando a você a oportunidade de fornecer informações que, de antemão, não eram necessárias.

## Uso da interface `IIoHost`
<a name="toolkit-library-configure-messages-iiohost"></a>

A interface `IIoHost` consiste em dois métodos principais:

1.  `notify`: trata mensagens informativas unidirecionais.

1.  `requestResponse`: trata de solicitações interativas que exijam uma resposta.

```
import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib';

interface IIoHost {
  // Handle informational messages
  notify(message: IoMessage): Promise<void>;

  // Handle requests that need responses
  requestResponse(request: IoRequest): Promise<any>;
}
```

## Níveis de mensagens e tipos de solicitação
<a name="toolkit-library-configure-messages-levels"></a>

O Kit de Ferramentas CDK gera vários tipos de mensagens e solicitações:

### Níveis de mensagens
<a name="_message_levels"></a>
+  **Depuração**: mensagens detalhadas para solução de problemas.
+  **Erro**: mensagens de erro que podem afetar a operação.
+  **Informações**: mensagens informativas gerais.
+  **Resultado**: mensagem principal de uma operação.
+  **Rastreamento**: informações muito detalhadas do fluxo de execução.
+  **Aviso**: mensagens de aviso que não impedem a operação.

Para obter uma lista completa, consulte [Registro de IoMessages](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) na *Referência de API da Biblioteca do Kit de Ferramentas CDK da AWS*.

### Tipos de solicitação
<a name="_request_types"></a>

O Kit de Ferramentas CDK envia solicitações quando precisa de informações ou confirmação do usuário. Essas são mensagens especiais que permitem uma resposta. Se nenhuma resposta for fornecida, o Kit de Ferramentas usará uma resposta padrão quando disponível.

## Implementação básica do `IIoHost`
<a name="toolkit-library-configure-messages-basic"></a>

Aqui está um exemplo simples de implementação de um host de e/s personalizado:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Create a toolkit with custom message handling
const toolkit = new Toolkit({
  ioHost: {
    // Implementing the IIoHost interface
    // Handle informational messages
    notify: async function (msg) {
      // Example: Handle different message levels appropriately
      switch (msg.level) {
        case 'error':
          console.error(`[${msg.time}] ERROR: ${msg.message}`);
          break;
        case 'warning':
          console.warn(`[${msg.time}] WARNING: ${msg.message}`);
          break;
        case 'info':
          console.info(`[${msg.time}] INFO: ${msg.message}`);
          break;
        case 'debug':
          console.debug(`[${msg.time}] DEBUG: ${msg.message}`);
          break;
        case 'trace':
          console.debug(`[${msg.time}] TRACE: ${msg.message}`);
          break;
        default:
          console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
      }
    },

    // Handle requests that need responses
    requestResponse: async function (msg) {
      // Example: Log the request and use default response
      console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`);
      return msg.defaultResponse;

      // Or implement custom logic to provide responses
      // if (msg.type === 'deploy') {
      //   return promptUserForDeployment(msg);
      // }
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

O Kit de Ferramentas CDK aguarda a conclusão de cada chamada, permitindo que você execute operações assíncronas, como solicitações de HTTP ou solicitações do usuário, ao lidar com mensagens.

## Comportamento padrão do `IIoHost`
<a name="toolkit-library-configure-messages-iiohost-default"></a>

Se você não fornecer um host ide e/s personalizado, a Biblioteca do Kit de Ferramentas CDK usa uma implementação padrão não interativa:
+ Saída do console para mensagens (usando cores apropriadas para diferentes tipos de mensagens).
+ Totalmente não interativa, sem solicitações de entrada do usuário.
+ Usa automaticamente as respostas padrão sempre que possível (equivalente a responder “sim” às solicitações).
+ Falha quando a entrada é necessária, mas nenhuma resposta padrão está disponível.

Esse comportamento padrão é adequado para operações autônomas, mas não para aplicações de linha de comando interativas. Para aplicações de linha de comando que exijam interação do usuário, você precisará implementar um host de e/s personalizado. Implementações personalizadas também são úteis para integração com sistemas de log, interfaces de usuário ou outros ambientes especializados.

## Implementação avançada de host de e/s
<a name="toolkit-library-configure-messages-advanced"></a>

Para cenários mais complexos, recomendamos estender a aula `NonInteractiveIoHost` como ponto de partida. Essa abordagem permite que você aproveite a implementação não interativa existente e, ao mesmo tempo, personalize somente os comportamentos específicos que você precisa alterar.

Veja abaixo um exemplo de host de e/s personalizado que estende a implementação básica:

```
import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib';

class MyCustomIoHost extends NonInteractiveIoHost {
  // Override only the methods you need to customize

  // Example: Custom implementation for notify
  public async notify(msg: IoMessage<unknown>): Promise<void> {
    // Add custom notification handling logic
    if (msg.level === 'error') {
      console.error(`ERROR: ${msg.message}`);
      // Optionally log to a service or notify a monitoring system
      await this.logToMonitoringService(msg);
    } else {
      await super.notify(msg);
    }
  }

  // Example: Custom implementation for requestResponse
  public async requestResponse<T, U>(request: IoRequest<T, U>): Promise<U> {
    // Implement custom request handling
    console.log(`Received request: ${request.message}`);
    return request.defaultResponse;
  }

  private async logToMonitoringService(msg: IoMessage<unknown>): Promise<void> {
    // Implementation for monitoring service integration
    console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`);
  }
}
```

Essa abordagem é mais fácil de manter do que implementar toda a interface `IIoHost` do zero, pois você só precisa substituir os métodos específicos que exijam comportamento personalizado.

## Integração com diferentes ambientes
<a name="toolkit-library-configure-messages-integration"></a>

### Integração com aplicações da Web
<a name="_web_application_integration"></a>

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example for integrating with a web application
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Send message to frontend via WebSocket
      webSocketServer.send(JSON.stringify({
        type: 'cdk-notification',
        messageLevel: msg.level,
        message: msg.message,
        time: msg.time
      }));
    },

    requestResponse: async function (msg) {
      // Create a promise that will be resolved when the user responds
      return new Promise((resolve) => {
        const requestId = generateUniqueId();

        // Store the resolver function
        pendingRequests[requestId] = resolve;

        // Send request to frontend
        webSocketServer.send(JSON.stringify({
          type: 'cdk-request',
          requestId: requestId,
          requestType: msg.type,
          message: msg.message,
          defaultResponse: msg.defaultResponse
        }));

        // Frontend would call an API endpoint with the response,
        // which would then call pendingRequests[requestId](response)
      });
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

### Integração de ambientes de CI/CD
<a name="_cicd_environment_integration"></a>

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example for CI/CD environments (non-interactive)
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Log all messages with appropriate level
      switch (msg.level) {
        case 'error':
          console.error(msg.message);
          break;
        case 'warning':
          console.warn(msg.message);
          break;
        default:
          console.log(msg.message);
      }
    },

    requestResponse: async function (msg) {
      // In CI/CD, always use default responses or predefined answers
      console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`);
      return msg.defaultResponse;
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

## Práticas recomendadas para implementação de host de e/s
<a name="toolkit-library-configure-messages-best-practices"></a>

Ao implementar um host de e/s personalizado, considere estas práticas recomendadas:
+  **Tratamento de erros**: implemente um tratamento robusto de erros em seus métodos de host de e/s para evitar que falhas afetem as operações do CDK.
+  **Tempos limite**: considere a implementação de tempos limite para interações do usuário para evitar esperas indefinidas.
+  **Logs**: armazene mensagens importantes em logs para solução de problemas, especialmente em ambientes não interativos.
+  **Respostas padrão**: forneça respostas padrão sensatas para ambientes automatizados em que a interação do usuário não seja possível.
+  **Indicação de andamento**: para operações de longa duração, forneça indicadores de andamento claros para melhorar a experiência do usuário.

O exemplo a seguir demonstra essas melhores práticas implementando um host de e/s personalizado com tratamento de erros, tempos limite para interações do usuário e logs adequados. Essa implementação é adequada para aplicações interativas em que você precise equilibrar a capacidade de resposta do usuário com uma operação confiável:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example with error handling and timeouts
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      try {
        console.log(`[${msg.time}] ${msg.level}: ${msg.message}`);
        // Additional logging or UI updates
      } catch (error) {
        // Ensure errors in notification handling don't break the CDK operation
        console.error("Error handling notification:", error);
      }
    },

    requestResponse: async function (msg) {
      try {
        // Implement timeout for user response
        const response = await Promise.race([
          getUserResponse(msg),
          new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000))
        ]);
        return response;
      } catch (error) {
        console.error("Error handling request:", error);
        return msg.defaultResponse;
      }
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```

## Solução de problemas
<a name="toolkit-library-configure-messages-troubleshooting"></a>

Considerações ao implementar um host de e/s personalizado:
+  **Rejeições de promessas não tratadas**: garanta que todas as operações assíncronas sejam tratadas adequadamente com blocos try/catch.
+  **Espera infinita**: implemente tempos limite para todas as interações do usuário para evitar que a aplicação seja interrompida.
+  **Níveis de mensagens ausentes**: esteja preparado para lidar com novos níveis de mensagens que possam ser adicionados em futuras versões do CDK.
+  **Respostas inconsistentes**: garanta que sua implementação de requestResponse retorne valores no formato esperado.

O exemplo a seguir demonstra uma abordagem robusta para lidar com níveis de mensagem, incluindo o tratamento elegante de tipos de mensagens desconhecidos que podem ser introduzidos em futuras versões do CDK. Essa implementação garante que seu host de e/s permaneça compatível com as atualizações do CDK, mantendo os logs adequados:

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

// Example of handling unknown message levels
const toolkit = new Toolkit({
  ioHost: {
    notify: async function (msg) {
      // Handle known levels
      const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status'];

      if (knownLevels.includes(msg.level)) {
        // Handle known level
        handleKnownMessageLevel(msg);
      } else {
        // Handle unknown level as info
        console.log(`Unknown message level "${msg.level}": ${msg.message}`);
      }
    },

    requestResponse: async function (msg) {
      // Default implementation
      return msg.defaultResponse;
    }
  } as IIoHost // Explicitly cast to IIoHost interface
});
```