Tutorial: Erstellen Sie eine WebSocket API mit einer AWS Integration - APIAmazon-Gateway

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.

Überblick über die ArchitekturAPI, die Sie in diesem Tutorial erstellen.

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.

Voraussetzungen

Sie benötigen die folgenden Voraussetzungen:

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
  1. Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation.

  2. Wählen Sie Stack erstellen und dann Mit neuen Ressourcen (Standard) aus.

  3. Wählen Sie unter Vorlage angeben die Option Vorlagendatei hochladen aus.

  4. Wählen Sie die Vorlage aus, die Sie heruntergeladen haben.

  5. Wählen Sie Weiter aus.

  6. Geben Sie für Stack-Name die Zeichenfolge websocket-step-functions-tutorial ein und klicken Sie auf Weiter.

  7. Wählen Sie in Stack-Optionen konfigurieren die Option Weiter aus.

  8. Bestätigen Sie bei Funktionen, dass IAM Ressourcen in Ihrem Konto erstellt werden AWS CloudFormation können.

  9. 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
  1. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

  2. Wählen Sie Erstellen API. Wählen Sie WebSocket APIdann für Build.

  3. Geben Sie als APINamen einwebsocket-step-functions-tutorial.

  4. 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.

  5. Wählen Sie Weiter aus.

  6. 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.

  7. Wählen Sie Weiter aus.

  8. Gehen Sie für die Integration für $connect wie folgt vor:

    1. Wählen Sie als Integrationstyp Lambda aus.

    2. 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.

  9. Gehen Sie für die Integration für $disconnect wie folgt vor:

    1. Wählen Sie als Integrationstyp Lambda aus.

    2. 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.

  10. Wählen Sie für Integration for $default die Option mock aus.

    Bei einer Scheinintegration verwaltet API Gateway die Routenantwort ohne ein Integrations-Backend.

  11. Wählen Sie Weiter aus.

  12. 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.

  13. 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
  1. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

  2. Wählen Sie im Hauptnavigationsbereich Genehmiger.

  3. Wählen Sie Create an Authorizer aus.

  4. Geben Sie als Namen des Autorisierers ein. LambdaAuthorizer

  5. 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.

  6. Wählen Sie als Identitätsquellentyp die Option Header aus. Geben Sie für Key (Schlüssel) Authorization ein.

  7. 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
  1. Wählen Sie im Hauptnavigationsbereich Routes aus.

  2. Wählen Sie die $connect-Route.

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

  4. Wählen Sie für Autorisierung das Drop-down-Menü und wählen Sie dann Ihren Anforderungsautorisierer aus.

  5. 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
  1. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

  2. Wählen Sie die $default Route und dann die Registerkarte Integrationsanfrage.

  3. Wählen Sie für Anforderungsvorlagen die Option Bearbeiten aus.

  4. Geben Sie als Ausdruck für die Vorlagenauswahl den 200 Wert ein, und wählen Sie dann Bearbeiten aus.

  5. Wählen Sie auf der Registerkarte Integrationsanfrage für Anforderungsvorlagen die Option Vorlage erstellen aus.

  6. Geben Sie als Vorlagenschlüssel ein200.

  7. 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:

    Konfiguration der Integrationsanforderung für die Scheinintegration für die $default Route.
  8. Wählen Sie im Bereich $default Route die Option Bidirektionale Kommunikation aktivieren aus.

  9. Wählen Sie die Registerkarte Integrationsantwort und dann Integrationsantwort erstellen aus.

  10. Geben Sie als Antwortschlüssel ein$default.

  11. Geben Sie als Ausdruck für die Vorlagenauswahl den Wert ein200.

  12. Wählen Sie Create response (Antwort erstellen) aus.

  13. Wählen Sie unter Antwortvorlagen die Option Vorlage erstellen aus.

  14. Geben Sie als Vorlagenschlüssel ein200.

  15. Geben Sie für Antwortvorlage die folgende Zuordnungsvorlage ein:

    {"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}
  16. Wählen Sie Create template (Vorlage erstellen) aus.

    Das Ergebnis sollte wie folgt aussehen:

    Konfiguration der Integrationsantwort für die Scheinintegration für die $default Route.

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
  1. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

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

  3. Geben Sie in Route key (Routenschlüssel) sendmessage ein.

  4. Wählen Sie als Integrationstyp die Option AWS Service aus.

  5. Geben Sie für AWS Region die Region ein, in der Sie Ihre AWS CloudFormation Vorlage bereitgestellt haben.

  6. Wählen Sie für AWS Service Step Functions.

  7. Wählen Sie als HTTPMethode POST.

  8. Für Aktionsname geben Sie StartExecution ein.

  9. Geben Sie als Ausführungsrolle die Ausführungsrolle ein, die durch die AWS CloudFormation Vorlage erstellt wurde. Der Name sollte sein WebsocketTutorialApiRole.

  10. 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
  1. Wählen Sie die SendMessage-Route und dann die Registerkarte Integrationsanfrage.

  2. Wählen Sie im Abschnitt Anforderungsvorlagen die Option Bearbeiten aus.

  3. Geben Sie als Ausdruck für die Vorlagenauswahl den Wert ein\$default.

  4. Wählen Sie Bearbeiten aus.

  5. Wählen Sie im Abschnitt Vorlagen anfordern die Option Vorlage erstellen aus.

  6. Geben Sie als Vorlagenschlüssel ein\$default.

  7. 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 die message 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.

  8. Wählen Sie Create template (Vorlage erstellen) aus.

    Konfiguration der SendMessage-Route.

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
  1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie im Hauptnavigationsbereich Routes aus.

  3. Wählen Sie BereitstellenAPI.

  4. Wählen Sie für Stage die Option Production aus.

  5. (Optional) Geben Sie unter Beschreibung der Bereitstellung eine Beschreibung ein.

  6. 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
  1. Wählen Sie Ihre API.

  2. Wählen Sie Stages (Phasen) und anschließend production (Produktion) aus.

  3. Notieren Sie sich IhreAPI. WebSocket URL Das URL sollte so aussehenwss://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
  1. 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 -P
    Connected (press CTRL+C to quit)
  2. 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
  1. Ö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)
  2. 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 die sendmessage 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 SieCTRL+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
  1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wählen Sie auf der APIsSeite Ihre Websocket-API aus.

  3. 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
  1. Öffnen Sie die AWS CloudFormation Konsole unter https://console.aws.amazon.com/cloudformation.

  2. Wählen Sie Ihren AWS CloudFormation Stack aus.

  3. 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.