API ゲートウェイ機能のサポートリクエストの形式認証と認可サービス統合パターン出力形式エラー処理 IAM ポリシー

Step Functions RESTAPIsでAPIゲートウェイを作成する

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

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

Optimized API Gateway 統合の主な機能

apigateway:invoke: に同等のがない AWS SDK サービス統合。代わりに、Optimized API Gateway サービスはAPIゲートウェイエンドポイントを直接呼び出します。

API ゲートウェイ機能のサポート

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

Step Functions API Gateway RESTAPIと API Gateway HTTPAPIの統合の両方でサポートされています。
- オーソライザー : IAM (署名バージョン 4 を使用）、認証なし、Lambda オーソライザー (リクエストパラメータベース、カスタムヘッダー付きのトークンベース）
- API タイプ: Regional
- API 管理 : APIゲートウェイAPIドメイン名、APIステージ、パス、クエリパラメータ、リクエスト本文
Step Functions API Gateway HTTPAPI統合でサポートされています。エッジ最適化のオプションを提供する Step Functions API Gateway RESTAPI統合APIsはサポートされていません。
Step Functions API Gateway 統合ではサポートされていません。
- オーソライザー： Amazon Cognitoネイティブ Open ID Connect / OAuth 2.0、トークンベースの Lambda オーソライザーの認証ヘッダー
- API タイプ： Private
- API 管理： カスタムドメイン名

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

Amazon API Gateway の概念ページ。
API Gateway デベロッパーガイドRESTのHTTPAPIsAPIs「」と「」を選択します。

リクエストの形式

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

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

ApiEndpoint
- タイプ: String
- API ゲートウェイのホスト名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 ステージHTTPAPIを使用するすべてのではオプションです。
Path
- タイプ: String
- API エンドポイントの後に追加されるパスパラメータ。
QueryParameters
- タイプ: JSON
- クエリ文字列では、同じキーに関連付けられた値のリストのみが許可されます。
RequestBody
- タイプ: JSON または String
- HTTP リクエスト本文。そのタイプは、JSONオブジェクトまたはのいずれかですString。 RequestBodyはPATCH、、POST、および PUTHTTPメソッドでのみサポートされています。
AllowNullValues
- タイプ: BOOLEAN – デフォルト値: false
- デフォルト設定では、リクエスト入力状態の NULL 値はに送信されませんAPI。次の例では、trueステートマシン定義でがに設定されていない限り、 categoryフィールドAllowNullValuesはリクエストに含まれません。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  注記
  デフォルトでは、リクエスト入力状態の null 値を持つフィールドはに送信されませんAPI。ステートマシン定義trueでをに設定APIすることで、null 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されます。
2. その Step Functions は、APIGateway を呼び出すサービスです"Service": "states.amazonaws.com"。
3. アクセス対象のリソースには、以下が含まれます。
  - - region.
  - - account-id 指定されたリージョンの。
  - - api-id.
  - - stage-name.
  - - HTTP-VERB （メソッド）。
  - - resource-path-specifier.
リソースポリシーの例については、IAM「Step Functions とAPIゲートウェイのポリシー」を参照してください。

リソース形式の詳細については、Gateway デベロッパーガイドのAPI「Gateway API で実行するためのアクセス許可のリソース形式API」を参照してください。

注記
リソースポリシーは、 REST でのみサポートされていますAPI。

サービス統合パターン

API Gateway 統合は、次の 2 つのサービス統合パターンをサポートします。

レスポンスのリクエスト。デフォルトの統合パターンです。これにより、Step Functions はHTTPレスポンスを受け取った直後に次のステップに進むことができます。

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


{
    "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 のステータスコードは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

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

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

リソース:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:[[region]]:[[accountId]]:*"
            ]
        }
    ]
}

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


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

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

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

ドキュメントの表記規則

最適化サービスの統合

Amazon Athena