Erstellen einer API Gateway-REST-API mit einem synchronen Express-Zustandsautomaten mithilfe der AWS CDK - AWS Step Functions

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.

Erstellen einer API Gateway-REST-API mit einem synchronen Express-Zustandsautomaten mithilfe der AWS CDK

Dieses Tutorial zeigt Ihnen, wie Sie eine API Gateway-REST-API mit Synchronous Express State Machine als Backend-Integration mithilfe der erstellen AWS Cloud Development Kit (AWS CDK). In diesem Tutorial wird das StepFunctionsRestApi Konstrukt verwendet, um den Zustandsautomaten mit dem API Gateway zu verbinden. Das StepFunctionsRestApiKonstrukt richtet ein Standard-Eingabe/Ausgabe-Mapping und die API Gateway-REST-API mit den erforderlichen Berechtigungen und einer HTTP-Methode „ANY“ ein. AWS CDK ist ein Infrastructure as Code (IAC)-Framework, mit dem Sie AWS Infrastruktur mit einer vollwertigen Programmiersprache definieren können. Sie schreiben eine App in einer der unterstützten Sprachen des CDK, die einen oder mehrere Stacks enthält, synthetisieren sie dann in einer - AWS CloudFormation Vorlage und stellen sie in Ihrem AWS Konto bereit. Wir verwenden sie, um eine API Gateway-REST-API zu definieren, die in Synchronous Express State Machine als Backend integriert ist, und dann die zu verwenden, AWS Management Console um die Ausführung zu initiieren.

Bevor Sie mit diesem Tutorial beginnen, richten Sie Ihre AWS CDK Entwicklungsumgebung wie unter Erste Schritte mit der AWS CDK – Voraussetzungen beschrieben ein und installieren Sie dann die , AWS CDK indem Sie Folgendes ausgeben:

npm install -g aws-cdk

Schritt 1: Einrichten Ihres AWS CDK Projekts

Erstellen Sie zunächst ein Verzeichnis für Ihre neue AWS CDK App und initialisieren Sie das Projekt.

TypeScript
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language typescript
JavaScript
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language javascript
Python
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language python

Nachdem das Projekt initialisiert wurde, aktivieren Sie die virtuelle Umgebung des Projekts und installieren Sie die Basisabhängigkeiten AWS CDKvon .

source .venv/bin/activate python -m pip install -r requirements.txt
Java
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language java
C#
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language csharp
Go
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language go
Anmerkung

Achten Sie darauf, das Verzeichnis zu benennenstepfunctions-rest-api. Die AWS CDK Anwendungsvorlage verwendet den Namen des Verzeichnisses, um Namen für Quelldateien und Klassen zu generieren. Wenn Sie einen anderen Namen verwenden, wird Ihre App nicht mit diesem Lernprogramm übereinstimmen.

Installieren Sie jetzt die Konstruktbibliotheksmodule für AWS Step Functions und Amazon API Gateway .

TypeScript
npm install @aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
JavaScript
npm install @aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
Python
python -m pip install aws-cdk.aws-stepfunctions python -m pip install aws-cdk.aws-apigateway
Java

Bearbeiten Sie pom.xml des Projekts, um die folgenden Abhängigkeiten innerhalb des vorhandenen <dependencies>-Container hinzuzufügen.

<dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>stepfunctions</artifactId> <version>${cdk.version}</version> </dependency> <dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>apigateway</artifactId> <version>${cdk.version}</version> </dependency>

Maven installiert diese Abhängigkeiten automatisch, wenn Sie Ihre App das nächste Mal erstellen. Um zu erstellen, stellen Sie mvn compile aus oder verwenden Sie den Entwicklung-Befehl Ihrer Java-IDE.

C#
dotnet add src/StepfunctionsRestApi package Amazon.CDK.AWS.Stepfunctions dotnet add src/StepfunctionsRestApi package Amazon.CDK.AWS.APIGateway

Sie können die angegebenen Pakete auch mithilfe der Visual Studio NuGet-Benutzeroberfläche installieren, die über Tools > NuGet Package Manager > Manage NuGet Packages for Solution verfügbar ist.

Sobald Sie die Module installiert haben, können Sie sie in Ihrer AWS CDK App verwenden, indem Sie die folgenden Pakete importieren.

TypeScript
@aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
JavaScript
@aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
Python
aws_cdk.aws_stepfunctions aws_cdk.aws_apigateway
Java
software.amazon.awscdk.services.apigateway.StepFunctionsRestApi software.amazon.awscdk.services.stepfunctions.Pass software.amazon.awscdk.services.stepfunctions.StateMachine software.amazon.awscdk.services.stepfunctions.StateMachineType
C#
Amazon.CDK.AWS.StepFunctions Amazon.CDK.AWS.APIGateway
Go

Fügen Sie Folgendes zu import in hinzustepfunctions-rest-api.go.

"github.com/aws/aws-cdk-go/awscdk/awsapigateway" "github.com/aws/aws-cdk-go/awscdk/awsstepfunctions"

Schritt 2: Verwenden der AWS CDK zum Erstellen einer API Gateway-REST-API mit Synchronous Express State Machine-Backend-Integration

Zuerst präsentieren wir die einzelnen Codeteile, die den Synchronous Express State Machine und die API Gateway-REST-API definieren, und erläutern dann, wie Sie sie in Ihre AWS CDK App einfügen. Anschließend erfahren Sie, wie Sie diese Ressourcen synthetisieren und bereitstellen.

Anmerkung

Der Zustandsautomat, den wir hier anzeigen werden, ist ein einfacher Zustandsautomat mit dem Pass Status .

So erstellen Sie einen Express-Zustandsautomaten

Dies ist der AWS CDK Code, der einen einfachen Zustandsautomaten mit einem -PassZustand definiert.

TypeScript
const machineDefinition = new stepfunctions.Pass(this, 'PassState', { result: {value:"Hello!"}, }) const stateMachine = new stepfunctions.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, });
JavaScript
const machineDefinition = new sfn.Pass(this, 'PassState', { result: {value:"Hello!"}, }) const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, });
Python
machine_definition = sfn.Pass(self,"PassState", result = sfn.Result("Hello")) state_machine = sfn.StateMachine(self, 'MyStateMachine', definition = machine_definition, state_machine_type = sfn.StateMachineType.EXPRESS)
Java
Pass machineDefinition = Pass.Builder.create(this, "PassState") .result(Result.fromString("Hello")) .build(); StateMachine stateMachine = StateMachine.Builder.create(this, "MyStateMachine") .definition(machineDefinition) .stateMachineType(StateMachineType.EXPRESS) .build();
C#
var machineDefinition = new Pass(this, "PassState", new PassProps { Result = Result.FromString("Hello") }); var stateMachine = new StateMachine(this, "MyStateMachine", new StateMachineProps { Definition = machineDefinition, StateMachineType = StateMachineType.EXPRESS });
Go
var machineDefinition = awsstepfunctions.NewPass(stack, jsii.String("PassState"), &awsstepfunctions.PassProps { Result: awsstepfunctions.NewResult(jsii.String("Hello")), }) var stateMachine = awsstepfunctions.NewStateMachine(stack, jsii.String("StateMachine"), &awsstepfunctions.StateMachineProps { Definition: machineDefinition, StateMachineType: awsstepfunctions.StateMachineType_EXPRESS, })

Sie können in diesem kurzen Snippet sehen:

  • Die Computerdefinition mit dem Namen PassState, bei der es sich um einen Pass Zustand handelt.

  • Der logische Name des Zustandsautomaten, MyStateMachine.

  • Die Computerdefinition wird als State Machine-Definition verwendet.

  • Der Typ des Zustandsautomaten ist auf gesetzt, EXPRESS da StepFunctionsRestApi nur einen Synchronous Express-Zustandsautomaten zulässt.

So erstellen Sie die API Gateway-REST-API mithilfe des StepFunctionsRestApiKonstrukts

Wir werden das -StepFunctionsRestApiKonstrukt verwenden, um die API Gateway-REST-API mit den erforderlichen Berechtigungen und der Standard-Eingabe/Ausgabe-Zuweisung zu erstellen.

TypeScript
const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
JavaScript
const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
Python
api = apigw.StepFunctionsRestApi(self, "StepFunctionsRestApi", state_machine = state_machine)
Java
StepFunctionsRestApi api = StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .stateMachine(stateMachine) .build();
C#
var api = new StepFunctionsRestApi(this, "StepFunctionsRestApi", new StepFunctionsRestApiProps { StateMachine = stateMachine });
Go
awsapigateway.NewStepFunctionsRestApi(stack, jsii.String("StepFunctionsRestApi"), &awsapigateway.StepFunctionsRestApiProps { StateMachine = stateMachine, })

So erstellen und stellen Sie die AWS CDK App bereit

Bearbeiten Sie in dem von Ihnen erstellten AWS CDK Projekt die Datei mit der Definition des Stacks so, dass sie wie der folgende Code aussieht. Sie werden die Definitionen des Step-Functions-Zustandsautomaten und des API Gateways von oben erkennen.

TypeScript

Aktualisieren Sie lib/stepfunctions-rest-api-stack.ts damit darauf folgendes steht.

import * as cdk from 'aws-cdk-lib'; import * as stepfunctions from 'aws-cdk-lib/aws-stepfunctions' import * as apigateway from 'aws-cdk-lib/aws-apigateway'; export class StepfunctionsRestApiStack extends cdk.Stack { constructor(scope: cdk.App, id: string, props?: cdk.StackProps) { super(scope, id, props); const machineDefinition = new stepfunctions.Pass(this, 'PassState', { result: {value:"Hello!"}, }); const stateMachine = new stepfunctions.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, }); const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
JavaScript

Aktualisieren Sie lib/stepfunctions-rest-api-stack.js damit darauf folgendes steht.

const cdk = require('@aws-cdk/core'); const stepfunctions = require('@aws-cdk/aws-stepfunctions'); const apigateway = require('@aws-cdk/aws-apigateway'); class StepfunctionsRestApiStack extends cdk.Stack { constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); const machineDefinition = new stepfunctions.Pass(this, "PassState", { result: {value:"Hello!"}, }) const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, }); const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine }); } } module.exports = { StepStack }
Python

Aktualisieren Sie stepfunctions_rest_api/stepfunctions_rest_api_stack.py damit darauf folgendes steht.

from aws_cdk import App, Stack from constructs import Construct from aws_cdk import aws_stepfunctions as sfn from aws_cdk import aws_apigateway as apigw class StepfunctionsRestApiStack(Stack): def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None: super().__init__(scope, construct_id, **kwargs) machine_definition = sfn.Pass(self,"PassState", result = sfn.Result("Hello")) state_machine = sfn.StateMachine(self, 'MyStateMachine', definition = machine_definition, state_machine_type = sfn.StateMachineType.EXPRESS) api = apigw.StepFunctionsRestApi(self, "StepFunctionsRestApi", state_machine = state_machine)
Java

Aktualisieren Sie src/main/java/com.myorg/StepfunctionsRestApiStack.java damit darauf folgendes steht.

package com.myorg; import software.amazon.awscdk.core.Construct; import software.amazon.awscdk.core.Stack; import software.amazon.awscdk.core.StackProps; import software.amazon.awscdk.services.stepfunctions.Pass; import software.amazon.awscdk.services.stepfunctions.StateMachine; import software.amazon.awscdk.services.stepfunctions.StateMachineType; import software.amazon.awscdk.services.apigateway.StepFunctionsRestApi; public class StepfunctionsRestApiStack extends Stack { public StepfunctionsRestApiStack(final Construct scope, final String id) { this(scope, id, null); } public StepfunctionsRestApiStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); Pass machineDefinition = Pass.Builder.create(this, "PassState") .result(Result.fromString("Hello")) .build(); StateMachine stateMachine = StateMachine.Builder.create(this, "MyStateMachine") .definition(machineDefinition) .stateMachineType(StateMachineType.EXPRESS) .build(); StepFunctionsRestApi api = StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .stateMachine(stateMachine) .build(); } }
C#

Aktualisieren Sie src/StepfunctionsRestApi/StepfunctionsRestApiStack.cs damit darauf folgendes steht.

using Amazon.CDK; using Amazon.CDK.AWS.StepFunctions; using Amazon.CDK.AWS.APIGateway; namespace StepfunctionsRestApi { public class StepfunctionsRestApiStack : Stack { internal StepfunctionsRestApi(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { var machineDefinition = new Pass(this, "PassState", new PassProps { Result = Result.FromString("Hello") }); var stateMachine = new StateMachine(this, "MyStateMachine", new StateMachineProps { Definition = machineDefinition, StateMachineType = StateMachineType.EXPRESS }); var api = new StepFunctionsRestApi(this, "StepFunctionsRestApi", new StepFunctionsRestApiProps { StateMachine = stateMachine }); } } }
Go

Aktualisieren Sie stepfunctions-rest-api.go damit darauf folgendes steht.

package main import ( "github.com/aws/aws-cdk-go/awscdk" "github.com/aws/aws-cdk-go/awscdk/awsapigateway" "github.com/aws/aws-cdk-go/awscdk/awsstepfunctions" "github.com/aws/constructs-go/constructs/v3" "github.com/aws/jsii-runtime-go" ) type StepfunctionsRestApiGoStackProps struct { awscdk.StackProps } func NewStepfunctionsRestApiGoStack(scope constructs.Construct, id string, props *StepfunctionsRestApiGoStackProps) awscdk.Stack { var sprops awscdk.StackProps if props != nil { sprops = props.StackProps } stack := awscdk.NewStack(scope, &id, &sprops) // The code that defines your stack goes here var machineDefinition = awsstepfunctions.NewPass(stack, jsii.String("PassState"), &awsstepfunctions.PassProps { Result: awsstepfunctions.NewResult(jsii.String("Hello")), }) var stateMachine = awsstepfunctions.NewStateMachine(stack, jsii.String("StateMachine"), &awsstepfunctions.StateMachineProps{ Definition: machineDefinition, StateMachineType: awsstepfunctions.StateMachineType_EXPRESS, }); awsapigateway.NewStepFunctionsRestApi(stack, jsii.String("StepFunctionsRestApi"), &awsapigateway.StepFunctionsRestApiProps{ StateMachine = stateMachine, }) return stack } func main() { app := awscdk.NewApp(nil) NewStepfunctionsRestApiGoStack(app, "StepfunctionsRestApiGoStack", &StepfunctionsRestApiGoStackProps{ awscdk.StackProps{ Env: env(), }, }) app.Synth(nil) } // env determines the AWS environment (account+region) in which our stack is to // be deployed. For more information see: https://docs.aws.amazon.com/cdk/latest/guide/environments.html func env() *awscdk.Environment { // If unspecified, this stack will be "environment-agnostic". // Account/Region-dependent features and context lookups will not work, but a // single synthesized template can be deployed anywhere. //--------------------------------------------------------------------------- return nil // Uncomment if you know exactly what account and region you want to deploy // the stack to. This is the recommendation for production stacks. //--------------------------------------------------------------------------- // return &awscdk.Environment{ // Account: jsii.String("123456789012"), // Region: jsii.String("us-east-1"), // } // Uncomment to specialize this stack for the AWS Account and Region that are // implied by the current CLI configuration. This is recommended for dev // stacks. //--------------------------------------------------------------------------- // return &awscdk.Environment{ // Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")), // Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")), // } }

Speichern Sie die Quelldatei, und geben Sie cdk synth im Hauptverzeichnis der App heraus. Der AWS CDK führt die App aus und synthetisiert daraus eine - AWS CloudFormation Vorlage und zeigt dann die Vorlage an.

Um das Amazon API Gateway und den AWS Step Functions Zustandsautomaten tatsächlich in Ihrem AWS-Konto bereitzustellen, geben Sie auscdk deploy. Sie werden aufgefordert, die von AWS CDK generierten IAM-Richtlinien zu genehmigen. Die erstellten Richtlinien sehen etwa wie folgt aus:

Schritt 3: Testen des API Gateways

Nachdem Sie Ihre API Gateway-REST-API mit Synchronous Express State Machine als Backend-Integration erstellt haben, können Sie das API Gateway testen.

So testen Sie das bereitgestellte API Gateway mit der API Gateway-Konsole

  1. Öffnen Sie die Amazon API Gateway-Konsole und melden Sie sich an.

  2. Wählen Sie Ihre REST-API mit dem Namen StepFunctionsRestApi.

  3. Wählen Sie im Bereich Ressourcen die ANY Methode aus.

  4. Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

  5. Wählen Sie für Method (Methode) die Option POST aus.

  6. Kopieren Sie für Anforderungstext die folgenden Anforderungsparameter.

    { "key": "Hello" }
  7. Wählen Sie Test aus. Sie bekommen die folgenden Informationen angezeigt:

    • Request ist der Pfad der Ressource, die für die Methode aufgerufen wurde.

    • Status ist der HTTP-Statuscode der Antwort.

    • Latenz ist die Zeit, die zwischen dem Empfang der Anforderung des Aufrufers und der zurückgegebenen Antwort vergeht.

    • Antworttext ist der Text der HTTP-Antwort.

    • Antwort-Header sind die Header der HTTP-Antwort.

    • Das Protokoll zeigt die simulierten Amazon- CloudWatch Logs-Einträge, die geschrieben worden wären, wenn diese Methode außerhalb der API-Gateway-Konsole aufgerufen worden wäre.

      Anmerkung

      Obwohl die CloudWatch Logs-Einträge simuliert werden, sind die Ergebnisse des Methodenaufrufs echt.

Die Ausgabe des Antworttexts sollte etwa wie folgt aussehen:

"Hello"
Tipp

Testen Sie das API Gateway mit verschiedenen Methoden und einer ungültigen Eingabe, um die Fehlerausgabe zu sehen. Möglicherweise möchten Sie den Zustandsautomaten so ändern, dass er nach einem bestimmten Schlüssel sucht, und während Tests geben Sie den falschen Schlüssel an, um die Ausführung des Zustandsautomaten zu fehlschlagen und eine Fehlermeldung in der Antworttextausgabe zu generieren.

So testen Sie die bereitgestellte API mithilfe von cURL

  1. Öffnen Sie ein Terminal-Fenster.

  2. Kopieren Sie den folgenden cURL-Befehl und fügen Sie ihn in das Terminalfenster ein. Ersetzen Sie dabei <api-id> mit der API-ID Ihrer API und <region> mit der Region, in der Ihre API bereitgestellt ist.

    curl -X POST\ 'https://<api-id>.execute-api.<region>.amazonaws.com/prod' \ -d '{"key":"Hello"}' \ -H 'Content-Type: application/json'

Die Ausgabe des Antworttexts sollte etwa wie folgt aussehen:

"Hello"
Tipp

Testen Sie das API Gateway mit verschiedenen Methoden und einer ungültigen Eingabe, um die Fehlerausgabe zu sehen. Möglicherweise möchten Sie den Zustandsautomaten ändern, um nach einem bestimmten Schlüssel zu suchen, und während Tests stellen Sie den falschen Schlüssel bereit, um die Ausführung des Zustandsautomaten zu fehlschlagen und eine Fehlermeldung in der Antworttextausgabe zu generieren.

Schritt 4: Bereinigen

Wenn Sie mit dem Ausprobieren Ihres API Gateways fertig sind, können Sie sowohl den Zustandsautomaten als auch das API Gateway mit dem AWS-CDK außer Betrieb nehmen. Geben Sie cdk destroy im Hauptverzeichnis Ihrer App heraus.