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

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

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

最適化された API ゲートウェイ統合と 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 コールに必要なすべての情報が含まれます。別の認可方法を選択することもできます。

注記

Step Functions は、API Gateway を介して HTTP エンドポイントを呼び出す機能をサポートしていますが、現在、汎用 HTTP エンドポイントを呼び出す機能はサポートしていません。

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
- AllowNullValues を true に設定すると、次のように、ヌル値を渡す許可がでます。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "name": null
    }
}
```
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このパターンを使用するには、を追加します。 waitForTask次の例のように、タスク定義の Resource フィールドの末尾にあるトークン。


{
    "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