API Gateway経由でStep Functionsのステートマシンを実行する

この記事はBeeX Advent Calendar 2023の6日目の記事です。

はじめに

AWSにはAPI機能をフルマネージドに提供するサービスとして、API Gatewayがあります。

よく見る構成としては、API Gatewayで作成されたAPI(RESTful等)に対してリクエストを送信し、受信したリクエストをバックエンドのLambdaで処理し結果を返す、というものがあります。

そのAPI Gatewayですが、Lambda等のリクエストを処理することができるコンピュートリソースをバックエンドに配置する以外に、直接AWSサービスのAPIをバックエンドとして呼び出すことも可能になっています。

今回はそのAPIを直接呼び出す仕組みを使用して、AWS Step Functionsの「StartExecution API」をAPI Gateway経由で呼び出す構成を検証していきます。
尚、API Gatewayを使用して「StartExecution API」を呼び出す手順は以下のドキュメントに記載されているので、こちらを参考に進めていきます。

作業内容

前提

API Gatewayを作成する前に、実行されるステートマシンを事前に準備しておきます。
今回は実行できれば良いので、以前作成したPassステートを1つ持つステートマシンを使用します。

１．IAMロール作成

ドキュメントの手順に従って、API Gatewayで利用するIAMロールを作成します。

• IAMロール：APIGatewayToStepFunctions
• 信頼関係："apigateway.amazonaws.com"
• アタッチポリシー：AWSStepFunctionsFullAccess

２．API作成

API エンドポイントタイプで"リージョン"を選択したREST APIを新規に作成します。

"/execution"リソースを作成します。

以下の内容で"POST"メソッドを作成します。

• メソッドタイプ：POST
• 統合タイプ：AWSのサービス
• AWSリージョン：ap-northeast-1
• AWSのサービス：Step Functions
• AWSサブドメイン：なし
• HTTPメソッド：POST
• アクションタイプ：アクション名を使用
• アクション名：StartExecution
• 実行ロール：手順１で作成したIAMロールのARN値
• 認証情報キャッシュ：発信者の認証情報をキャッシュキーに追加しない
• デフォルトタイムアウト：あり

３．実行テスト

API Gatewayのテストメソッドを使用して、実行テストを行います。
以下のパラメータを指定します。"name"パラメータは敢えて指定していません。

{
   "input": "{}",
   "arn:aws:states:ap-northeast-1:123456789123:stateMachine:PassStateMachine"
}

テストを実行すると、レスポンスが正常に返ってくることが確認できました。

念のためステートマシン側のコンソールも確認すると、実行された履歴が残っていることが確認できました。

４．APIデプロイ

ここまでできたら、API GatewayのコンソールからAPIをデプロイします。

デプロイするとURLが確認できるようになるので、このURLに対してコマンドラインからAPIを実行してみます。

先ほどのテストと同じくレスポンスが返ってきていることが確認できました。

$ curl -X POST -d '{"input": "{}","stateMachineArn": "arn:aws:states:ap-northeast-1:123456789132:stateMachine:PassStateMachine"}' https://s8l41c37mk.execute-api.ap-northeast-1.amazonaws.com/dev/execution
{"executionArn":"arn:aws:states:ap-northeast-1:123456789132:execution:PassStateMachine:1fa77114-5aef-404f-921d-fbc84d922a7d","startDate":1.701750653715E9}

ステートマシンのコンソールを確認すると新しい実行履歴が追加されていました。

おまけ

手順では、API Gateway作成時に設定するIAMロールに「AWSStepFunctionsFullAccess」ポリシーをアタッチしていましたが、実行するだけであればこれよりも少ない権限で実現できます。
具体的には以下の権限です。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "states:StartExecution",
            "Resource": "arn:aws:states:*:123456789132:stateMachine:*"
        }
    ]
}

また、そのままだとAPI URLが外部に漏れると自由に実行されてしまうため、WAFやリソースベースポリシーで実行元のソースIPを制限することができます。
以下はリソースベースポリシーで特定IPアドレス以外からの実行を拒否したときの例です。

実際に利用する場合は、上記などの観点も気にして設定するとよいと思います。

おまけ2

ここまでで実装したAPI GatewayではStep Functionsのステートマシンを実行するだけでしたが、実行結果を取得するリソースも同じ手順で作成してみます。

「/execution/status」というパスでAPIに新しいリソースを作成します。

「StartExecution」用メソッドを作成時と同じ内容で、アクション名だけを「DescribeExecution」に変更したメソッドを作成します。

以下を参考にCORSを有効化します。

• 「/execution」リソースのCORS有効化
  

• 「/execution/status」リソースのCORS有効化
  

API Gatewayのリソースベースポリシーも少し修正します。
具体的にはResource部分に追加したリソースを含めるように修正します。

APIをデプロイします。

最後にAPI Gatewayに設定しているIAMロールのポリシーに「DescribeExecution」APIを許可する権限を追加します。(わかりやすさのためステートメントを分けています)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "states:StartExecution",
            "Resource": "arn:aws:states:*:123456789123:stateMachine:*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "states:DescribeExecution",
            "Resource": [
                "arn:aws:states:*:123456789123:execution:*:*",
                "arn:aws:states:*:123456789123:express:*:*:*"
            ]
        }
    ]
}

ここまでできたら実際にAPIを実行して想定通りに動作するか確認していきます。
まずコマンドラインからAPIにリクエストを投げて、ステートマシンを実行します。

$ curl -X POST -d '{"input": "{}","stateMachineArn": "arn:aws:states:ap-northeast-1:123456789123:stateMachine:PassStateMachine"}' https://s8l41c37mk.execute-api.ap-northeast-1.amazonaws.com/dev/execution
{"executionArn":"arn:aws:states:ap-northeast-1:123456789123:execution:PassStateMachine:e19c7aff-0985-4c4f-936f-4df104200a69","startDate":1.701837432549E9}

レスポンスとして、「executionArn」が返されるので、それを「DescribeExecution」APIのリクエストパラメータに含めてステータスチェックを行います。
「DescribeExecution」APIに必要なリクエストパラメータは以下に記載があります。

以下のコマンドを実行します。

$ curl -X POST -d '{"executionArn": "arn:aws:states:ap-northeast-1:123456789123:execution:PassStateMachine:e19c7aff-0985-4c4f-936f-4df104200a69"}' https://s8l41c37mk.execute-api.ap-northeast-1.amazonaws.com/dev/execution/status

レスポンス内容のstatus値を見ると成功していることが確認できました。

$ curl -X POST -d '{"executionArn": "arn:aws:states:ap-northeast-1:123456789123:execution:PassStateMachine:e19c7aff-0985-4c4f-936f-4df104200a69"}' https://s8l41c37mk.execute-api.ap-northeast-1.amazonaws.com/dev/execution/status
{"executionArn":"arn:aws:states:ap-northeast-1:123456789123:execution:PassStateMachine:e19c7aff-0985-4c4f-936f-4df104200a69","input":"{}","inputDetails":{"__type":"com.amazonaws.swf.base.model#CloudWatchEventsExecutionDataDetails","included":true},"name":"e19c7aff-0985-4c4f-936f-4df104200a69","output":"{}","outputDetails":{"__type":"com.amazonaws.swf.base.model#CloudWatchEventsExecutionDataDetails","included":true},"redriveCount":0,"redriveStatus":"NOT_REDRIVABLE","redriveStatusReason":"Execution is SUCCEEDED and cannot be redriven","startDate":1.701837432549E9,"stateMachineArn":"arn:aws:states:ap-northeast-1:123456789123:stateMachine:PassStateMachine","status":"SUCCEEDED","stopDate":1.701837432618E9,"traceHeader":"Root=1-656ffa78-6aeb8e79759bcdf2257765bc;Sampled=1"}

おわりに

このようにAPI Gatewayを利用すると外部からAWSサービスのAPIを実行することができるようになります。