WebSocket-APIs in API Gateway im Überblick

In API Gateway können Sie eine WebSocket-API als zustandsbehaftetes Frontend für einen AWS-Service (wie AWS-Lambda oder DynamoDB) oder für einen HTTP-Endpunkt erstellen. Die WebSocket-API ruft Ihr Backend basierend auf dem Inhalt der Nachrichten auf, die sie von Client-Apps erhält.

Anders als eine REST-API, die Anforderungen empfängt und auf sie antwortet, unterstützt eine WebSocket-API eine bidirektionale Kommunikation zwischen Client-Apps und Ihrem Backend. Das Backend kann Rückruf-Nachrichten an verbundene Clients senden.

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.

Routen für eine WebSocket-API verwenden

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.

Weitere Informationen über die Routen $connect und $disconnect finden Sie unter Verwalten von verbundenen Benutzern und Client-Apps: $connect- und $disconnect-Routen.

Weitere Informationen über die Route $default und benutzerdefinierte Routen finden Sie unter Aufrufen Ihrer Backend-Integration mit der $default-Route und benutzerdefinierten Routen in API Gateway.

Daten an verbundene Client-Apps senden

Backend-Services können Daten an verbundene Client-Apps senden. Gehen Sie für eine Datenversendung wie folgt vor:

• Senden Sie eine Antwort mithilfe einer Integration. Diese wird über die von Ihnen definierte Routenantwort an den Client zurückgegeben.

• Sie können mithilfe der @connections-API eine POST-Anforderung senden. Weitere Informationen finden Sie unter Verwenden der @connections-Befehle in Ihrem Backend-Service.

Statuscodes für WebSocket-APIs

WebSocket-APIs in API Gateway verwenden die folgenden Statuscodes für die Kommunikation vom Server zum Client, wie im WebSocket Close Code Number Registry beschrieben:

1001

API Gateway gibt diesen Statuscode zurück, wenn der Client 10 Minuten inaktiv ist oder die maximale Verbindungsdauer von 2 Stunden erreicht.

1003

API Gateway gibt diesen Statuscode zurück, wenn ein Endpunkt einen binären Medientyp empfängt. Binäre Medientypen werden für WebSocket-APIs nicht unterstützt.

1005

API Gateway gibt diesen Statuscode zurück, wenn der Client ein Close-Frame ohne Abschlusscode sendet.

1006

API Gateway gibt diesen Statuscode zurück, wenn eine unerwartete Unterbrechung der Verbindung auftritt, z. B. wenn die TCP-Verbindung ohne WebSocket-Close-Frame beendet wird.

1008

API Gateway gibt diesen Statuscode zurück, wenn ein Endpunkt zu viele Anfragen von einem bestimmten Client erhält.

1009

API Gateway gibt diesen Statuscode zurück, wenn ein Endpunkt eine Nachricht empfängt, die zu groß ist, um verarbeitet zu werden.

1011

API Gateway gibt diesen Statuscode zurück, wenn ein interner Serverfehler auftritt.

1012

API Gateway gibt diesen Statuscode zurück, wenn der Service neu gestartet wird.