在 API Gateway 中設定 WebSocket API 整合要求 - Amazon API 网关
使用 WebSocket API Gateway 主控台設定 API 整合要求使用設定整合要求 AWS CLILambda 函數的輸入格式，用於 WebSocket API 的代理整合

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 API Gateway 中設定 WebSocket API 整合要求

設定整合請求包含下列事項：

  • 選擇路由金鑰來整合後端。

  • 指定要叫用的後端端點。 WebSocket API 支援下列整合類型：

    • AWS_PROXY

    • AWS

    • HTTP_PROXY

    • HTTP

    • MOCK

    如需有關整合類型的詳細資訊，請參閱 API Gateway V2 REST API IntegrationType中的。

  • 視需要指定一個或多個請求範本，設定路由請求資料轉換為整合請求資料的方式。

使用 WebSocket API Gateway 主控台設定 API 整合要求

使用 API Gateway 主控台將整合要求新增至 WebSocket API 中的路由

  1. 登入 API Gateway 主控台、選擇 API，然後選擇 Routes (路由)。

  2. 在 Routes (路由) 底下選擇路由。

  3. 選擇整合請求索引標籤，然後在整合請求設定區段中，選擇編輯。

  4. 針對整合類型，選擇下列其中一項：

    • 只有在您的 API 將與您在此帳戶或其他帳戶中建立的 AWS Lambda 函數整合時，才選擇 Lambda 函數。

      若要在中建立新的 Lambda 函數 AWS Lambda、設定 Lambda 函數的資源權限，或是要執行任何其他 Lambda 服務動作，請改為選擇AWS 服務。

    • 若您的 API 將整合現有 HTTP 端點，請選擇 HTTP (HTTP)。如需詳細資訊，請參閱 API Gateway 中其餘 API 的 HTTP 整合。

    • 若您希望直接從 API Gateway 產生 API 回應，不使用整合後端，請選擇 Mock (模擬)。如需詳細資訊，請參閱 API 網關中 REST API Gateway 的模擬集成。

    • 如果您的 API 將與AWS 服務整合，請選擇「 AWS 服務」。

    • 如果您的 API 將使用 VpcLink 做為私有整合端點，請選擇 VPC 連結。如需詳細資訊，請參閱 API閘道RESTAPIs中的私人整合。

  5. 如果您選擇 Lambda 函數，請執行下列動作：

    1. 若您希望使用 Lambda 代理整合或跨帳戶 Lambda 代理整合，請勾選使用 Lambda 代理整合核取方塊。

    2. 針對 Lambda 函數，以下列方式之一指定函數：

      • 若您的 Lambda 函數位於同一個帳戶，請輸入函數名稱，然後從下拉式清單中選取函數。

        注意

        函數名稱可選擇納入其別名或版本規格，如 HelloWorld、HelloWorld:1 或 HelloWorld:alpha。

      • 若函數位於不同帳戶，請輸入該函數的 ARN。

    3. 若要使用 29 秒的預設逾時值，請將預設逾時保持開啟。若要設定自訂逾時，請選擇預設逾時，然後輸入介於 50 和 29000 毫秒之間的逾時值。

  6. 若您選擇 HTTP (HTTP)，請依照 使用 API Gateway 主控台設定 API 整合請求 步驟 4 的指示。

  7. 若您選擇 Mock (模擬)，請前往 Request Templates (請求範本) 步驟。

  8. 若您選擇 AWS 服務，請依照 使用 API Gateway 主控台設定 API 整合請求 的步驟 6 的指示進行。

  9. 若您選擇 VPC 連結，請執行下列動作：

    1. 若您希望將請求代理到 VPCLink 端點，請勾選 VPC 代理整合核取方塊。

    2. 針對 HTTP method (HTTP 方法)，選擇最符合 HTTP 後端中方法的 HTTP 方法類型。

    3. 從 VPC 連結下拉式清單中，選取 VPC 連結。您可以在清單下方的文字方塊中選取 [Use Stage Variables] 並輸入 ${stageVariables.vpcLinkId}。

      將 API 部署到階段後，您就可以定義 vpcLinkId 階段變數，並將其值設定為 VpcLink 的 ID。

    4. 針對 Endpoint URL (端點 URL)，請輸入您希望此整合使用之 HTTP 後端的 URL。

    5. 若要使用 29 秒的預設逾時值，請將預設逾時保持開啟。若要設定自訂逾時，請選擇預設逾時，然後輸入介於 50 和 29000 毫秒之間的逾時值。

  10. 選擇儲存變更。

  11. 在請求範本下，執行下列動作：

    1. 在請求範本下選擇編輯，以輸入範本選擇表達式。

    2. 輸入範本選擇表達式。使用 API Gateway 在訊息承載中尋找的表達式。若找到將對其評估，而結果範本金鑰值將用於選取在訊息承載內套用至資料的資料映射範本。您會在下一個步驟中建立資料映射範本。選擇編輯，儲存您的變更。

    3. 選擇建立範本，以建立資料映射範本。針對範本金鑰輸入範本金鑰值，該值將用來選取要對訊息承載中的資料套用的資料映射範本。接著，輸入映射範本。選擇建立範本。

      如需範本選擇表達式的相關資訊，請參閱 範本選擇表達式。

使用設定整合要求 AWS CLI

您可以使用如下列範例所示，建立模擬整合 AWS CLI ，在 WebSocket API 中設定路由的整合要求：

  1. 建立名為 integration-params.json 的檔案，其中內容如下：

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

  2. 執行建立整合命令，如下列範例所示：

    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"
}

或者，您也可以使用如下列範例所示，設定 Proxy 整合 AWS CLI 的整合要求：

  1. 在 Lambda 主控台中建立 Lambda 函數，並賦予基本的 Lambda 執行角色。

  2. 執行建立整合命令命令，如下列範例所示：

    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"
}

Lambda 函數的輸入格式，用於 WebSocket API 的代理整合

在 Lambda 代理整合中，API Gateway 會將整個用戶端請求映射至後端 Lambda 函數的輸入 event 參數。下列範例顯示$connect路由中輸入事件的結構，以及 API Gateway 傳送至 Lambda 代理整合$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
  }