Tutorial: Erstellen einer WebSocket-API mit einer AWS-Integration

So erstellen Sie einen AWS CloudFormation-Stack

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 in Funktionen, dass AWS CloudFormation IAM-Ressourcen in Ihrem Konto erstellen darf.

9. Wählen Sie Absenden aus.

Erstellen einer WebSocket-API

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wählen Sie Create API (API erstellen) aus. Wählen Sie in WebSocket API (WebSocket-API) die Option Build (Entwickeln) aus.

3. Geben Sie in API name (API-Name) websocket-step-functions-tutorial ein.

4. Geben Sie in Route selection expression (Ausdruck für die Routenauswahl) request.body.action ein.

   Der Ausdruck für die Routenauswahl legt die Route fest, die von API Gateway aufgerufen wird, wenn ein Client eine Nachricht sendet.

5. Wählen Sie Weiter.

6. Wählen Sie unter Vordefinierte Routen die Optionen $connect hinzufügen, $disconnect hinzufügen und $default hinzufügen aus.

   Die Routen $connect und $disconnect sind spezielle Routen, die API Gateway automatisch aufruft, wenn ein Client eine Verbindung zu einer API herstellt oder trennt. API Gateway ruft die $default-Route auf, wenn keine anderen Routen mit einer Anforderung übereinstimmen. Nachdem Sie Ihre API erstellt haben, erstellen Sie eine benutzerdefinierte Route, um eine Verbindung zu den Step Functions herzustellen.

7. Wählen Sie Weiter.

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

   1. Wühlen Sie unter Integrationstyp die Option Lambda aus.

   2. Unter Lambda-Funktion wählen Sie dann die entsprechende $connect-Lambda-Funktion aus, die Sie in Schritt 1 mit AWS CloudFormation erstellt haben. Der Lambda-Funktionsname sollte mit websocket-step beginnen.

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

   1. Wählen Sie unter Integrationstyp die Option Lambda aus.

   2. Unter Lambda-Funktion wählen Sie dann die entsprechende $disconnect-Lambda-Funktion aus, die Sie in Schritt 1 mit AWS CloudFormation erstellt haben. Der Lambda-Funktionsname sollte mit websocket-step beginnen.

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

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

11. Wählen Sie Weiter.

12. Überprüfen Sie die Phase, die API Gateway für Sie erstellt. Standardmäßig erstellt API Gateway eine Stufe namens Produktion und stellt Ihre API automatisch für diese Stufe bereit. Wählen Sie Weiter.

13. Wählen Sie Create and deploy (Erstellen und bereitstellen) aus.

Erstellen eines Lambda-Genehmigers

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wählen Sie im Hauptnavigationsbereich Genehmiger.

3. Klicken Sie auf Genehmiger erstellen.

4. Geben Sie unter Genehmigername LambdaAuthorizer ein.

5. Geben Sie unter Genehmiger-ARN den Namen des mit der AWS CloudFormation-Vorlage erstellten Genehmigers ein. Der Name muss mit websocket-step-functions-tutorial-AuthorizerHandler beginnen.

   Anmerkung

   Wir empfehlen, diesen Beispielgenehmiger nicht für Ihre Produktions-APIs zu verwenden.

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

7. Wählen Sie Autorisierer erstellen.

So fügen Sie einen Genehmiger zu der $connect-Route hinzu

1. Klicken Sie im Hauptnavigationsbereich auf Routen.

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

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

4. Öffnen Sie das Dropdown-Menü Genehmigung und wählen Sie Ihren Anforderungsgenehmiger aus.

5. Wählen Sie Änderungen speichern.

So erstellen Sie eine Scheinintegration

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Wählen Sie die $default-Route und dann die Registerkarte Integrationsanforderung aus.

3. Klicken Sie unter Anforderungsvorlagen auf Bearbeiten.

4. Geben Sie unter Ausdruck für die Vorlagenauswahl 200 ein und klicken Sie dann auf Bearbeiten.

5. Wählen Sie auf der Registerkarte Integrationsanforderung unter Anforderungsvorlagen die Option Vorlage erstellen aus.

6. Geben Sie unter Vorlagenschlüssel 200 ein.

7. Geben Sie für Vorlagentext die folgende Zuweisungsvorlage ein:

   {"statusCode": 200}

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

   Das Ergebnis sollte wie folgt aussehen:

   

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 unter Antwortschlüssel $default ein.

11. Geben Sie unter Vorlagen-Auswahlausdruck 200 ein.

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

13. Klicken Sie unter Zuweisungsvorlagen auf Vorlage erstellen.

14. Geben Sie unter Vorlagenschlüssel 200 ein.

15. Geben Sie für Antwortvorlage die folgende Zuweisungsvorlage 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:

    

So erstellen Sie eine Nicht-Proxy-Integration

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

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

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

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

5. Geben Sie unter AWS-Region die Region ein, in der Sie Ihre AWS CloudFormation-Vorlage bereitgestellt haben.

6. Wählen Sie unter AWS-Service die Option Step Functions aus.

7. Wählen Sie in HTTP method POST.

8. Für Aktionsname geben Sie StartExecution ein.

9. Geben Sie für Ausführungsrolle die Ausführungsrolle ein, die von der AWS CloudFormation-Vorlage erstellt wurde. Der Name sollte WebSocketTutorialApiRole lauten.

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

Erstellen einer Zuweisungsvorlage

1. Wählen Sie die sendmessage-Route und dann die Registerkarte Integrationsanforderung aus.

2. Klicken Sie im Abschnitt Vorlagenanforderung auf Bearbeiten.

3. Geben Sie unter Vorlagen-Auswahlausdruck \$default ein.

4. Wählen Sie Edit (Bearbeiten) aus.

5. Klicken Sie im Abschnitt Vorlagenanforderung auf Vorlage erstellen.

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

7. Geben Sie für Vorlagentext die folgende Zuweisungsvorlage 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 StateMachinEarn mit dem ARN der von AWS CloudFormation erstellten Zustandsmaschine.

   Die Zuweisungsvorlage führt Folgendes aus:

   • Erzeugt die Variable $domain mithilfe der Kontextvariable domainName.

   • Erzeugt die Variable $stage mithilfe der Kontextvariable stage.

     Die Variablen $domain und $stage sind für die Erzeugung einer Callback-URL erforderlich.

   • Extrahiert die message-Eigenschaft aus der eingehenden sendmessage-JSON-Nachricht.

   • Erzeugt die Eingabe für den Zustandsautomaten. Die Eingabe ist die Domain und die Stufe der WebSocket-API sowie die Nachricht von der sendmessage-Route.

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

   

Stellen Sie Ihre API bereit

1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

2. Klicken Sie im Hauptnavigationsbereich auf Routen.

3. Klicken Sie auf Deploy API.

4. Wählen Sie unter Stufe Produktion aus.

5. (Optional) Geben Sie unter Bereitstellungsbeschreibung eine Beschreibung ein.

6. Wählen Sie Bereitstellen.

So rufen Sie die URL für den Aufruf Ihrer API auf

1. Wählen Sie Ihre API aus.

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

3. Notieren Sie sich die WebSocket-URL Ihrer API. Die URL sollte wie wss://abcdef123.execute-api.us-east-2.amazonaws.com/production aussehen.

So testen Sie die Verbindung zu Ihrer API

1. Stellen Sie mit dem folgenden Befehl eine Verbindung zu Ihrer API her. Zuerst 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 anzupingen. Sie können einen Kontrollrahmen für Keepalive-Zwecke von der Client-Seite aus verwenden.

   /ping

   Das Ergebnis sollte wie folgt aussehen:

   < Received pong (data: "")

So testen Sie Ihre 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. API Gateway legt basierend auf dem Ausdruck für die Routenanforderungsauswahl Ihrer API fest, welche Route aufgerufen wird. Der Ausdruck für die Routenauswahl Ihrer API lautet $request.body.action. Daher ruft API Gateway die Route sendmessage auf, wenn Sie die folgende Nachricht senden:

   {"action": "sendmessage", "message": "hello, from Step Functions!"}

   Die der Route zugeordnete Zustandsmaschine für Step Functions ruft eine Lambda-Funktion mit der Nachricht und der Callback-URL auf. Die Lambda-Funktion ruft die API-Gateway-Management-API auf und sendet die Nachricht an alle verbundenen Clients. Alle Clients erhalten die folgende Nachricht:

   < hello, from Step Functions!

So trennen Sie die Verbindung zu Ihrer API

• Zur Trennung der Verbindung zu Ihrer API drücken Sie CTRL+C.

  Wenn ein Client die Verbindung zu Ihrer API trennt, ruft API Gateway die Route $disconnect Ihrer API auf. Die Lambda-Integration der $disconnect-Route Ihrer API entfernt die Verbindungs-ID aus DynamoDB.

So erstellen Sie eine 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 Seite APIs Ihre websocket-api aus.

3. Wählen Sie Actions (Aktionen) und Delete (Löschen) aus. Bestätigen Sie anschließend Ihre Auswahl.

So löschen Sie einen AWS CloudFormation-Stack

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.