Ceci est le guide du développeur du AWS CDK v2. L'ancien CDK v1 est entré en maintenance le 1er juin 2022 et a pris fin le 1er juin 2023.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configuration des messages et des interactions du CDK Toolkit

La bibliothèque du kit d'outils AWS CDK fournit l' IIoHost interface permettant de personnaliser la façon dont les messages et les interactions sont gérés pendant les opérations du CDK, ce qui vous permet de contrôler l'affichage de la progression du déploiement, des messages d'erreur et des instructions utilisateur afin de mieux s'intégrer à l'expérience utilisateur de votre application.

Avant d'effectuer des opérations telles que le déploiement ou la synthèse, vous devez comprendre comment le CDK Toolkit communique avec les utilisateurs. L'IIoHostinterface sert de canal de communication entre le kit CDK et votre application, gérant à la fois les messages sortants et les réponses des utilisateurs entrants.

Lorsque le CDK Toolkit exécute des opérations, il communique par le biais de deux mécanismes principaux :

Utilisation de l'IIoHostinterface

L'IIoHostinterface comprend deux méthodes principales :

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

Niveaux de message et types de demandes

Le kit d'outils CDK génère plusieurs types de messages et de demandes :

Niveaux des messages

Pour une liste complète, voir IoMessages Registry dans le manuel de référence de l'API de la bibliothèque AWS CDK Toolkit.

Types de demande

Le kit d'outils CDK envoie des demandes lorsqu'il a besoin d'une saisie ou d'une confirmation de la part de l'utilisateur. Il s'agit de messages spéciaux qui permettent d'obtenir une réponse. Si aucune réponse n'est fournie, le kit d'outils utilisera une réponse par défaut lorsqu'elle sera disponible.

Mise en IIoHost œuvre de base

Voici un exemple simple de mise en œuvre d'un hôte io personnalisé :

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

Le kit d'outils CDK attend la fin de chaque appel, ce qui vous permet d'effectuer des opérations asynchrones telles que des requêtes HTTP ou des instructions utilisateur lors de la gestion des messages.

IIoHostComportement par défaut

Si vous ne fournissez pas d'hôte io personnalisé, la bibliothèque du kit d'outils CDK utilise une implémentation non interactive par défaut :

Ce comportement par défaut convient aux opérations sans assistance, mais pas aux applications de ligne de commande interactives. Pour les applications en ligne de commande qui nécessitent une interaction de l'utilisateur, vous devez implémenter un hôte io personnalisé. Les implémentations personnalisées sont également utiles pour l'intégration aux systèmes de journalisation ou à d'autres environnements spécialisés. UIs

Implémentation avancée de l'hôte io

Pour les scénarios plus complexes, nous recommandons d'étendre la NonInteractiveIoHost classe comme point de départ. Cette approche vous permet de tirer parti de l'implémentation non interactive existante tout en personnalisant uniquement les comportements spécifiques que vous devez modifier.

Voici un exemple d'hôte io personnalisé qui étend l'implémentation de base :

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

Cette approche est plus facile à maintenir que d'implémenter l'intégralité de l'IIoHostinterface à partir de zéro, car il suffit de remplacer les méthodes spécifiques qui nécessitent un comportement personnalisé.

Intégration à différents environnements

Intégration d'applications Web

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

Intégration de l'environnement CI/CD

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

Bonnes pratiques pour la mise en œuvre d'un hôte io

Lorsque vous implémentez un hôte io personnalisé, tenez compte des meilleures pratiques suivantes :

L'exemple suivant illustre ces meilleures pratiques en implémentant un hôte io personnalisé avec gestion des erreurs, délais d'expiration pour les interactions avec les utilisateurs et journalisation appropriée. Cette implémentation convient aux applications interactives dans lesquelles vous devez trouver un équilibre entre la réactivité des utilisateurs et la fiabilité du fonctionnement :

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

Résolution des problèmes

Considérations à prendre en compte lors de l'implémentation d'un hôte io personnalisé :

L'exemple suivant illustre une approche robuste de gestion des niveaux de message, y compris la gestion progressive des types de messages inconnus qui pourraient être introduits dans les futures versions du CDK. Cette implémentation garantit que votre hôte io reste compatible avec les mises à jour du CDK tout en maintenant une journalisation correcte :

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