Arbeiten mit Routen für WebSocket-APIs

In Ihrer WebSocket-API werden eingehende JSON-Nachrichten basierend auf von Ihnen definierten Routen an Backend-Integrationen weitergeleitet. (Nicht-JSON-Nachrichten werden an eine von Ihnen konfigurierte $default-Route weitergeleitet.)

Eine Route umfasst einen Routenschlüssel. Dabei handelt es sich um den Wert, der bei der Auswertung eines Routen-Auswahlausdrucks erwartet wird. Das routeSelectionExpression ist ein auf API-Ebene definiertes Attribut. Es gibt eine JSON-Eigenschaft an, von der erwartet wird, dass sie in der Nachricht-Nutzlast vorhanden ist. Weitere Informationen zu Routen-Auswahlausdrücken finden Sie unter Routen-Auswahlausdrücke.

Beispiel: Wenn Ihre JSON-Nachrichten eine action-Eigenschaft enthalten und Sie basierend auf dieser Eigenschaft verschiedene Aktionen durchführen möchten, könnte Ihr Routen-Auswahlausdruck ${request.body.action} lauten. Ihre Routing-Tabelle würde in diesem Fall angeben, welche Aktion ausgeführt werden soll, indem der Wert der action-Eigenschaft gegen die benutzerdefinierten Routenschlüssel-Werte abgeglichen wird, die Sie in der Tabelle definiert haben.

Es gibt drei vordefinierte Routen, die verwendet werden können: $connect, $disconnect und $default. Darüber hinaus können Sie benutzerdefinierte Routen erstellen.

API Gateway ruft die $connect-Route auf, wenn eine permanente Verbindung zwischen dem Client und einer WebSocket-API initiiert wird.
API Gateway ruft die $disconnect-Route auf, wenn der Client oder der Server die Verbindung mit der API unterbricht.
API Gateway ruft eine benutzerdefinierte Route auf, wenn nach der Auswertung des Routen-Auswahlausdrucks im Hinblick auf die Nachricht eine übereinstimmende Route gefunden wird. Die Übereinstimmung bestimmt, welche Integration aufgerufen wird.
API Gateway ruft die Route $default auf, wenn der Routen-Auswahlausdruck nicht im Hinblick auf die Nachricht ausgewertet werden kann oder wenn keine übereinstimmende Route gefunden wird.

Routen-Auswahlausdrücke

Ein Routen-Auswahlausdruck wird ausgewertet, wenn der Service die Route auswählt, der eine eingehende Nachricht folgen soll. Der Service verwendet die Route, deren routeKey genau dem ausgewerteten Wert entspricht. Wenn bei fehlender Übereinstimmung eine Route mit dem Routenschlüssel $default vorhanden ist, wird diese Route ausgewählt. Wenn keine Routen dem ausgewählten Wert entsprechen und keine $default-Route vorhanden ist, gibt der Service einen Fehler zurück. Bei WebSocket-basierten APIs sollte der Ausdruck das Format aufweise $request.body.{path_to_body_element}.

Angenommen, Sie senden die folgende JSON-Nachricht:


{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

Möglicherweise möchten Sie das Verhalten Ihrer API basierend auf der Eigenschaft action auswählen. In diesem Fall könnten Sie den folgenden Routen-Auswahlausdruck definieren:


$request.body.action

In diesem Beispiel bezieht sich request.body auf die JSON-Nutzlast Ihrer Nachricht und .action ist ein JSONPath-Ausdruck. Sie können nach request.body einen beliebigen JSON-Pfad-Ausdruck verwenden. Denken Sie aber daran, dass das Ergebnis in Text umgewandelt wird. Beispiel: Wenn Ihr JSONPath-Ausdruck ein Array mit zwei Elementen zurückgibt, werden sie als Zeichenfolge dargestell "[item1, item2]". Aus diesem Grund ist es sinnvoll, dass Ihr Ausdruck auf einen Wert und nicht auf ein Array oder Objekt ausgewertet wird.

Sie können einfach einen statischen Wert oder auch mehrere Variablen verwenden. In der folgenden Tabelle werden Beispiele und deren im Hinblick auf die vorhergehende Nutzlast ausgewerteten Ergebnisse gezeigt.

Ausdruck	Ausgewertetes Ergebnis	Beschreibung
`$request.body.action`	`join`	Eine entpackte Variable
`${request.body.action}`	`join`	Eine verpackte Variable
`${request.body.service}/${request.body.action}`	`chat`/`join`	Mehrere Variablen mit statischen Werten
`${request.body.action}-${request.body.invalidPath}`	`join-`	Wenn der JSONPath nicht gefunden wird, wird die Variable als "" aufgelöst.
`action`	`action`	Statischer Wert
`\$default`	`$default`	Statischer Wert

Das ausgewertete Ergebnis wird zum Auffinden der Route verwendet. Wenn eine Route mit einem übereinstimmenden Routenschlüssel vorhanden ist, wird die Route zur Verarbeitung der Nachricht ausgewählt. Wenn keine passende Route gefunden wird, versucht API Gateway, die $default-Route zu finden, falls verfügbar. Wenn die $default-Route nicht definiert ist, gibt API Gateway einen Fehler zurück.

Routen für eine WebSocket-API in API Gateway einrichten

Wenn Sie zum ersten Mal eine neue WebSocket-API erstellen, gibt es drei vordefinierte Routen: $connect, $disconnect und $default. Sie können sie mithilfe der Konsole, der API oder der erstelle AWS CLI. Auf Wunsch können Sie benutzerdefinierte Routen erstellen. Weitere Informationen finden Sie unter Mehr zu WebSocket-APIs in API Gateway.

Anmerkung

In der CLI ist es möglich, Routen vor oder nach dem Erstellen von Integrationen zu erstellen. Auch können Sie dieselbe Integration für mehrere Routen wiederverwenden.

Route mit der API Gateway-Konsole erstellen

So erstellen Sie eine Route über die API Gateway-Konsole:

Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie Routes (Routen).
Um eine der vordefinierten Routen ($connect, $disconnect und $default) zu erstellen, wählen Sie den betreffenden Namen aus.
Auf Wunsch können Sie benutzerdefinierte Routen erstellen. Geben Sie hierzu den Namen des Routenschlüssels in das Textfeld New Route Key (Neuer Routenschlüssel) ein. Wählen Sie das dann Häkchen-Symbol aus.

Anmerkung
Wenn Sie eine benutzerdefinierte Route erstellen, verwenden Sie nicht das $-Präfix im Routenschlüsselnamen. Dieses Präfix ist für vordefinierte Routen reserviert.

Erstellen einer Route mithilfe der AWS CLI

Um mit dem AWS CLI-Aufruf eine Route zu erstellen, rufen Sie wie im folgenden Beispiel den Befehl create-route auf:


aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

Beispielausgabe:


{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

Angeben der Routenanforderungs-Einstellungen für `$connect`

Wenn Sie die $connect-Route für Ihre API einrichten, sind die folgenden optionalen Einstellungen verfügbar, um die Autorisierung für Ihre API zu ermöglichen. Weitere Informationen finden Sie unter Die Route $connect.

Authorization (Autorisierung): Wenn keine Autorisierung erforderlich ist, können Sie NONE angeben. Geben Sie andernfalls Folgendes ein:
- AWS_IAM, um AWS-IAM-Standardrichtlinien zur Kontrolle des Zugriffs auf Ihre API zu verwenden.
- CUSTOM, um die Autorisierung für eine API durch Angabe einer zuvor von Ihnen erstellten Lambda-Genehmigerfunktion zu implementieren. Der Genehmiger kann zu Ihrem AWS-Konto oder zu einem anderen AWS-Konto gehören. Weitere Informationen über Lambda-Genehmiger finden Sie unter API Gateway-Lambda-Genehmiger verwenden.
  
  Anmerkung
  In der API Gateway-Konsole ist die Einstellung CUSTOM erst sichtbar, nachdem Sie eine Genehmigerfunktion wie unter Lambda-Genehmiger über die API Gateway-Konsole konfigurieren beschrieben eingerichtet haben.
Wichtig
Die Einstellung von Authorization (Autorisierung) wird auf die gesamte API angewendet, nicht nur auf die $connect-Route. Die $connect-Route schützt die übrigen Routen, da sie für jede Verbindung aufgerufen wird.
API Key Required (API-Schlüssel erforderlich): Sie können für die $connect-Route einer API optional einen API-Schlüssel verlangen. Sie können API-Schlüssel zusammen mit Nutzungsplänen zur Kontrolle und Nachverfolgung des Zugriffs auf Ihre APIs einsetzen. Weitere Informationen finden Sie unter Erstellen und Verwenden von Nutzungsplänen mit API-Schlüsseln.

`$connect`-Routenanforderung über die API Gateway-Konsole einrichten

So richten Sie die $connect-Routenanforderung für eine WebSocket-API über die API Gateway-Konsole ein:

Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie Routes (Routen).
Wählen Sie unter Routes (Routen) die Option $connect aus.
Wählen Sie im Routenübersichtsbereich Route Request (Routenanforderung) aus.
Konfigurieren Sie unter Access Settings (Zugriffseinstellungen) folgendermaßen die Routeneinstellungen:
1. Wählen Sie zur Bearbeitung der Einstellung Authorization (Autorisierung) das Stiftsymbol. Wählen Sie die gewünschte Einstellung aus dem Dropdown-Menü aus und wählen Sie das Häkchensymbol, um die neue Einstellung zu speichern.
2. Um die Einstellung API Key Required (API-Schlüssel erforderlich) zu bearbeiten, wählen Sie das Stiftsymbol. Wählen Sie true oder false aus dem Dropdown-Menü aus. Wählen Sie dann das Häkchen-Symbol, um die neue Einstellung zu speichern.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Erstellen und Konfigurieren

Einrichten von WebSocket-API-Routenantworten