API Gateway 特徴のサポートリクエストの形式認証と認可サービス統合パターン出力形式エラー処理 IAM ポリシー

Step Functions を使用して API Gateway REST API を作成する

Amazon API Gateway を使用して、Step Functions で HTTP と REST API を作成、発行、管理、モニタリングする方法について説明します。API Gateway と統合するには、コードを記述したり、他のインフラストラクチャに依存したりすることなく、API Gateway HTTP または API Gateway REST エンドポイントを直接呼び出す Step Functions 内の Task 状態を定義します。Task 状態定義には、API コールに必要なすべての情報が含まれます。別の認可方法を選択することもできます。

Step Functions で AWS サービスと統合することについては、「サービスとの統合」および「Step Functions でサービス API にパラメータを渡す」を参照してください。

最適化された API Gateway 統合の主な機能

AWS SDK サービス統合には、apigateway:invoke: に同等のものはありません。代わりに、最適化 API Gateway サービスは API Gateway エンドポイントを直接呼び出します。

API Gateway 特徴のサポート

Step Functions API Gateway 統合は、一部の API Gateway 機能をサポートしますが、すべてはサポートしていません。サポートされている特徴の詳細なリストについては、以下を参照してください。

以下は、Step Functions API Gateway REST API と API Gateway HTTP API 統合の両方でサポートされています。
- オーソライザー: IAM (署名バージョン 4を使用)、認証なし、Lambda Authorizers (カスタムヘッダーを使用したリクエストパラメータベースおよびトークンベース)
- API タイプ: リージョン
- API 管理: API Gateway API ドメイン名、API ステージ、パス、クエリパラメータ、リクエストボディ
Step Functions API Gateway HTTP API 統合でサポートされています。エッジ最適化 API のオプションを提供する Step Functions API Gateway REST API 統合はサポートされていません。
Step Functions API Gateway 統合ではサポートされていません。
- オーソライザー: Amazon Cognito、ネイティブオープン ID Connect/OAuth 2.0、トークンベースの Lambda オーソライザーの認可ヘッダー
- API タイプ: プライベート
- API 管理: カスタムドメイン名

API Gateway と HTTP および REST API の詳細については、以下を参照してください。

Amazon API Gateway の概念ページ。
API Gateway デベロッパーガイドの HTTP API と REST API 間で選択します。

リクエストの形式

Task 状態定義を作成するとき、Step Functions はパラメータを検証し、呼び出しを実行するのに必要な URL を構築し、API を呼び出します。レスポンスには、HTTP ステータスコード、ヘッダー、およびレスポンス本文が含まれます。リクエスト形式には、必須およびオプションのパラメータがあります。

必須リクエストパラメータ

ApiEndpoint
- 型: String
- API Gateway URL のホスト名。形式は <API ID>.execute-api.region.amazonaws.com です。
  
  API ID には、次の英数字の組み合わせのみを使用できます: 0123456789abcdefghijklmnopqrstuvwxyz
Method
- 型: Enum
- HTTP メソッド。次のいずれかとなる必要があります。
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
  - HEAD
  - OPTIONS

オプションのリクエストパラメータ

Headers
- 型: JSON
- HTTP ヘッダーは、同じキーに関連付けられた値のリストを許可します。
Stage
- 型: String
- API Gateway で API がデプロイされるステージの名前。$default ステージを使用する HTTP API のオプションとなっています。
Path
- 型: String
- API エンドポイントの後に追加されるパスパラメータ。
QueryParameters
- 型: JSON
- クエリ文字列では、同じキーに関連付けられた値のリストのみが許可されます。
RequestBody
- タイプ: JSON または String
- HTTP リクエストボディ。そのタイプは、JSON オブジェクトまたは String です。RequestBody は、PATCH、POST、および PUT HTTP メソッドに対してのみサポートされています。
AllowNullValues
- タイプ: BOOLEAN - デフォルト値: false
- デフォルト設定では、リクエスト入力状態の null 値は API に送信されません。次の例では、ステートマシン定義で AllowNullValues が true に設定されていない限り、category フィールドはリクエストに含まれません。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  注記
  デフォルトでは、リクエスト入力状態の null 値を持つフィールドは API に送信されません。ステートマシン定義で AllowNullValues を true に設定することで、null 値を強制的に API に送信できます。
AuthType
- 型: JSON
- 認証方法。デフォルトの方法は NO_AUTH です。指定できる値は次のとおりです。
  - NO_AUTH
  - IAM_ROLE
  - RESOURCE_POLICY
  詳細については、「認証および認可」を参照してください。

注記

セキュリティを考慮して、以下の HTTP ヘッダーキーは現在、許可されていません。

X-Forwarded、X-Amz、または X-Amzn のプレフィックスが付いているキー。
Authorization
Connection
Content-md5
Expect
Host
Max-Forwards
Proxy-Authenticate
Server
TE
Transfer-Encoding
Trailer
Upgrade
Via
Www-Authenticate

次のコード例は、Step Functions を使用して API Gateway を呼び出す方法を示しています。


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "GET", 
        "Headers": { 
            "key": ["value1", "value2"] 
        },
        "Stage": "prod",
        "Path": "bills",
        "QueryParameters": {
            "billId": ["123456"]
        },
        "RequestBody": {},
        "AuthType": "NO_AUTH"
    } 
}

認証と認可

次の認証方法を使用できます。

認可なし: 認可メソッドなしで API を直接呼び出します。
IAM ロール: この方法では、Step Functions はステートマシンのロールを引き受けて、署名バージョン 4 (SigV4) を使ってリクエストに署名した後、API を呼び出します。
リソースポリシー: Step Functions はリクエストを認証し、API を呼び出します。API に以下を指定するリソースポリシーをアタッチする必要があります。
1. API Gateway を呼び出すステートマシン。
  
  重要
  アクセスを制限するため、ステートマシンを指定する必要があります。そうしない場合は、API へのリソースポリシー認証を使って API Gateway リクエストを認証するステートマシンにアクセスが付与されます。
2. そのStep Functions は、API Gateway を呼び出すサービスです: "Service": "states.amazonaws.com"。
3. アクセス対象のリソースには、以下が含まれます。
  - region。
  - 指定されたリージョンの account-id。
  - api-id。
  - stage-name。
  - HTTP-VERB (メソッド)。
  - resource-path-specifier。
リソースポリシーの例については、Step Functions と API Gateway 用 IAM ポリシーを参照してください。

リソース形式の詳細については、API Gateway デベロッパーガイドの API Gateway における API 実行許可のリソース形式を参照してください。

注記
リソースポリシーは REST API の場合に限り、サポートされます。

サービス統合パターン

API Gateway 統合では、次の 2 つのサービス統合パターンがサポートされています。

リクエストレスポンス。デフォルトの統合パターンです。このおかげで、TTP レスポンスを受信した直後に Step Functions が H次のステップに進むことができます。

タスクトークンのコールバックまで待機する (.waitForTaskToken) は、タスクトークンがペイロードとともに返されるまで待機します。以下の例に示す通り、.waitForTaskToken パターンを使うため、タスク定義の [Resource] (リソース) フィールドの末尾に .waitForTaskToken を追加します。


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "POST", 
        "Headers": { 
            "TaskToken": "{% $states.context.Task.Token %}"
        },
        "Stage": "prod",
        "Path": "bills/add",
        "QueryParameters": {},
        "RequestBody": {
            "billId": "my-new-bill"
        },
        "AuthType": "IAM_ROLE"
    } 
}

出力形式

次の出力パラメータが提供されます。

名前	型	説明
`ResponseBody`	`JSON` または `String`	API コールのレスポンスの本文。
`Headers`	`JSON`	レスポンスヘッダー
`StatusCode`	`Integer`	レスポンスの HTTP ステータスコード。
`StatusText`	`String`	レスポンスのステータステキスト。

レスポンスの例:


{
    "ResponseBody": {
        "myBills": []
    },
    "Headers": { 
        "key": ["value1", "value2"]
    }, 
    "StatusCode": 200,
    "StatusText": "OK" 
}

エラー処理

エラーが発生した場合、error そして cause は次のように返されます。

HTTP ステータスコードが使用可能な場合、エラーは ApiGateway.<HTTP Status Code> 形式で返されます。
HTTP ステータスコードが使用できない場合、エラーは ApiGateway.<Exception> 形式で返されます。

いずれの場合も、cause は文字列として返されます。

以下は、エラーが発生したレスポンスの例です。


{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}

注記

2XX のステータスコードは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

Amazon API Gateway への呼び出しの IAM ポリシー

以下のテンプレート例では、ステートマシンの定義におけるリソースに基づき、AWS Step Functions による IAM ポリシーの生成方法を示しています。詳細については、「Step Functions が統合サービスの IAM ポリシーを生成する方法」および「Step Functions でサービス統合パターンを検出する」を参照してください。

リソース:


{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
            ],
            "Effect": "Allow"
        }
    ]
}

次のコード例では、API Gateway を呼び出すためのリソースポリシーを示しています。


{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "states.amazonaws.com"
            },
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

最適化サービスの統合

Amazon Athena