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. Im Gegensatz zum Anforderungs-/Antwortmodell von HTTP kann WebSocket im Backend Nachrichten an den Client senden, ohne dass der Client Maßnahmen ergreift.

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 weitergeleitet werden, um einen bestimmten Backend-Service basierend auf dem Nachrichteninhalt 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 Routenanforderung für eine WebSocket API in der API Gateway-Konsole, mithilfe der AWS CLI oder mithilfe eines SDK einrichten AWS .

Anmerkung

In den AWS CLI und AWS SDKs können Sie Routen vor oder nach dem Erstellen von Integrationen 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 API Gateway die Anforderung fehl, ohne Ihr Backend aufzurufen, sendet 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 Informationen zu WebSocket APIs in API Gateway.)

Angenommen, Sie möchten eine Chat-Raum-Anwendung erstellen. Sie können damit beginnen, eine WebSocket API zu erstellen, deren Routenauswahlausdruck lautet$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 verwenden, um eine Verbindung zu Ihrer Geschäftslogik herzustellen

Nachdem Sie eine Route für eine 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 ähneln Integrationen für REST-APIs, 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.

  In den AWS CLI und AWS SDKs können Sie eine Integration wiederverwenden, indem Sie das Ziel der Route auf einen Wert von setzen"integrations/{integration-id}", wobei die eindeutige ID der Integration {integration-id}" ist, die der Route zugeordnet werden soll.

• 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> sowie statische Werte.

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.