Aufrufen Ihrer Backend-Integration: $default-Route und benutzerdefinierte Routen

Verwenden von Routen zur Verarbeitung von Nachrichten

In API Gateway-WebSocket-APIs können Nachrichten vom Client an Ihren Backend-Service und umgekehrt gesendet werden. Anders als im HTTP-Anforderungs-/Antwort-Modell kann das Backend in WebSocket Nachrichten an den Client senden, ohne dass der Client weiter reagieren muss.

Es kann sich dabei um JSON- oder Nicht-JSON-Nachrichten handeln. Es können jedoch nur JSON-Nachrichten basierend auf dem Nachrichteninhalt an bestimmte Integrationen weitergeleitet werden. Nicht-JSON-Nachrichten werden über die $default-Route an das Backend übergeben.

Anmerkung

API Gateway unterstützt Nachrichten-Payloads bis zu 128 KB mit einer maximalen Frame-Größe von 32 KB. Sie müssen Nachrichten, die 32 KB überschreiten, in mehrere Frames aufteilen, die jeweils 32 KB oder kleiner sind. Wenn eine größere Nachricht (oder ein größerer Frame) empfangen wird, wird die Verbindung mit dem Code 1009 geschlossen.

Derzeit werden keine binären Nutzlasten unterstützt. Wenn ein binärer Frame empfangen wird, wird die Verbindung mit dem Code 1003 geschlossen. Es ist jedoch möglich, binäre Nutzlasten in Text zu konvertieren. Siehe Mit binären Medientypen für WebSocket-APIs arbeiten.

Mit WebSocket-APIs in API Gateway können JSON-Nachrichten geroutet werden, um einen bestimmten Backend-Service auf der Grundlage des Nachrichteninhalts auszuführen. Wenn ein Client eine Nachricht über seine WebSocket-Verbindung sendet, führt dies zu einer Routenanforderung an die WebSocket-API. Die Anfrage wird der Route mit dem entsprechenden Routenschlüssel in API Gateway zugeordnet. Sie können eine Routenanfrage für eine WebSocket-API in der API-Gateway-Konsole, mit der AWS CLI oder mit einem AWS SDK einrichten.

Anmerkung

In der AWS CLI und den AWS SDKs können Sie vor oder nach dem Erstellen von Integrationen Routen erstellen. Derzeit unterstützt die Konsole keine Wiederverwendung von Integrationen. Daher müssen Sie zuerst die Route erstellen und dann die Integration für diese Route.

Sie können API Gateway so konfigurieren, dass die Validierung einer Routenanforderung durchgeführt wird, bevor Sie mit der Integrationsanforderung fortfahren. Wenn die Validierung fehlschlägt, schlägt die Anfrage bei API Gateway fehl. Ohne Ihr Backend aufzurufen sendet API Gateway eine "Bad request body"-Gateway-Antwort ähnlich der folgenden an den Client und veröffentlicht die Validierungsergebnisse in CloudWatch Logs:

{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}

Damit werden unnötige Aufrufe Ihres Backend reduziert, sodass Sie sich auf andere Voraussetzungen für Ihre API konzentrieren können.

Darüber hinaus können Sie eine Routenantwort für die Routen Ihrer API vorgeben, um eine bidirektionale Kommunikation zu ermöglichen. Eine Routenantwort beschreibt, welche Daten bei Abschluss der Integration einer bestimmten Route an Ihren Client gesendet werden. Es ist nicht notwendig, eine Antwort für eine Route vorzugeben, wenn ein Client Nachrichten an Ihr Backend senden soll, ohne eine Antwort zu erhalten (unidirektionale Kommunikation). Wenn Sie keine Routenantwort bereitstellen, sendet API Gateway jedoch keine Informationen über das Ergebnis Ihrer Integration an Ihre Kunden.

Die Route $default

Jede API Gateway-WebSocket-API kann eine $default-Route haben. Hierbei handelt es sich um einen speziellen Routing-Wert, der auf folgende Weise eingesetzt werden kann:

• Sie können ihn zusammen mit vorgegebenen Routenschlüsseln verwenden, um für eingehende Nachrichten, auf die keine der vorgegebenen Routenschlüssel zutreffen, eine "Fallback"-Route anzugeben (z. B. eine generische Pseudo-Integration, die eine bestimmte Fehlermeldung zurückgibt).

• Sie können ihn ohne vorgegebene Routenschlüssel verwenden, um ein Proxy-Modell anzugeben, durch das Routing an eine Backend-Komponente delegiert wird.

• Sie können mit ihm eine Route für Nicht-JSON-Nutzlasten angeben.

Benutzerdefinierte Routen

Wenn basierend auf dem Nachrichteninhalt eine bestimmte Integration aufgerufen werden soll, können Sie hierzu eine benutzerdefinierte Route erstellen.

Für eine benutzerdefinierte Route werden ein Routenschlüssel und eine Integration nach Ihren Angaben verwendet. Wenn eine eingehende Nachricht eine JSON-Eigenschaft enthält und diese Eigenschaft mit einem Wert ausgewertet wird, der mit dem Routenschlüsselwert übereinstimmt, ruft API Gateway die Integration auf. (Weitere Informationen finden Sie unter Mehr zu WebSocket-APIs in API Gateway.)

Angenommen, Sie möchten eine Chat-Raum-Anwendung erstellen. Sie könnten mit dem Erstellen einer WebSocket-API mit einem Routen-Auswahlausdruck von beginne $request.body.action. Anschließend könnten Sie zwei Routen definieren: joinroom und sendmessage. Ein Client-App könnte die joinroom-Route durch Senden einer Nachricht wie die folgende aufrufen:

{"action":"joinroom","roomname":"developers"}

Und sie könnte die sendmessage-Route durch Senden einer Nachricht wie die folgende aufrufen:

{"action":"sendmessage","message":"Hello everyone"}

API Gateway-WebSocket-API-Integrationen zur Verbindung mit Ihrer Geschäftslogik verwenden

Nachdem Sie eine Route für ein API Gateway-WebSocket-API eingerichtet haben, müssen Sie die Integration angeben, die Sie verwenden möchten. Genauso wie eine Route über eine Routenanforderung und eine Routenantwort verfügen kann, kann eine Integration eine Integrationsanforderung und eine Integrationsantwort besitzen. Eine Integrationsanforderung enthält die Informationen, die von Ihrem Backend zur Verarbeitung der von Ihrem Client stammenden Anforderung erwartet werden. Die Integrationsantwort enthält die Daten, die Ihr Backend an API Gateway zurücksendet. Sie kann verwendet werden, um eine an den Client zu sendende Nachricht zu verfassen (falls eine Routenantwort definiert ist).

Weitere Informationen zum Einrichten von Integrationen finden Sie unter Einrichten von WebSocket-API-Integrationen.

Wichtige Unterschiede zwischen WebSocket-APIs und REST-APIs

Integrationen für WebSocket-APIs sind mit Integrationen für REST-APIs vergleichbar, mit Ausnahme der folgenden Unterschiede:

• Derzeit müssen Sie in der API Gateway-Konsole zuerst eine Route und dann eine Integration als Ziel dieser Route erstellen. In der API und der CLI können Sie Routen und Integrationen jedoch unabhängig voneinander in beliebiger Reihenfolge erstellen.

• Sie können eine einzelne Integration für mehrere Routen verwenden. Für eine Gruppe von Aktionen, die eng miteinander in Beziehung stehen, empfiehlt es sich beispielsweise, dass alle diese Routen zu einer einzelnen Lambda-Funktion führen. Anstatt die Details der Integration mehrmals zu definieren, können Sie sie einmal angeben und jeder verwandten Route zuweisen.

  Anmerkung

  Derzeit unterstützt die Konsole keine Wiederverwendung von Integrationen. Daher müssen Sie zuerst die Route erstellen und dann die Integration für diese Route.

  Sie können eine Integration in der AWS CLI und den AWS SDKs wiederverwenden, indem Sie als Ziel der Route einen Wert von "integrations/{integration-id}" festlegen, wobei {integration-id}" die eindeutige ID der Integration ist, die mit der Route verknüpft ist.

• API Gateway bietet mehrere Auswahlausdrücke, die Sie in Ihren Routen und Integrationen verwenden können. Sie müssen die Auswahl einer Eingabevorlage oder einer Ausgabezuordnung nicht vom Inhaltstyp abhängig machen. Wie bei Routenauswahlausdrücken können Sie einen Auswahlausdruck definieren, der von API Gateway ausgewertet wird, um das richtige Element auszuwählen. Alle von ihnen übernehmen automatisch die $default-Vorlage, wenn keine passende Vorlage gefunden wird.

  • In Integrationsanforderungen unterstützt der Vorlagen-Auswahlausdruck $request.body.<json_path_expression> und statische Werte.

  • In Integrationsantworten unterstützt der Vorlagen-Auswahlausdruck $request.body.<json_path_expression>, $integration.response.statuscode und $integration.response.header.<headerName>.

Im HTTP-Protokoll, in dem Anforderungen und Antworten synchron gesendet werden, ist die Kommunikation im Wesentlichen unidirektional. Im WebSocket-Protokoll ist die Kommunikation bidirektional. Antworten sind asynchron und werden vom Client nicht unbedingt in der gleichen Reihenfolge empfangen, in der die Client-Nachrichten gesendet wurden. Darüber hinaus kann das Backend Nachrichten an den Client senden.

Anmerkung

Für eine Route, die zur Verwendung der Integration AWS_PROXY oder LAMBDA_PROXY konfiguriert wurde, ist die Kommunikation unidirektional. API Gateway übergibt die Backend-Antwort nicht automatisch über die Routenantwort. Wenn bei der LAMBDA_PROXY-Integration wird der von der Lambda-Funktion zurückgegebene Text beispielsweise nicht an den Client zurückgegeben. Wenn Sie möchten, dass der Client Integrationsantworten erhält, müssen Sie eine Routenantwort definieren, um eine bidirektionale Kommunikation zu ermöglichen.