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

Step Functions を使用して API Gateway を呼び出し

Step Functions は、 Amazon ステートメント言語 (ASL) から直接特定の AWS サービスを制御できます。詳細については、「他のサービスでの使用」および「サービス API にパラメータを渡す」を参照してください。

Optimized API Gateway 統合と API Gateway AWS SDK 統合の違い

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

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

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 に送信されません。次の例では、trueステートマシン定義でがに設定されていない限り、 categoryフィールドAllowNullValuesはリクエストに含まれません。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  注記
  デフォルトでは、リクエスト入力状態の null 値を持つフィールドは API に送信されません。ステートマシン定義trueでをに設定することで、null 値を強制的に API AllowNullValues に送信できます。
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", 
    "Parameters": {
        "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 パターンを使用するには、次の例に示すように、タスク定義のリソースフィールドのForTaskToken 末尾に .wait を追加します。


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
    "Parameters": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "POST", 
        "Headers": { 
            "TaskToken.$": "States.Array($$.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 のステータスコードは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

詳細については、以下を参照してください。

API Gateway デベロッパーガイドの Amazon API Gateway の概念。
Amazon API Gateway の IAM ポリシー
API Gateway を呼び出すの方法を示すサンプルプロジェクト

API Gateway デベロッパーガイドの Amazon API Gateway の概念。

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

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

ドキュメントの表記規則

最適化された統合

Amazon Athena