WebSocket API-Integrationsantworten in API Gateway einrichten

Übersicht über Integrationsantworten

Die Integrationsantwort von API Gateway ist eine Möglichkeit, die Antwort von einem Backend-Service zu modellieren und zu manipulieren. Es gibt einige Unterschiede bei der Einrichtung einer REST-API im Vergleich zu einer WebSocket API-Integrationsantwort, aber das Verhalten ist konzeptionell dasselbe.

WebSocket Routen können für bidirektionale oder unidirektionale Kommunikation konfiguriert werden.

• Wenn für eine Route bidirektionale Kommunikation konfiguriert ist, ermöglicht Ihnen eine Integrationsantwort, Transformationen für die zurückgegebene Nachrichtennutzlast zu konfigurieren, ähnlich wie Integrationsantworten für REST-APIs.

• Wenn eine Route für die unidirektionale Kommunikation konfiguriert ist, wird unabhängig von der Konfiguration der Integrationsantwort nach der Verarbeitung der Nachricht keine Antwort über den WebSocket Kanal zurückgegeben.

API Gateway übergibt die Backend-Antwort nicht über die Routenantwort, es sei denn, Sie richten eine Routenantwort ein. Weitere Informationen zum Einrichten einer Routenreaktion finden Sie unter Richten Sie Routenantworten für eine WebSocket API in API Gateway ein.

Integrationsantworten für bidirektionale Kommunikation

Integrationen lassen sich in Proxy-Integrationen und Nicht-Proxy-Integrationen unterteilen.

Wichtig

Bei Proxy-Integrationen gibt API Gateway automatisch die Backend-Ausgabe als vollständigen Payload an den Aufrufer weiter. Es gibt keine Integrationsantwort.

Bei Nicht-Proxy-Integrationen müssen Sie mindestens eine Integrationsantwort einrichten:

• Im Idealfall sollte eine Ihrer Integrationsantworten als Catch-all-Methode dienen, wenn keine explizite Wahl vorgenommen werden kann. Dieser Standardfall wird durch Festlegen des Integrationsantwort-Schlüssels dargestell $default.

• In allen anderen Fällen fungiert der Integrationsantwort-Schlüssel als regulärer Ausdruck. Er sollte dem Format folge "/expression/".

Bei Nicht-Proxy-HTTP-Integrationen:

• API Gateway versucht, den HTTP-Statuscode der Backend-Antwort zuzuordnen. Der Integrationsantwort-Schlüssel fungiert in diesem Fall als regulärer Ausdruck. Wenn keine Übereinstimmung gefunden wird, dann wird $default als Integrationsantwort gewählt.

• Der Vorlagen-Auswahlausdruck funktioniert wie oben beschrieben identisch. Zum Beispiel:

  • /2\d\d/: Erfolgreiche Antworten empfangen und transformieren

  • /4\d\d/: Fehler (ungültige Anforderung) empfangen und transformieren

  • $default: Alle unerwarteten Antworten empfangen und transformieren

Weitere Informationen zu Vorlagen-Auswahlausdrücken finden Sie unter Vorlagen-Auswahlausdrücke.

Integrationsantwort mit der API Gateway-Konsole einrichten

So richten Sie mithilfe der API-Gateway-Konsole eine Antwort zur Routenintegration für eine WebSocket API ein:

1. Melden Sie sich bei der API-Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wählen Sie Ihre WebSocket API und wählen Sie Ihre Route.

3. Wählen Sie die Registerkarte Integration request (Integrationsanforderung) und dann im Abschnitt Integration request settings (Einstellungen für Integrationsanforderungen) die Option Create integration response (Integrationsantwort erstellen) aus.

4. Geben Sie für Antwortschlüssel einen Wert ein, der nach Auswertung des Ausdrucks der Antwortauswahl im Antwortschlüssel der ausgehenden Nachricht zu finden ist. Sie können beispielsweise /4\d\d/ eingeben, um Anforderungsfehler zu empfangen und umzuwandeln, oder Sie können $default eingeben, um alle Antworten zu empfangen und umzuwandeln, die dem Ausdruck für die Vorlagenauswahl entsprechen.

5. Geben Sie unter Template selection expression (Ausdruck für die Vorlagenauswahl) einen Auswahlausdruck ein, um die ausgehende Nachricht auszuwerten.

6. Wählen Sie Create response (Antwort erstellen) aus.

7. Sie können auch eine Zuordnungsvorlage definieren, um Transformationen Ihrer Payload für zurückgegebene Nachrichten zu konfigurieren. Wählen Sie Create template (Vorlage erstellen) aus.

8. Geben Sie einen Schlüsselnamen ein. Wenn Sie den Standardausdruck für die Vorlagenauswahl auswählen, geben Sie \$default ein.

9. Geben Sie unter Response template (Antwortvorlage) Ihre Zuordnungsvorlage in den Code-Editor ein.

10. Wählen Sie Create template (Vorlage erstellen) aus.

11. Wählen Sie Deploy API (API bereitstellen) aus, um Ihre API bereitzustellen.

Stellen Sie mit dem folgenden wscat-Befehl eine Verbindung mit Ihrer API her. Mehr über wscat erfahren Sie unter Wird verwendetwscat, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden.

wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test

Wenn Sie Ihre Route aufrufen, sollte die Payload der zurückgegebenen Nachricht zurückgegeben werden.

Richten Sie eine Integrationsantwort mit dem ein AWS CLI

Um eine Integrationsantwort für eine WebSocket API einzurichten, AWS CLI rufen Sie den create-integration-responseBefehl auf. Der folgende CLI-Befehl zeigt ein Beispiel für das Erstellen einer $default-Integrationsantwort:

aws apigatewayv2 create-integration-response \
    --api-id vaz7da96z6 \
    --integration-id a1b2c3 \
    --integration-response-key '$default'