Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Routen für WebSocket APIs im API Gateway erstellen In Ihrer WebSocket API werden eingehende JSON-Nachrichten auf der Grundlage von Routen, die Sie konfigurieren, 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](#apigateway-websocket-api-route-selection-expressions). 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 persistente 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. Für WebSocket -based APIs sollte der Ausdruck die folgende Form haben`$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 ``` `request.body`Bezieht sich in diesem Beispiel auf die JSON-Nutzlast Ihrer Nachricht und `.action` ist ein [JSONPath](https://goessner.net/articles/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. Wenn Ihr JSONPath Ausdruck beispielsweise ein Array mit zwei Elementen zurückgibt, wird dieses als Zeichenfolge `"[item1, item2]"` dargestellt. 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 | | --- | --- | --- | | \$1request.body.action | join | Eine entpackte Variable | | \$1\$1request.body.action\$1 | join | Eine verpackte Variable | | \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Mehrere Variablen mit statischen Werten | | \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Wenn der nicht gefunden JSONPath wird, wird die Variable als „“ aufgelöst. | | action | action | Statischer Wert | | \$1\$1default | \$1default | 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 erstellen AWS CLI. Auf Wunsch können Sie benutzerdefinierte Routen erstellen. Weitere Informationen finden Sie unter [Überblick über WebSocket APIs in API Gateway](apigateway-websocket-api-overview.md). **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:** 1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie **Routes (Routen)**. 1. Wählen Sie **Create route** (Route erstellen) aus. 1. 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. 1. Wählen und konfigurieren Sie den Integrationstyp für die Route. Weitere Informationen finden Sie unter [Richten Sie mit der WebSocket API Gateway-Konsole eine API-Integrationsanfrage ein](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console). ### Erstellen Sie eine Route mit dem AWS CLI Der folgende [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html)-Befehl erstellt eine Route: ``` aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default ``` Die Ausgabe sieht wie folgt aus: ``` { "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`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect). + **Authorization (Autorisierung)**: Wenn keine Autorisierung erforderlich ist, können Sie `NONE` angeben. Geben Sie andernfalls Folgendes ein: + `AWS_IAM`um den Zugriff auf Ihre API mithilfe von AWS Standard-IAM-Richtlinien zu kontrollieren. + `CUSTOM`, um die Autorisierung für eine API durch Angabe einer zuvor von Ihnen erstellten Lambda-Genehmigerfunktion zu implementieren. Der Autorisierer kann sich in Ihrem eigenen AWS Konto oder einem anderen Konto befinden. AWS Weitere Informationen über Lambda-Genehmiger finden Sie unter [API Gateway-Lambda-Genehmiger verwenden](apigateway-use-lambda-authorizer.md). **Anmerkung** In der API Gateway-Konsole ist die Einstellung `CUSTOM` erst sichtbar, nachdem Sie eine Genehmigerfunktion wie unter [Lambda-Genehmiger konfigurieren (Konsole)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console) 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-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 verwenden, um den Zugriff auf Ihre zu kontrollieren und zu verfolgen. APIs Weitere Informationen finden Sie unter [Nutzungspläne und API-Schlüssel für REST APIs in API Gateway](api-gateway-api-usage-plans.md). ### `$connect`-Routenanforderung über die API Gateway-Konsole einrichten So richten Sie die `$connect` Routenanforderung für eine WebSocket API mithilfe der API-Gateway-Konsole ein: 1. Melden Sie sich bei der API Gateway-Konsole an, wählen Sie die API und wählen Sie **Routes (Routen)**. 1. Wählen Sie unter **Routes** (Routen) `$connect` aus oder erstellen Sie eine `$connect`-Route, indem Sie wie folgt vorgehen [Route mit der API Gateway-Konsole erstellen](#apigateway-websocket-api-route-using-console). 1. Wählen Sie im Abschnitt **Route request settings** (Einstellungen der Routenanforderung) die Option **Edit** (Bearbeiten) aus. 1. Wählen Sie für **Authorization** (Autorisierung) einen Autorisierungstyp aus. 1. Um eine API für die `$connect`-Route anzufordern, wählen Sie **Require API key** (API-Schlüssel erforderlich) aus. 1. Wählen Sie **Änderungen speichern ** aus. # Richten Sie Routenantworten für WebSocket APIs in API Gateway ein WebSocket Routen können für bidirektionale oder unidirektionale Kommunikation konfiguriert werden. API-Gateway übergibt die Backend-Antwort nicht über die Routenantwort, es sei denn, Sie haben eine Routenantwort eingerichtet. **Anmerkung** Sie können nur die `$default` Routenantwort für definieren. WebSocket APIs Sie können eine Integrationsantwort verwenden, um die Antwort von einem Backend-Service zu manipulieren. Weitere Informationen finden Sie unter [Übersicht über Integrationsantworten](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview). Sie können Routenantworten und Antwortauswahlausdrücke mithilfe der API Gateway Gateway-Konsole oder des AWS CLI oder eines AWS SDK konfigurieren. Weitere Informationen über Routenantwort-Auswahlausdrücke finden Sie unter [Routenantwort-Auswahlausdrücke](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions). **Topics** + [ ## Routenantwort mit der API Gateway-Konsole einrichten ](#apigateway-websocket-api-route-response-using-console) + [ ## Richten Sie eine Routenantwort ein, indem Sie AWS CLI ](#apigateway-websocket-api-route-response-using-awscli) ## Routenantwort mit der API Gateway-Konsole einrichten Nachdem Sie eine WebSocket API erstellt und eine Proxy-Lambda-Funktion an die Standardroute angehängt haben, können Sie die Routenantwort mit der API Gateway Gateway-Konsole einrichten: 1. Melden Sie sich bei der API Gateway Gateway-Konsole an und wählen Sie eine WebSocket API mit einer Proxy-Lambda-Funktionsintegration auf der `$default` Route aus. 1. Wählen Sie unter **Routes** (Routen) die `$default`-Route aus. 1. Wählen Sie **Enable two-way communication** (Bidirektionale Kommunikation aktivieren). 1. Klicken Sie auf **Deploy API**. 1. Stellen Sie Ihre API für eine Stufe bereit. Stellen Sie mit dem folgenden [wscat](https://www.npmjs.com/package/wscat)-Befehl eine Verbindung mit Ihrer API her. Mehr über `wscat` erfahren Sie unter [Wird verwendet`wscat`, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden](apigateway-how-to-call-websocket-api-wscat.md). ``` wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test ``` Drücken Sie die Eingabetaste, um die Standardroute aufzurufen. Der Hauptteil Ihrer Lambda-Funktion sollte zurückgegeben werden. ## Richten Sie eine Routenantwort ein, indem Sie AWS CLI Der folgende [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)Befehl erstellt eine Routenantwort für die `$default` Route. Sie können die API-ID und Routing-ID identifizieren, indem Sie die Befehle [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) und [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html) verwenden. ``` aws apigatewayv2 create-route-response \ --api-id aabbccddee \ --route-id 1122334 \ --route-response-key '$default' ``` Die Ausgabe sieht wie folgt aus: ``` { "RouteResponseId": "abcdef", "RouteResponseKey": "$default" } ``` # Richten Sie eine `$connect` Route ein, für die ein WebSocket Unterprotokoll erforderlich ist Clients können das `Sec-WebSocket-Protocol` Feld verwenden, um während der Verbindung zu Ihrer WebSocket API ein [WebSocket Unterprotokoll](https://datatracker.ietf.org/doc/html/rfc6455#page-12) anzufordern. Sie können eine Integration für die `$connect`-Route einrichten, um Verbindungen nur zuzulassen, wenn ein Client ein von Ihrer API unterstütztes Unterprotokoll anfordert. Die folgende Lambda-Beispielfunktion gibt den `Sec-WebSocket-Protocol`-Header an Clients zurück. Die Funktion stellt nur dann eine Verbindung zu Ihrer API her, wenn der Client das `myprotocol`-Unterprotokoll angibt. Eine CloudFormation Vorlage, die diese Beispiel-API- und Lambda-Proxyintegration erstellt, finden Sie unter [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip). ``` export const handler = async (event) => { if (event.headers != undefined) { const headers = toLowerCaseProperties(event.headers); if (headers['sec-websocket-protocol'] != undefined) { const subprotocolHeader = headers['sec-websocket-protocol']; const subprotocols = subprotocolHeader.split(','); if (subprotocols.indexOf('myprotocol') >= 0) { const response = { statusCode: 200, headers: { "Sec-WebSocket-Protocol" : "myprotocol" } }; return response; } } } const response = { statusCode: 400 }; return response; }; function toLowerCaseProperties(obj) { var wrapper = {}; for (var key in obj) { wrapper[key.toLowerCase()] = obj[key]; } return wrapper; } ``` Sie können [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) verwenden, um zu testen, ob Ihre API Verbindungen nur zulässt, wenn ein Client ein von Ihrer API unterstütztes Unterprotokoll anfordert. Die folgenden Befehle verwenden das `-s`-Flag, um während der Verbindung Unterprotokolle anzugeben. Mit dem folgenden Befehl wird versucht, eine Verbindung mit einem nicht unterstützten Unterprotokoll herzustellen. Da der Client das `chat1`-Unterprotokoll angegeben hat, gibt die Lambda-Integration einen 400-Fehler zurück und die Verbindung ist nicht erfolgreich. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1 error: Unexpected server response: 400 ``` Der folgende Befehl enthält ein unterstütztes Unterprotokoll in der Verbindungsanforderung. Die Lambda-Integration ermöglicht die Verbindung. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol connected (press CTRL+C to quit) ``` Weitere Informationen zum Aufrufen WebSocket APIs finden Sie unter. [Aufrufen WebSocket APIs](apigateway-how-to-call-websocket-api.md)