API Gateway で HTTP API の AWS のサービス統合を作成する - Amazon API Gateway

API Gateway で HTTP API の AWS のサービス統合を作成する

HTTP API と AWS のサービスは、ファーストクラス統合を使用して統合できます。ファーストクラス統合は、HTTP API ルートを AWS のサービス API に接続します。クライアントがファーストクラス統合でサポートされるルートを呼び出すと、API Gateway は AWS のサービス API を呼び出します。例えば、ファーストクラス統合を使用して、Amazon Simple Queue Service キューにメッセージを送信したり、AWS Step Functions ステートマシンを起動したりすることができます。サポートされているサービスアクションについては、「統合サブタイプのリファレンス」を参照してください。

リクエストパラメータのマッピング

ファーストクラス統合には、必須およびオプションのパラメータがあります。統合を作成するには、すべての必須のパラメータを設定する必要があります。静的な値を使用するか、実行時に動的に評価されるパラメータをマッピングできます。サポートされている統合とパラメータの完全なリストについては、「統合サブタイプのリファレンス」を参照してください。

次の表は、サポートされているマッピング要求パラメータを示しています。

タイプ コメント
ヘッダー値 $request.header.name ヘッダー名では大文字と小文字は区別されません。API Gateway は、複数のヘッダー値をコンマで結合します (例: "header1": "value1,value2")。
クエリ文字列値 $request.querystring.name クエリ文字列名では大文字と小文字が区別されます。API Gateway は複数の値をコンマで結合します (例: "querystring1": "Value1,Value2")。
パスパラメータ $request.path.name リクエストのパスパラメータの値。例えば、ルートが /pets/{petId} の場合は、$request.path.petId を使用してリクエストの petId パラメータをマッピングできます。
リクエストボディのパススルー $request.body API Gateway はリクエストボディ全体をパススルーします。
リクエストボディ $request.body.name JSON パス式。再帰下降 ($request.body..name) およびフィルター式 (?(expression)) はサポートされていません。
注記

JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、$request.body を指定します。

コンテキスト変数 $context.variableName サポートされているコンテキスト変数の値。
ステージ変数 $stageVariables.variableName ステージ変数の値。
静的な値 string 定数値。

ファーストクラス統合を作成する

ファーストクラス統合を作成する前に、統合する AWS のサービスアクションを呼び出す API Gateway アクセス許可を付与する IAM ロールを作成する必要があります。詳細については、「AWS のサービスのロールの作成」を参照してください。

ファーストクラス統合を作成するには、SQS-SendMessage などのサポートされている AWS のサービスアクションを選択し、リクエストパラメータを設定して、統合された AWS のサービス API を呼び出すアクセス許可を API Gateway に付与するロールを提供します。統合サブタイプに応じて、異なるリクエストパラメータが必要です。詳細については、「統合サブタイプのリファレンス」を参照してください。

次の AWS CLI コマンドは、Amazon SQS メッセージを送信する統合を作成します。

aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-subtype SQS-SendMessage \ --integration-type AWS_PROXY \ --payload-format-version 1.0 \ --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \ --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'

AWS CloudFormation を使用してファーストクラス統合を作成する

次の例は、Amazon EventBridge とのファーストクラス統合を使用して /{source}/{detailType} ルートを作成する AWS CloudFormation スニペットを示しています。

Source パラメータは {source} パスパラメータ、DetailType{DetailType} パスパラメータ、Detail パラメータはリクエスト本文にマップされます。

このスニペットは、PutEvents アクションを呼び出すための API Gateway アクセス許可を付与するイベントバスや IAM ロールを表示しません。

Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0"