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.. ) およびフィルター式 (?( ) はサポートされていません。注記JSON パスを指定すると、API Gateway はリクエスト本文を 100 KB で切り捨て、選択式を適用します。100 KB を超えるペイロードを送信するには、 |
コンテキスト変数 | $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"