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을 참조하세요.

  • 필요할 경우 하나 이상의 요청 템플릿을 지정하여 라우팅 요청 데이터를 어떻게 통합 요청 데이터로 변환할 것인지 구성합니다.

API Gateway 콘솔을 사용하여 WebSocket API 통합 요청을 설정

API Gateway 콘솔을 사용하여 WebSocket API의 라우팅에 통합 요청을 추가하려면

  1. API Gateway 콘솔에 로그인하고 API를 선택한 다음 라우팅을 선택하세요.

  2. 라우팅에서 라우팅을 선택합니다.

  3. 통합 요청 탭을 선택한 다음 통합 요청 설정 섹션에서 편집을 선택합니다.

  4. 통합 유형에서 다음 중 하나를 선택합니다.

    • API가 이 계정 또는 다른 계정에서 이미 생성한 AWS Lambda 함수와 통합되는 경우에만 Lambda 함수를 선택합니다.

      AWS Lambda에서 새로운 Lambda 함수를 생성하거나 Lambda 함수에 대한 리소스 권한을 설정하거나 다른 Lambda 서비스 작업을 수행하려면 대신 AWS 서비스를 선택하세요.

    • API가 기존 HTTP 엔드포인트와 통합될 예정이라면 HTTP를 선택합니다. 자세한 내용은 API Gateway의 REST API에 대한 HTTP 통합 단원을 참조하세요.

    • 통합 백엔드 없이 직접 API Gateway에서 API 응답을 생성하려면 모의(Mock)를 선택하세요. 자세한 내용은 API Gateway의 REST API 모의 통합 단원을 참조하세요.

    • API가 AWS 서비스와 직접 통합될 예정이라면 AWS 서비스를 선택합니다.

    • API가 프라이빗 통합 엔드포인트로 VpcLink를 사용할 경우 VPC 링크를 선택합니다. 자세한 내용은 API Gateway의 REST API에 대한 프라이빗 통합 단원을 참조하세요.

  5. Lambda 함수를 선택한 경우 다음을 수행합니다.

    1. Lambda 프록시 통합 사용의 경우, Lambda 프록시 통합 또는 교차 계정 Lambda 프록시 통합을 사용하려면 해당 확인란을 선택합니다.

    2. Lambda 함수의 경우, 다음 방법 중 하나로 함수를 지정합니다.

      • Lambda 함수가 동일한 계정에 있으면 함수 이름을 입력한 후 드롭다운 목록에서 해당 함수를 선택합니다.

        참고

        함수 이름은 HelloWorld, HelloWorld:1 또는 HelloWorld:alpha에서와 같이, 별칭 또는 버전 사양을 선택적으로 포함할 수 있습니다.

      • 함수가 다른 계정에 있으면 함수의 ARN을 입력합니다.

    3. 기본 제한 시간 값인 29초를 사용하려면 기본 제한 시간을 활성화된 상태로 유지합니다. 사용자 지정 제한 시간을 설정하려면 기본 제한 시간을 선택하고 50 ~ 29000밀리초 사이의 제한 시간 값을 입력합니다.

  6. HTTP를 선택한 경우, API Gateway 콘솔을 사용하여 API 통합 요청 설정의 4단계 지침을 따릅니다.

  7. Mock(모의)을 선택한 경우 Request Templates(요청 템플릿) 단계로 진행하십시오.

  8. AWS 서비스를 선택한 경우, API Gateway 콘솔을 사용하여 API 통합 요청 설정의 6단계 지침을 따릅니다.

  9. VPC 링크를 선택한 경우 다음을 수행합니다.

    1. 프록시 통합 사용에서 요청이 VPCLink의 엔드포인트로 프록시되도록 하려면 확인란을 선택합니다.

    2. HTTP 메서드(HTTP method)에서 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. Save changes(변경 사항 저장)를 선택합니다.

  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. 다음 예와 같이 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
  }