Erstellen Sie Routen für WebSocket APIs in Gateway API

In Ihrem WebSocket API werden eingehende JSON Nachrichten auf der Grundlage von Routen, die Sie konfigurieren, an Backend-Integrationen weitergeleitet. (Nachrichten, die keine JSON Nachrichten sind, 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 der API Ebene definiertes Attribut. Es gibt eine JSON Eigenschaft an, von der erwartet wird, dass sie in der Nachrichtennutzlast vorhanden ist. Weitere Informationen zu Routen-Auswahlausdrücken finden Sie unter Routen-Auswahlausdrücke.

Wenn Ihre JSON Nachrichten beispielsweise eine action Eigenschaft enthalten und Sie auf der Grundlage dieser Eigenschaft verschiedene Aktionen ausführen möchten, könnte Ihr Routenauswahlausdruck wie folgt lauten${request.body.action}. 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.

• APIGateway ruft die $connect Route auf, wenn eine dauerhafte Verbindung zwischen dem Client und einem initiiert WebSocket API wird.

• APIGateway ruft die $disconnect Route auf, wenn der Client oder der Server die Verbindung zum API trennt.

• APIGateway ruft eine benutzerdefinierte Route auf, nachdem der Routenauswahlausdruck anhand der Nachricht ausgewertet wurde, falls eine passende Route gefunden wurde. Die Übereinstimmung bestimmt, welche Integration aufgerufen wird.

• APIGateway ruft die $default Route auf, wenn der Routenauswahlausdruck nicht anhand der Nachricht ausgewertet werden kann oder wenn keine passende 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. Für WebSocket -based APIs sollte der Ausdruck die folgende Form haben$request.body.{path_to_body_element}.

Nehmen wir zum Beispiel an, Sie senden die folgende JSON Nachricht:

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

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

$request.body.action

request.bodyBezieht sich in diesem Beispiel auf die JSON Nutzlast Ihrer Nachricht und .action ist ein JSONPathAusdruck. Sie können danach einen beliebigen JSON Pfadausdruck verwendenrequest.body, aber denken Sie daran, dass das Ergebnis stringifiziert wird. Wenn Ihr JSONPath Ausdruck beispielsweise ein Array mit zwei Elementen zurückgibt, wird dieses als Zeichenfolge dargestellt. "[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 nicht gefunden JSONPath 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.

Richten Sie Routen für ein WebSocket API API In-Gateway ein

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

Anmerkung

In der können Sie Routen erstellenCLI, bevor oder nachdem Sie Integrationen erstellt haben, und Sie können dieselbe Integration für mehrere Routen wiederverwenden.

Erstellen Sie eine Route mit der API Gateway-Konsole

Um eine Route mit der API Gateway-Konsole zu erstellen

1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und anschließend Routes aus.

2. Wählen Sie Create route (Route erstellen) aus.

3. Geben Sie bei Route key (Routenschlüssel) den Schlüsselnamen ein. Sie können die vordefinierten Routen ($connect, $disconnect und $default) oder eine benutzerdefinierte Route erstellen.

   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.

4. Wählen und konfigurieren Sie den Integrationstyp für die Route. Weitere Informationen finden Sie unter Richten Sie mit der API Gateway-Konsole eine WebSocket API Integrationsanfrage ein.

Erstellen Sie eine Route mit dem AWS CLI

Um eine Route mit dem zu erstellen AWS CLI, rufen Sie create-routewie im folgenden Beispiel gezeigt 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 einrichtenAPI, sind die folgenden optionalen Einstellungen verfügbar, um die Autorisierung für Ihre zu aktivierenAPI. 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_IAMum AWS IAM Standardrichtlinien zu verwenden, um den Zugriff auf Ihre zu kontrollierenAPI.

  • CUSTOMum die Autorisierung für eine zu implementieren, API indem Sie eine Lambda-Autorisierungsfunktion angeben, die Sie zuvor erstellt haben. Der Autorisierer kann sich in Ihrem eigenen AWS Konto oder einem anderen Konto befinden. AWS Weitere Informationen über Lambda-Genehmiger finden Sie unter Verwenden Sie API Gateway Lambda-Autorisierer.

    Anmerkung

    In der API Gateway-Konsole ist die CUSTOM Einstellung erst sichtbar, nachdem Sie eine Autorisierungsfunktion eingerichtet haben, wie unter beschrieben. Konfigurieren Sie einen Lambda-Autorisierer (Konsole)

  Wichtig

  Die Autorisierungseinstellung wird auf die gesamte Route angewendetAPI, nicht nur auf die $connect Route. Die $connect-Route schützt die übrigen Routen, da sie für jede Verbindung aufgerufen wird.

• APIErforderlicher Schlüssel: Sie können optional einen API Schlüssel für die $connect Route eines API Benutzers anfordern. Sie können API Schlüssel zusammen mit Nutzungsplänen verwenden, um den Zugriff auf Ihre zu kontrollieren und zu verfolgenAPIs. Weitere Informationen finden Sie unter Nutzungspläne und API Schlüssel für REST APIs in API Gateway .

Richten Sie die $connect Routenanfrage über die API Gateway-Konsole ein

So richten Sie die $connect Routenanfrage für ein WebSocket API mithilfe der API Gateway-Konsole ein:

1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und anschließend Routes aus.

2. Wählen Sie unter Routes (Routen) $connect aus oder erstellen Sie eine $connect-Route, indem Sie wie folgt vorgehen Erstellen Sie eine Route mit der API Gateway-Konsole.

3. Wählen Sie im Abschnitt Route request settings (Einstellungen der Routenanforderung) die Option Edit (Bearbeiten) aus.

4. Wählen Sie für Authorization (Autorisierung) einen Autorisierungstyp aus.

5. Um eine API für die $connect Route anzufordern, wählen Sie APISchlüssel erforderlich aus.

6. Wählen Sie Änderungen speichern aus.