응답 스트리밍을 위한 Lambda 함수 예제 페이로드 응답 스트리밍과 Lambda 프록시 통합 생성

API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 구성

응답 페이로드 스트리밍을 설정할 때 리소스의 통합 요청에서 전송 모드를 지정합니다. 통합 요청에서 이러한 설정을 구성하여 통합 응답 전후에 API Gateway가 작동하는 방식을 제어합니다.

응답 스트리밍을 위한 Lambda 함수 예제

Lambda 함수는 응답 스트리밍을 위한 Lambda 프록시 통합 형식을 준수해야 합니다. 응답 스트리밍을 테스트하려면 세 가지 예제 Lambda 함수 중 하나를 사용하는 것이 좋습니다. Lambda 함수를 생성할 때 다음을 수행해야 합니다.

함수에 적절한 제한 시간을 제공합니다. 응답 스트리밍에 대해 알아보려면 최소 1분의 제한 시간을 구성하는 것이 좋습니다. 프로덕션 리소스를 생성할 때 Lambda 함수 제한 시간이 전체 요청 주기를 포함하는지 확인합니다. 자세한 내용은 Lambda 함수 제한 시간 구성을 참조하세요.
최신 Node.js 런타임을 사용합니다.
Lambda 응답 스트리밍을 사용할 수 있는 리전을 사용합니다.

Using HttpResponseStream.from

다음 코드 예제에서는 파이프라인 awslambda.HttpResponseStream() 메서드를 사용하지 않고 메서드를 사용하여 JSON 메타데이터 객체와 페이로드를 클라이언트로 다시 스트리밍합니다. 구분 기호를 생성할 필요가 없습니다. 자세한 내용은 응답 스트리밍이 활성화된 Lambda 함수 작성을 참조하세요.


export const handler = awslambda.streamifyResponse(
  async (event, responseStream, context) => {
    const httpResponseMetadata = {
      "statusCode": 200,
      "headers": {
        "x-foo": "bar"
      },
      "multiValueHeaders": {
        "x-mv1": ["hello", "world"],
        "Set-Cookie": ["c1=blue", "c2=red"]
      }
    };

    responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
    await new Promise(r => setTimeout(r, 1000)); // synthetic delay

    responseStream.write("First payload ");
    await new Promise(r => setTimeout(r, 1000)); // synthetic delay

    responseStream.write("Final payload");
    responseStream.end();
});

Using the pipeline method

Lambda는 응답 스트리밍 지원 함수를 작성할 때 네이티브 Node.js 런타임이 제공하는 awslambda.streamifyResponse() 데코레이터와 pipeline() 메서드를 사용할 것을 권장합니다. 파이프라인 메서드를 사용하는 경우 구분 기호를 생성할 필요가 없습니다. Lambda가이 작업을 수행합니다. 자세한 내용은 응답 스트리밍이 활성화된 Lambda 함수 작성을 참조하세요.

다음 코드 예제에서는 JSON 메타데이터 객체와 세 개의 페이로드를 클라이언트로 다시 스트리밍합니다.


import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';

export const handler = awslambda.streamifyResponse(
  async (event, responseStream, context) => {
    const httpResponseMetadata = {
      statusCode: 200,
      headers: {
        "Content-Type": "text/plain",
        "X-Custom-Header": "Example-Custom-Header"
      }
    };

    responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);

    const dataStream = Readable.from(async function* () {
      yield "FIRST payload\n";
      await new Promise(r => setTimeout(r, 1000));
      yield "SECOND payload\n";
      await new Promise(r => setTimeout(r, 1000));
      yield "THIRD payload\n";
      await new Promise(r => setTimeout(r, 1000));
    }());

    await pipeline(dataStream, responseStream);
  }
);

Without using the pipeline method

다음 코드 예제에서는 awslambda.HttpResponseStream() 메서드를 사용하지 않고 JSON 메타데이터 객체와 세 개의 페이로드를 클라이언트로 다시 스트리밍합니다. awslambda.HttpResponseStream() 메서드가 없으면 메타데이터와 페이로드 사이에 8 Null 바이트의 구분 기호를 포함해야 합니다.


export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
  response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
  response.write("\x00".repeat(8)); // DELIMITER
  await new Promise(r => setTimeout(r, 1000));

  response.write("FIRST payload");
  await new Promise(r => setTimeout(r, 1000));

  response.write("SECOND payload");
  await new Promise(r => setTimeout(r, 1000));

  response.write("FINAL payload");
  response.end();
});

페이로드 응답 스트리밍과 Lambda 프록시 통합 생성

다음 절차에서는 페이로드 응답 스트리밍과 Lambda 프록시 통합을 생성하는 방법을 보여 줍니다. 예제 Lambda 함수를 사용하거나 직접 생성합니다.

AWS Management 콘솔

페이로드 응답 스트리밍과 Lambda 프록시 통합을 생성하려면

https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.
REST API를 선택합니다.
리소스 생성을 선택합니다.
리소스 이름에 streaming을 입력합니다.
리소스 생성을 선택합니다.
/streaming 리소스를 선택한 상태에서 메서드 생성을 선택합니다.
메서드 유형에서 모두를 선택합니다.
통합 유형‬에서 ‬Lambda를 선택합니다.
Lambda 프록시 통합을 선택합니다.
응답 전송 모드에서 스트림을 선택합니다.
Lambda 함수에서 Lambda 함수의 이름을 선택합니다.

API Gateway 콘솔은 InvokeWithResponseStream API를 사용하여 Lambda 함수를 간접적으로 호출합니다. 응답 스트리밍이 활성화된 Lambda 함수를 작성하는 것은 사용자의 책임입니다. 문제 해결 예는 응답 스트리밍을 위한 Lambda 함수 예제을(를) 참조하세요.
메서드 생성을 선택합니다.

메서드를 생성한 후 API를 배포합니다.

API를 배포하려면

Deploy API(API 배포)를 선택합니다.
스테이지에서 새 스테이지를 선택합니다.
단계 이름에 prod를 입력합니다.
(선택 사항) 설명에 설명을 입력합니다.
배포(Deploy)를 선택합니다.

AWS CLI

다음 절차에서는 responseTransferMode가 STREAM으로 설정된 새 API를 가져오는 방법을 보여 줍니다. 기존 통합 API가 있으며 responseTransferMode를 수정하려면 Lambda 프록시 통합에 대한 응답 전송 모드 업데이트 섹션을 참조하세요.

페이로드 응답 스트리밍을 사용하여 새 API 생성

다음 Open API 파일을 복사하고 ResponseStreamDemoSwagger.yaml로 저장합니다. 이 파일에서 responseTransferMode는 STREAM으로 설정되고 통합 URI는 arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations로 설정됩니다.

my-function의 함수 이름을 스트리밍 지원 함수로 바꾸고 자격 증명을 apigateway 서비스가 Lambda 함수를 간접적으로 호출하도록 허용하는 정책이 있는 IAM 역할로 바꿉니다.
```
openapi: "3.0.1"
info:
  title: "ResponseStreamingDemo"
  version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
  variables:
    basePath:
      default: "prod"
paths:
  /lambda:
    get:
      x-amazon-apigateway-integration:
        httpMethod: "POST"
        uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
        type: "aws_proxy"
        timeoutInMillis: 90000
        responseTransferMode: "STREAM"
        credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
자격 증명에 대한 IAM 역할을 제공하는 대신 Lambda에 대한 add-permission 명령을 사용하여 리소스 기반 권한을 추가할 수 있습니다.

다음 import-rest-api 명령을 사용하여 OpenAPI 정의를 가져옵니다.


aws apigateway import-rest-api \
  --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
  --parameters endpointConfigurationTypes=REGIONAL \
  --region us-west-1

다음 create-deployment 명령을 사용하여 새 API를 스테이지에 배포합니다.


aws apigateway create-deployment \
  --rest-api-id a1b2c2 \
  --stage-name prod \
  --region us-west-1

Lambda 프록시 통합에 대한 응답 전송 모드 업데이트

다음 절차에서는 Lambda 프록시 통합에 대한 응답 전송 모드를 업데이트하는 방법을 보여 줍니다. 응답 전송 모드를 스트리밍으로 변경할 때 응답 스트리밍 요구 사항을 준수하도록 Lambda 함수를 업데이트합니다. 예제 Lambda 함수를 사용하거나 직접 생성합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

페이로드 응답 스트리밍과 Lambda 프록시 통합 설정

응답 스트리밍 문제 해결