API Gateway で WebSocket API 統合リクエストを設定する - Amazon API Gateway
API Gateway コンソールを使用して WebSocket API 統合リクエストを設定するAWS CLI を使用して統合リクエストを設定するWebSocket API のプロキシ統合のための Lambda 関数の入力形式

API Gateway で WebSocket API 統合リクエストを設定する

統合リクエストの設定では、次の操作が必要になります。

  • バックエンドに統合するルートキーを選択します。

  • 呼び出すバックエンドエンドポイントを指定します。WebSocket API は、以下の統合タイプをサポートしています。

    • AWS_PROXY

    • AWS

    • HTTP_PROXY

    • HTTP

    • MOCK

    統合タイプの詳細については、API Gateway V2 REST API の IntegrationType を参照してください。

  • 必要に応じて、1 つ以上のリクエストテンプレートを指定して、ルートリクエストデータを統合リクエストデータに変換する方法を設定します。

API Gateway コンソールを使用して WebSocket API 統合リクエストを設定する

API Gateway コンソールを使用して統合リクエストを WebSocket API のルートに追加するには

  1. API Gateway コンソールにサインインし、[API]、[Routes (ルート)] の順に選択します。

  2. [ルート] で、ルートを選択します。

  3. [統合リクエスト] タブを選択し、[統合リクエスト設定] セクションで [編集] を選択します。

  4. [統合タイプ] で、以下のいずれかを選択します。

    • [Lambda 関数] は、API がこのアカウントまたは別のアカウントで既に作成済みの AWS Lambda 関数と統合される場合のみ選択してください。

      AWS Lambda で新しい Lambda 関数を作成する場合、Lambda 関数にリソースのアクセス許可を設定する場合、またはその他の Lambda サービスアクションを実行する場合、代わりに [AWS Service] (AWS のサービス) を選択します。

    • API が既存の HTTP エンドポイントに統合される場合は、[HTTP] を選択します。詳細については、「API Gateway での REST API の HTTP 統合」を参照してください。

    • 統合バックエンドを必要とすることなく、API Gateway から直接 API レスポンスを生成する場合は、[Mock] を選択します。詳細については、「API Gateway での REST API の Mock 統合」を参照してください。

    • API が AWS のサービスと直接統合する場合は、[AWS のサービス] を選択します。

    • API でプライベート統合エンドポイントして VpcLink を使用する場合は、[VPC リンク] を選択します。詳細については、「API Gateway での REST API のプライベート統合」を参照してください。

  5. [Lambda 関数] を選択した場合は、以下の操作を実行します。

    1. [プロキシ統合の使用] で、Lambda プロキシ統合または クロスアカウントの Lambda プロキシ統合を使用する場合は、チェックボックスをオンにします。

    2. [Lambda 関数] で、次のいずれかの方法で関数を指定します。

      • Lambda 関数が同じアカウントにある場合、関数名を入力し、表示されたドロップダウンリストから関数を選択します。

        注記

        関数名には、オプションでエイリアスまたはバージョン指定を含めることができます (HelloWorld、HelloWorld:1、または HelloWorld:alpha)。

      • 関数が別のアカウントにある場合は、関数の ARN を入力します。

    3. 29 秒のデフォルトのタイムアウト値を使用するには、[デフォルトタイムアウト] をオンのままにします。カスタムのタイムアウトを設定するには、[デフォルトタイムアウト] を選択してから、タイムアウト値を 50 ～ 29000 ミリ秒の間で入力します。

  6. [HTTP] を選択した場合は、「API Gateway コンソールを使用して API 統合リクエストを設定する」のステップ 4 に従います。

  7. [Mock] を選択した場合は、[リクエストテンプレート] ステップに進みます。

  8. [AWS のサービス] を選択した場合は、「API Gateway コンソールを使用して API 統合リクエストを設定する」のステップ 6 に従います。

  9. [VPC リンク] を選択した場合は、以下の操作を実行します。

    1. [VPC プロキシ統合の使用] で、リクエストを VPCLink のエンドポイントにプロキシする場合は、チェックボックスを選択します。

    2. [HTTP メソッド] で、HTTP バックエンドのメソッドに最も厳密に一致する HTTP メソッドタイプを選択します。

    3. [VPC リンク] ドロップダウンリストから、[VPC リンク] を選択します。[Use Stage Variables] を選択して、リストの下のテキストボックスに ${stageVariables.vpcLinkId} を入力できます。

      ステージに API をデプロイした後、vpcLinkId ステージ変数を定義し、その値を VpcLink の ID に定義できます。

    4. [エンドポイント URL] に、この統合で使用する HTTP バックエンドの URL を入力します。

    5. 29 秒のデフォルトのタイムアウト値を使用するには、[デフォルトタイムアウト] をオンのままにします。カスタムのタイムアウトを設定するには、[デフォルトタイムアウト] を選択してから、タイムアウト値を 50 ～ 29000 ミリ秒の間で入力します。

  10. [Save changes] (変更の保存) をクリックします。

  11. [クエストテンプレート] で、次の操作を行います。

    1. テンプレート選択式を入力するには、[リクエストテンプレート] で [編集] を選択します。

    2. テンプレート選択式を入力します。メッセージペイロード内で API Gateway が検索する式を使用します。見つかった式は評価され、結果はメッセージペイロード内のデータに適用されるデータのマッピングテンプレートを選択するために使用されるテンプレートキー値となります。次のステップで、データマッピングテンプレートを作成します。[はい、編集します] を選択して、変更を保存します。

    3. [テンプレートの作成] を選択してデータマッピングテンプレートを作成します。[テンプレートキー] に、メッセージペイロード内のデータに適用されるデータマッピングの選択に使用するテンプレートキー値を入力します。次に、マッピングテンプレートを入力します。[テンプレートを作成] をクリックします。

      テンプレート選択式の詳細については、「テンプレート選択式」を参照してください。

AWS CLI を使用して統合リクエストを設定する

WebSocket API のルートの統合リクエストを設定するには、次の例のように、Mock 統合を作成する AWS CLI を使用します。

  1. 次の内容で、integration-params.json というファイルを作成します。

    {"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}

  2. 次の例に示すように create-integration コマンドを実行します。

    aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json

この例のサンプル出力を以下に示します。

{
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "TimeoutInMillis": 29000,
    "ConnectionType": "INTERNET",
    "IntegrationResponseSelectionExpression": "${response.statuscode}",
    "RequestTemplates": {
        "application/json": "{\"statusCode\":200}"
    },
    "IntegrationId": "0abcdef",
    "IntegrationType": "MOCK"
}

または、次の例のように AWS CLI を使用してプロキシ統合の統合リクエストを設定することもできます。

  1. Lambda コンソールで Lambda 関数を作成し、基本的な Lambda 実行ロールを提供します。

  2. 次の例のように create-integration コマンドを実行します。

    aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations

この例のサンプル出力を以下に示します。

{
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "IntegrationMethod": "POST",
    "TimeoutInMillis": 29000,
    "ConnectionType": "INTERNET",
    "IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations",
    "IntegrationId": "abcdefg",
    "IntegrationType": "AWS_PROXY"
}

WebSocket API のプロキシ統合のための Lambda 関数の入力形式

Lambda プロキシ統合では、API Gateway がクライアントリクエスト全体をバックエンド Lambda 関数の入力 event パラメータにマップします。次の例は、API Gateway が Lambda プロキシ統合に送信する $connect ルートおよび $disconnect ルートの入力イベントの構造を示しています。

Input from the $connect route
{
    headers: {
      Host: 'abcd123.execute-api.us-east-1.amazonaws.com',
      'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits',
      'Sec-WebSocket-Key': '...',
      'Sec-WebSocket-Version': '13',
      'X-Amzn-Trace-Id': '...',
      'X-Forwarded-For': '192.0.2.1',
      'X-Forwarded-Port': '443',
      'X-Forwarded-Proto': 'https'
    },
    multiValueHeaders: {
      Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ],
      'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ],
      'Sec-WebSocket-Key': [ '...' ],
      'Sec-WebSocket-Version': [ '13' ],
      'X-Amzn-Trace-Id': [ '...' ],
      'X-Forwarded-For': [ '192.0.2.1' ],
      'X-Forwarded-Port': [ '443' ],
      'X-Forwarded-Proto': [ 'https' ]
    },
    requestContext: {
      routeKey: '$connect',
      eventType: 'CONNECT',
      extendedRequestId: 'ABCD1234=',
      requestTime: '09/Feb/2024:18:11:43 +0000',
      messageDirection: 'IN',
      stage: 'prod',
      connectedAt: 1707502303419,
      requestTimeEpoch: 1707502303420,
      identity: { sourceIp: '192.0.2.1' },
      requestId: 'ABCD1234=',
      domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      connectionId: 'AAAA1234=',
      apiId: 'abcd1234'
    },
    isBase64Encoded: false
  }
Input from the $disconnect route
{
    headers: {
      Host: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      'x-api-key': '',
      'X-Forwarded-For': '',
      'x-restapi': ''
    },
    multiValueHeaders: {
      Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ],
      'x-api-key': [ '' ],
      'X-Forwarded-For': [ '' ],
      'x-restapi': [ '' ]
    },
    requestContext: {
      routeKey: '$disconnect',
      disconnectStatusCode: 1005,
      eventType: 'DISCONNECT',
      extendedRequestId: 'ABCD1234=',
      requestTime: '09/Feb/2024:18:23:28 +0000',
      messageDirection: 'IN',
      disconnectReason: 'Client-side close frame status not set',
      stage: 'prod',
      connectedAt: 1707503007396,
      requestTimeEpoch: 1707503008941,
      identity: { sourceIp: '192.0.2.1' },
      requestId: 'ABCD1234=',
      domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com',
      connectionId: 'AAAA1234=',
      apiId: 'abcd1234'
    },
    isBase64Encoded: false
  }