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	ステージ変数の値。
静的な値	文字列	定数値。

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

ファーストクラス統合を作成する前に、統合する 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"