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.
Tutorial: Erstellen Sie eine WebSocket API mit einer AWS Integration
In diesem Tutorial erstellen Sie eine serverlose Broadcast-Anwendung mit einem. WebSocket API Kunden können Nachrichten erhalten, ohne Updates abfragen zu müssen.
Dieses Tutorial zeigt, wie Nachrichten an verbundene Clients gesendet werden, und enthält ein Beispiel für einen Lambda-Authorizer, eine Scheinintegration und eine Nicht-Proxy-Integration in Step Functions.
Nachdem Sie Ihre Ressourcen mithilfe einer AWS CloudFormation Vorlage erstellt haben, verwenden Sie die API Gateway-Konsole, um eine zu erstellen WebSocket API, die sich in Ihre AWS Ressourcen integrieren lässt. Sie fügen Ihrem einen Lambda-Autorisierer hinzu API und erstellen eine AWS Serviceintegration mit Step Functions, um eine State-Machine-Ausführung zu starten. Die Step Functions Functions-Zustandsmaschine ruft eine Lambda-Funktion auf, die eine Nachricht an alle verbundenen Clients sendet.
Nachdem Sie Ihre eingerichtet habenAPI, testen Sie Ihre Verbindung zu Ihrem API und stellen sicher, dass Nachrichten gesendet und empfangen werden. Die Fertigstellung dieses Tutorials dauert ungefähr 45 Minuten.
Themen
- Voraussetzungen
- Schritt 1: Erstellen von Ressourcen
- Schritt 2: Erstellen Sie ein WebSocket API
- Schritt 3: Erstellen Sie einen Lambda-Autorisierer
- Schritt 4: Erstellen Sie eine simulierte bidirektionale Integration
- Schritt 5: Erstellen Sie eine Nicht-Proxy-Integration mit Step Functions
- Schritt 6: Testen Sie Ihre API
- Schritt 7: Bereinigen
- Nächste Schritte
Voraussetzungen
Sie benötigen die folgenden Voraussetzungen:
-
Ein AWS Konto und ein AWS Identity and Access Management Benutzer mit Konsolenzugriff. Weitere Informationen finden Sie unter Für die Verwendung von API Gateway einrichten.
-
wscat
um eine Verbindung zu Ihrem herzustellenAPI. Weitere Informationen finden Sie unter Wird verwendetwscat, um eine Verbindung zu einer WebSocket API herzustellen und Nachrichten an diese zu senden.
Wir empfehlen Ihnen, das WebSocket Chat-App-Tutorial abzuschließen, bevor Sie mit diesem Tutorial beginnen. Informationen zum Ausfüllen des WebSocket Chat-App-Tutorials finden Sie unterTutorial: Erstellen Sie eine WebSocket Chat-App mit a WebSocket API, Lambda und DynamoDB.
Schritt 1: Erstellen von Ressourcen
Laden Sie die Vorlage zur App-Erstellung für AWS CloudFormation herunter und entpacken Sie sie. Sie werden diese Vorlage verwenden, um Folgendes zu erstellen:
Lambda-Funktionen, die API Anfragen bearbeiten und den Zugriff auf Ihre autorisieren. API
Eine DynamoDB-Tabelle zum Speichern der Client IDs - und Hauptbenutzeridentifikation, die vom Lambda-Autorisierer zurückgegeben wurde.
Eine Step Functions Functions-Zustandsmaschine zum Senden von Nachrichten an verbundene Clients.
Um einen AWS CloudFormation Stapel zu erstellen
Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation
. -
Wählen Sie Stack erstellen und dann Mit neuen Ressourcen (Standard) aus.
-
Wählen Sie unter Vorlage angeben die Option Vorlagendatei hochladen aus.
-
Wählen Sie die Vorlage aus, die Sie heruntergeladen haben.
-
Wählen Sie Weiter aus.
-
Geben Sie für Stack-Name die Zeichenfolge
websocket-step-functions-tutorial
ein und klicken Sie auf Weiter. -
Wählen Sie in Stack-Optionen konfigurieren die Option Weiter aus.
-
Bestätigen Sie bei Funktionen, dass IAM Ressourcen in Ihrem Konto erstellt werden AWS CloudFormation können.
-
Wählen Sie Absenden aus.
AWS CloudFormation stellt die in der Vorlage angegebenen Ressourcen bereit. Die Bereitstellung der Ressourcen kann einige Minuten dauern. Wählen Sie die Registerkarte Ausgaben, um Ihre erstellten Ressourcen und deren Eigenschaften zu sehenARNs. Wenn der Status Ihres AWS CloudFormation Stacks CREATE_ istCOMPLETE, können Sie mit dem nächsten Schritt fortfahren.
Schritt 2: Erstellen Sie ein WebSocket API
Sie erstellen eine WebSocket API, um Client-Verbindungen zu verarbeiten und Anfragen an die Ressourcen weiterzuleiten, die Sie in Schritt 1 erstellt haben.
Um eine zu erstellen WebSocket API
Melden Sie sich unter https://console.aws.amazon.com/apigateway
bei der API Gateway-Konsole an. Wählen Sie Erstellen API. Wählen Sie WebSocket APIdann für Build.
Geben Sie als APINamen ein
websocket-step-functions-tutorial
.Geben Sie in Route selection expression (Ausdruck für die Routenauswahl)
request.body.action
ein.Der Routenauswahlausdruck bestimmt die Route, die API Gateway aufruft, wenn ein Client eine Nachricht sendet.
Wählen Sie Weiter aus.
Wählen Sie für vordefinierte Routen Add $connect, Add $disconnect, Add $default aus.
Die Routen $connect und $disconnect sind spezielle Routen, die API Gateway automatisch aufruft, wenn ein Client eine Verbindung zu einem herstellt oder die Verbindung zu einem trennt. API APIGateway ruft die $default Route auf, wenn keine anderen Routen mit einer Anfrage übereinstimmen. Sie erstellen eine benutzerdefinierte Route, um eine Verbindung zu Step Functions herzustellen, nachdem Sie Ihre erstellt habenAPI.
Wählen Sie Weiter aus.
Gehen Sie für die Integration für $connect wie folgt vor:
Wählen Sie als Integrationstyp Lambda aus.
-
Wählen Sie für die Lambda-Funktion die entsprechende $connect Lambda-Funktion aus, mit der Sie AWS CloudFormation in Schritt 1 erstellt haben. Der Name der Lambda-Funktion sollte mit
websocket-step
beginnen.
Gehen Sie für die Integration für $disconnect wie folgt vor:
Wählen Sie als Integrationstyp Lambda aus.
-
Wählen Sie für die Lambda-Funktion die entsprechende $disconnect Lambda-Funktion aus, mit der Sie AWS CloudFormation in Schritt 1 erstellt haben. Der Name der Lambda-Funktion sollte mit
websocket-step
beginnen.
Wählen Sie für Integration for $default die Option mock aus.
Bei einer Scheinintegration verwaltet API Gateway die Routenantwort ohne ein Integrations-Backend.
Wählen Sie Weiter aus.
-
Sehen Sie sich die Phase an, die API Gateway für Sie erstellt. Standardmäßig erstellt API Gateway eine Phase mit dem Namen Production und stellt Ihre Phase automatisch in dieser Phase API bereit. Wählen Sie Weiter aus.
Wählen Sie Create and deploy (Erstellen und bereitstellen) aus.
Schritt 3: Erstellen Sie einen Lambda-Autorisierer
Um den Zugriff auf Ihren zu kontrollieren WebSocket API, erstellen Sie einen Lambda-Autorisierer. Die AWS CloudFormation Vorlage hat die Lambda-Autorisierungsfunktion für Sie erstellt. Sie können die Lambda-Funktion in der Lambda-Konsole sehen. Der Name sollte mit beginnen. websocket-step-functions-tutorial-AuthorizerHandler
Diese Lambda-Funktion verweigert alle Aufrufe von, WebSocket API es sei denn, der Authorization
Header ist es. Allow
Die Lambda-Funktion übergibt die $context.authorizer.principalId
Variable auch an IhreAPI, die später in der DynamoDB-Tabelle verwendet wird, um Anrufer zu identifizieren. API
In diesem Schritt konfigurieren Sie die $connect-Route für die Verwendung des Lambda-Autorisierers.
Um einen Lambda-Autorisierer zu erstellen
Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.
Wählen Sie im Hauptnavigationsbereich Genehmiger.
Wählen Sie Create an Authorizer aus.
Geben Sie als Namen des Autorisierers ein.
LambdaAuthorizer
Geben Sie als Autorisierer den Namen des Autorisierers einARN, der mit der Vorlage erstellt wurde. AWS CloudFormation Der Name sollte mit beginnen.
websocket-step-functions-tutorial-AuthorizerHandler
Anmerkung
Wir empfehlen, diesen Beispielautorisierer nicht für Ihre Produktion APIs zu verwenden.
Wählen Sie als Identitätsquellentyp die Option Header aus. Geben Sie für Key (Schlüssel)
Authorization
ein.Wählen Sie Autorisierer erstellen.
Nachdem Sie Ihren Autorisierer erstellt haben, hängen Sie ihn an die $connect-Route Ihres an. API
Um einen Authorizer an die $connect-Route anzuhängen
Wählen Sie im Hauptnavigationsbereich Routes aus.
Wählen Sie die $connect-Route.
Wählen Sie im Abschnitt Route request settings (Einstellungen der Routenanforderung) die Option Edit (Bearbeiten) aus.
Wählen Sie für Autorisierung das Drop-down-Menü und wählen Sie dann Ihren Anforderungsautorisierer aus.
Wählen Sie Änderungen speichern aus.
Schritt 4: Erstellen Sie eine simulierte bidirektionale Integration
Als Nächstes erstellen Sie die bidirektionale Scheinintegration für die $default-Route. Mit einer Scheinintegration können Sie eine Antwort an den Client senden, ohne ein Backend zu verwenden. Wenn Sie eine Integration für die $default Route erstellen, können Sie Kunden zeigen, wie sie mit Ihrer interagieren können. API
Sie konfigurieren die $default Route, um Clients darüber zu informieren, dass sie die SendMessage-Route verwenden sollen.
Um eine Scheinintegration zu erstellen
Melden Sie sich unter https://console.aws.amazon.com/apigateway
bei der API Gateway-Konsole an. Wählen Sie die $default Route und dann die Registerkarte Integrationsanfrage.
Wählen Sie für Anforderungsvorlagen die Option Bearbeiten aus.
Geben Sie als Ausdruck für die Vorlagenauswahl den
200
Wert ein, und wählen Sie dann Bearbeiten aus.Wählen Sie auf der Registerkarte Integrationsanfrage für Anforderungsvorlagen die Option Vorlage erstellen aus.
Geben Sie als Vorlagenschlüssel ein
200
.Geben Sie für Vorlage generieren die folgende Zuordnungsvorlage ein:
{"statusCode": 200}
Wählen Sie Create template (Vorlage erstellen) aus.
Das Ergebnis sollte wie folgt aussehen:
Wählen Sie im Bereich $default Route die Option Bidirektionale Kommunikation aktivieren aus.
Wählen Sie die Registerkarte Integrationsantwort und dann Integrationsantwort erstellen aus.
Geben Sie als Antwortschlüssel ein
$default
.Geben Sie als Ausdruck für die Vorlagenauswahl den Wert ein
200
.Wählen Sie Create response (Antwort erstellen) aus.
Wählen Sie unter Antwortvorlagen die Option Vorlage erstellen aus.
Geben Sie als Vorlagenschlüssel ein
200
.Geben Sie für Antwortvorlage die folgende Zuordnungsvorlage ein:
{"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}
Wählen Sie Create template (Vorlage erstellen) aus.
Das Ergebnis sollte wie folgt aussehen:
Schritt 5: Erstellen Sie eine Nicht-Proxy-Integration mit Step Functions
Als Nächstes erstellen Sie eine SendMessage-Route. Clients können die SendMessage-Route aufrufen, um eine Nachricht an alle verbundenen Clients zu senden. Die SendMessage-Route hat eine Nicht-Proxy-Serviceintegration mit. AWS AWS Step Functions Die Integration ruft den StartExecutionBefehl für den Step Functions Functions-Zustandsmaschine auf, den die AWS CloudFormation Vorlage für Sie erstellt hat.
Um eine Nicht-Proxy-Integration zu erstellen
Melden Sie sich unter https://console.aws.amazon.com/apigateway
bei der API Gateway-Konsole an. Wählen Sie Create route (Route erstellen) aus.
Geben Sie in Route key (Routenschlüssel)
sendmessage
ein.Wählen Sie als Integrationstyp die Option AWS Service aus.
Geben Sie für AWS Region die Region ein, in der Sie Ihre AWS CloudFormation Vorlage bereitgestellt haben.
Wählen Sie für AWS Service Step Functions.
Wählen Sie als HTTPMethode POST.
Für Aktionsname geben Sie
StartExecution
ein.Geben Sie als Ausführungsrolle die Ausführungsrolle ein, die durch die AWS CloudFormation Vorlage erstellt wurde. Der Name sollte sein WebsocketTutorialApiRole.
Wählen Sie Create route (Route erstellen) aus.
Als Nächstes erstellen Sie eine Mapping-Vorlage, um Anforderungsparameter an die Step Functions Functions-Zustandsmaschine zu senden.
Erstellen einer Zuweisungsvorlage
Wählen Sie die SendMessage-Route und dann die Registerkarte Integrationsanfrage.
Wählen Sie im Abschnitt Anforderungsvorlagen die Option Bearbeiten aus.
Geben Sie als Ausdruck für die Vorlagenauswahl den Wert ein
\$default
.Wählen Sie Bearbeiten aus.
Wählen Sie im Abschnitt Vorlagen anfordern die Option Vorlage erstellen aus.
Geben Sie als Vorlagenschlüssel ein
\$default
.Geben Sie für Vorlage generieren die folgende Zuordnungsvorlage ein:
#set($domain = "$context.domainName") #set($stage = "$context.stage") #set($body = $input.json('$')) #set($getMessage = $util.parseJson($body)) #set($mymessage = $getMessage.message) { "input": "{\"domain\": \"$domain\", \"stage\": \"$stage\", \"message\": \"$mymessage\"}", "stateMachineArn": "arn:aws:states:
us-east-2
:123456789012
:stateMachine:WebSocket-Tutorial-StateMachine" }Ersetzen Sie das
stateMachineArn
durch die ARN der Zustandsmaschine, die von erstellt wurde AWS CloudFormation.Die Zuordnungsvorlage macht Folgendes:
-
Erzeugt die Variable
$domain
mithilfe der KontextvariablendomainName
. -
Erzeugt die Variable
$stage
mithilfe der Kontextvariablenstage
.Die
$stage
Variablen$domain
und sind erforderlich, um einen Callback URL zu erstellen. Nimmt die eingehende
sendmessage
JSON Nachricht auf und extrahiert diemessage
Eigenschaft.-
Erzeugt die Eingabe für die Zustandsmaschine. Die Eingabe ist die Domäne und die Phase der Route WebSocket API sowie die Nachricht von der
sendmessage
Route.
-
-
Wählen Sie Create template (Vorlage erstellen) aus.
Sie können eine Nicht-Proxy-Integration auf den Routen $connect oder $disconnect erstellen, um direkt eine Verbindungs-ID zur DynamoDB-Tabelle hinzuzufügen oder zu entfernen, ohne eine Lambda-Funktion aufzurufen.
Schritt 6: Testen Sie Ihre API
Als Nächstes stellen Sie Ihr Gerät bereit und testen esAPI, um sicherzustellen, dass es ordnungsgemäß funktioniert. Sie verwenden den wscat
Befehl, um eine Verbindung zum herzustellen, API und dann verwenden Sie einen Schrägstrich-Befehl, um einen Ping-Frame zu senden, um die Verbindung zum zu überprüfen. WebSocket API
Um Ihre bereitzustellen API
Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway
an. Wählen Sie im Hauptnavigationsbereich Routes aus.
Wählen Sie BereitstellenAPI.
Wählen Sie für Stage die Option Production aus.
(Optional) Geben Sie unter Beschreibung der Bereitstellung eine Beschreibung ein.
Wählen Sie Bereitstellen.
Nachdem Sie Ihre bereitgestellt habenAPI, können Sie sie aufrufen. Verwenden Sie den InvokeURL, um Ihren aufzurufen. API
Um den Invoke URL für Ihren zu erhalten API
Wählen Sie Ihre API.
Wählen Sie Stages (Phasen) und anschließend production (Produktion) aus.
-
Notieren Sie sich IhreAPI. WebSocket URL Das URL sollte so aussehen
wss://
.abcdef123
.execute-api.us-east-2
.amazonaws.com/production
Jetzt, wo Sie Ihren Aufruf habenURL, können Sie die Verbindung zu Ihrem WebSocket API testen.
Um die Verbindung zu Ihrem zu testen API
Verwenden Sie den folgenden Befehl, um eine Verbindung zu Ihrem herzustellenAPI. Zunächst testen Sie die Verbindung, indem Sie den
/ping
Pfad aufrufen.wscat -c wss://
abcdef123
.execute-api.us-east-2
.amazonaws.com/production -H "Authorization: Allow" --slash -PConnected (press CTRL+C to quit)
-
Geben Sie den folgenden Befehl ein, um den Kontrollrahmen zu pingen. Sie können einen Kontrollrahmen für Keepalive-Zwecke von der Clientseite aus verwenden.
/ping
Das Ergebnis sollte wie folgt aussehen:
< Received pong (data: "")
Nachdem Sie die Verbindung getestet haben, können Sie testen, ob Ihre Verbindung korrekt API funktioniert. In diesem Schritt öffnen Sie ein neues Terminalfenster, damit Sie eine Nachricht an alle verbundenen Clients senden WebSocket API können.
Um deine zu testen API
-
Öffnen Sie ein neues Terminal. Führen Sie den Befehl
wscat
erneut mit den folgenden Parametern aus.wscat -c wss://
abcdef123
.execute-api.us-east-2
.amazonaws.com/production -H "Authorization: Allow"Connected (press CTRL+C to quit)
-
APIGateway bestimmt anhand Ihres API Ausdrucks zur Auswahl der Routenanforderung, welche Route aufgerufen werden soll. Ihr API Routenauswahlausdruck lautet
$request.body.action
. Daher ruft API Gateway diesendmessage
Route auf, wenn Sie die folgende Nachricht senden:{"action": "sendmessage", "message": "hello, from Step Functions!"}
Die der Route zugeordnete Step Functions Functions-Zustandsmaschine ruft eine Lambda-Funktion mit der Nachricht und dem Callback auf. URL Die Lambda-Funktion ruft das API Gateway Management auf API und sendet die Nachricht an alle verbundenen Clients. Alle Clients erhalten die folgende Nachricht:
< hello, from Step Functions!
Nachdem Sie Ihren getestet haben WebSocket API, können Sie die Verbindung zu Ihrem trennenAPI.
Um die Verbindung zu Ihrem zu trennen API
Drücken Sie
CTRL+C
, um die Verbindung zu Ihrem zu trennenAPI.Wenn ein Client die Verbindung zu Ihrem trenntAPI, ruft API Gateway Ihre API $disconnect-Route auf. Die Lambda-Integration für Ihre API $disconnect-Route entfernt die Verbindungs-ID aus DynamoDB.
Schritt 7: Bereinigen
Um unnötige Kosten zu verhindern, löschen Sie die Ressourcen, die Sie im Rahmen dieses Tutorials erstellt haben. Die folgenden Schritte löschen Ihren Stack und. AWS CloudFormation WebSocket API
Um ein zu löschen WebSocket API
Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway
an. Wählen Sie auf der APIsSeite Ihre Websocket-API aus.
Wählen Sie Actions (Aktionen) und Delete (Löschen) aus. Bestätigen Sie anschließend Ihre Auswahl.
Um einen Stapel zu löschen AWS CloudFormation
Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation
. -
Wählen Sie Ihren AWS CloudFormation Stack aus.
-
Wählen Sie Löschen und bestätigen Sie dann Ihre Auswahl.
Nächste Schritte
Sie können die Erstellung und Bereinigung aller an diesem Tutorial beteiligten AWS Ressourcen automatisieren. Ein Beispiel für eine AWS CloudFormation Vorlage, die diese Aktionen für dieses Tutorial automatisiert, finden Sie unter ws-sfn.zip.