Dies ist der AWS CDK v2-Entwicklerhandbuch. Das ältere CDK v1 wurde am 1. Juni 2022 in die Wartung aufgenommen und der Support wurde am 1. Juni 2023 eingestellt.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

CDK Toolkit-Nachrichten und Interaktionen konfigurieren

Die AWS CDK Toolkit Library bietet eine IIoHost Benutzeroberfläche, mit der Sie die Art und Weise anpassen können, wie Nachrichten und Interaktionen während des CDK-Betriebs behandelt werden. So können Sie die Anzeige des Bereitstellungsfortschritts, der Fehlermeldungen und der Benutzereingaben steuern, um sie besser in die Benutzererfahrung Ihrer Anwendung zu integrieren.

Bevor Sie Operationen wie Bereitstellung oder Synthese durchführen, müssen Sie verstehen, wie das CDK Toolkit mit Benutzern kommuniziert. Die IIoHost Schnittstelle dient als Kommunikationskanal zwischen dem CDK Toolkit und Ihrer Anwendung und verarbeitet sowohl ausgehende Nachrichten als auch eingehende Benutzerantworten.

Wenn das CDK Toolkit Operationen ausführt, kommuniziert es über zwei Hauptmechanismen:

Verwenden der IIoHost Schnittstelle

Die IIoHost Schnittstelle besteht aus zwei Hauptmethoden:

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

Nachrichtenebenen und Anforderungstypen

Das CDK Toolkit generiert verschiedene Arten von Nachrichten und Anfragen:

Nachrichtenebenen

Eine vollständige Liste finden Sie unter IoMessages Registry in der AWS CDK Toolkit Library API-Referenz.

Anforderungstypen

Das CDK Toolkit sendet Anfragen, wenn es eine Eingabe oder Bestätigung vom Benutzer benötigt. Dies sind spezielle Nachrichten, die eine Antwort ermöglichen. Wenn keine Antwort erfolgt, verwendet das Toolkit eine Standardantwort, sofern verfügbar.

Grundlegende IIoHost-Implementierung

Hier ist ein einfaches Beispiel für die Implementierung eines benutzerdefinierten IO-Hosts:

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

Das CDK Toolkit wartet auf den Abschluss jedes Aufrufs, sodass Sie bei der Bearbeitung von Nachrichten asynchrone Operationen wie HTTP-Anfragen oder Benutzeraufforderungen ausführen können.

Standardverhalten IIoHost

Wenn Sie keinen benutzerdefinierten IO-Host bereitstellen, verwendet die CDK Toolkit Library eine standardmäßige, nicht interaktive Implementierung:

Dieses Standardverhalten eignet sich für unbeaufsichtigte Operationen, nicht jedoch für interaktive Befehlszeilenanwendungen. Für Befehlszeilenanwendungen, die eine Benutzerinteraktion erfordern, müssen Sie einen benutzerdefinierten IO-Host implementieren. Benutzerdefinierte Implementierungen eignen sich auch für die Integration in Protokollierungssysteme oder andere UIs spezialisierte Umgebungen.

Fortgeschrittene IO-Host-Implementierung

Für komplexere Szenarien empfehlen wir, den NonInteractiveIoHost Kurs als Ausgangspunkt zu erweitern. Dieser Ansatz ermöglicht es Ihnen, die bestehende, nicht interaktive Implementierung zu nutzen und gleichzeitig nur die spezifischen Verhaltensweisen anzupassen, die Sie ändern müssen.

Hier ist ein Beispiel für einen benutzerdefinierten IO-Host, der die Basisimplementierung erweitert:

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

Dieser Ansatz ist wartungsfreundlicher als die Implementierung der gesamten IIoHost Schnittstelle von Grund auf, da Sie nur die spezifischen Methoden überschreiben müssen, die ein benutzerdefiniertes Verhalten erfordern.

Integration in verschiedene Umgebungen

Integration von Webanwendungen

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

Integration der CI/CD-Umgebung

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

Bewährte Methoden für die Implementierung von IO-Hosts

Beachten Sie bei der Implementierung eines benutzerdefinierten IO-Hosts die folgenden bewährten Methoden:

Im folgenden Beispiel werden diese bewährten Methoden anhand der Implementierung eines benutzerdefinierten IO-Hosts mit Fehlerbehandlung, Timeouts für Benutzerinteraktionen und ordnungsgemäßer Protokollierung veranschaulicht. Diese Implementierung eignet sich für interaktive Anwendungen, bei denen Sie die Reaktionsfähigkeit der Benutzer mit einem zuverlässigen Betrieb in Einklang bringen müssen:

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

Fehlerbehebung

Überlegungen bei der Implementierung eines benutzerdefinierten IO-Hosts:

Das folgende Beispiel zeigt einen robusten Ansatz für den Umgang mit Nachrichtenebenen, einschließlich der ordnungsgemäßen Behandlung unbekannter Nachrichtentypen, die in future CDK-Versionen eingeführt werden könnten. Diese Implementierung stellt sicher, dass Ihr IO-Host mit CDK-Updates kompatibel bleibt und gleichzeitig die korrekte Protokollierung gewährleistet:

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