# API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 설정
Lambda 함수의 응답을 스트리밍하여 첫 번째 바이트까지의 시간(TTFB) 성능을 개선하고 부분 응답을 사용할 수 있게 되면 클라이언트로 다시 보낼 수 있습니다. API Gateway를 사용하려면 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) Lambda API를 사용하여 Lambda 함수를 간접적으로 호출해야 합니다. API Gateway는 이벤트 객체를 Lambda 함수에 전달합니다. 백엔드 Lambda 함수는 수신되는 요청 데이터를 구문 분석하여 반환하는 응답을 결정합니다. API Gateway가 Lambda 출력을 스트리밍하려면 Lambda 함수가 API Gateway에 필요한 [형식](#response-transfer-mode-lambda-format)을 출력해야 합니다.
## 스트림과 버퍼링된 응답 전송 모드 간의 Lambda 프록시 통합 차이
다음 목록은 응답 스트리밍을 위한 Lambda 프록시 통합과 Lambda 프록시 통합의 차이점을 설명합니다.
+ API Gateway는 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API를 사용하여 응답 스트리밍을 위한 Lambda 프록시 통합을 간접적으로 호출합니다. 이렇게 하면 다음과 같은 다른 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
```
이 ARN은 API 버전에 대해 다른 날짜를 사용하고 Lambda 프록시 통합과는 다른 서비스 작업을 사용합니다.
응답 스트리밍에 API Gateway 콘솔을 사용하는 경우 콘솔은 올바른 URI를 사용합니다.
+ Lambda 프록시 통합에서 API Gateway는 Lambda로부터 전체 응답을 수신한 후에만 클라이언트에 응답을 전송합니다. 응답 스트리밍을 위한 Lambda 프록시 통합에서 API Gateway는 Lambda에서 유효한 메타데이터 및 구분 기호를 수신한 후 페이로드 스트림을 시작합니다.
+ 응답 스트리밍을 위한 Lambda 프록시 통합은 프록시 통합과 동일한 입력 형식을 사용하지만 다른 출력 형식이 필요합니다.
## 응답 스트리밍을 위한 Lambda 프록시 통합 형식
API Gateway가 응답 스트리밍으로 Lambda 함수를 간접적으로 호출하는 경우 입력 형식은 프록시 통합을 위한 Lambda 함수의 입력 형식과 동일합니다. 자세한 내용은 [프록시 통합에 대한 Lambda 함수의 입력 형식](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) 섹션을 참조하세요.
Lambda가 API Gateway에 응답을 스트리밍할 때 응답은 다음 형식을 준수해야 합니다. 이 형식은 구분 기호를 사용하여 메타데이터 JSON과 원시 페이로드를 구분합니다. 이 경우 페이로드 데이터는 스트리밍 Lambda 함수에 의해 전송될 때 스트리밍됩니다.
```
{
"headers": {"headerName": "headerValue", ...},
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"cookies" : ["cookie1", "cookie2"],
"statusCode": httpStatusCode
}PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
출력에서:
+ 출력에서 추가 응답 헤더가 반환되지 않을 경우 `headers`, `multiValueHeaders`, `cookies` 및 `statusCode` 키가 비지정 상태일 수 있습니다.
+ `headers` 키에는 단일 값 헤더만 있습니다.
+ 출력에는 헤더에 `Transfer-Encoding: chunked` 또는 `Content-length: number`이 포함될 것으로 예상됩니다. 함수가 이러한 헤더 중 하나를 반환하지 않으면 API Gateway는 응답 헤더에 `Transfer-Encoding: chunked`를 추가합니다.
+ `multiValueHeaders` 키에는 다중 값 헤더와 단일 값 헤더가 있을 수 있습니다. `multiValueHeaders` 키를 사용하여 모든 단일 값 헤더를 포함하는 모든 추가 헤더를 지정할 수 있습니다.
+ `headers` 및 `multiValueHeaders` 모두에 대해 값을 지정한 경우, API Gateway는 이들 헤더를 단일 목록으로 병합합니다. 동일한 키-값 페어가 양쪽 모두에 지정된 경우, `multiValueHeaders`의 값만이 병합된 목록에 표시됩니다.
+ 메타데이터는 유효한 JSON이어야 합니다. `headers`, `multiValueHeaders`, `statusCode` 및 `cookies` 키만 지원됩니다.
+ 메타데이터 JSON 뒤에 구분 기호를 제공해야 합니다. 구분 기호는 8 Null 바이트여야 하며 스트림 데이터의 처음 16KB 내에 나타나야 합니다.
+ API Gateway에는 메서드 응답 페이로드에 대한 특정 형식이 필요하지 않습니다.
함수 URL을 사용하여 Lambda 함수를 스트리밍하는 경우 이러한 요구 사항을 충족하도록 Lambda 함수의 입력 및 출력을 수정해야 합니다.
Lambda 함수 출력이 이 형식의 요구 사항을 준수하지 않는 경우에도 API Gateway는 여전히 Lambda 함수를 간접적으로 호출할 수 있습니다. 다음 표에는 API Gateway에서 지원하는 API 통합 요청 설정과 Lambda 함수 코드의 조합이 나와 있습니다. 여기에는 버퍼링된의 응답 전송 모드에 대해 지원되는 조합이 포함됩니다.
| 응답 전송 모드 | 함수 코드가 필수 형식을 준수합니다. | Lambda API 간접 호출 | API Gateway에서 지원됨 |
| --- | --- | --- | --- |
| Stream | 예 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 예. API Gateway는 응답을 스트리밍합니다. |
| Stream | 아니요 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는 Lambda 함수를 간접적으로 호출하고 500 오류 응답을 반환합니다. |
| Stream | 예 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| Stream | 아니요 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 예 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 아니요 | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | 아니요. API Gateway는이 통합 구성을 지원하지 않습니다. |
| 버퍼링됨 | 예 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway는 HTTP 헤더와 상태 코드를 반환하지만 응답 본문은 반환하지 않습니다. |
| 버퍼링됨 | 아니요 | [간접 호출](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 예. 이는 Lambda 프록시 통합입니다. 자세한 내용은 [Lambda 프록시 통합](set-up-lambda-proxy-integrations.md)을 참조하세요. |
# API Gateway에서 페이로드 응답 스트리밍과 Lambda 프록시 통합 구성
응답 페이로드 스트리밍을 설정할 때 리소스의 통합 요청에서 전송 모드를 지정합니다. 통합 요청에서 이러한 설정을 구성하여 통합 응답 전후에 API Gateway가 작동하는 방식을 제어합니다.
## 응답 스트리밍을 위한 Lambda 함수 예제
Lambda 함수는 [응답 스트리밍을 위한 Lambda 프록시 통합 형식](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format)을 준수해야 합니다. 응답 스트리밍을 테스트하려면 세 가지 예제 Lambda 함수 중 하나를 사용하는 것이 좋습니다. Lambda 함수를 생성할 때 다음을 수행해야 합니다.
+ 함수에 적절한 제한 시간을 제공합니다. 응답 스트리밍에 대해 알아보려면 최소 1분의 제한 시간을 구성하는 것이 좋습니다. 프로덕션 리소스를 생성할 때 Lambda 함수 제한 시간이 전체 요청 주기를 포함하는지 확인합니다. 자세한 내용은 [Lambda 함수 제한 시간 구성](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)을 참조하세요.
+ 최신 Node.js 런타임을 사용합니다.
+ Lambda 응답 스트리밍을 사용할 수 있는 리전을 사용합니다.
------
#### [ Using HttpResponseStream.from ]
다음 코드 예제에서는 파이프라인 `awslambda.HttpResponseStream()` 메서드를 사용하지 않고 메서드를 사용하여 JSON 메타데이터 객체와 페이로드를 클라이언트로 다시 스트리밍합니다. 구분 기호를 생성할 필요가 없습니다. 자세한 내용은 [응답 스트리밍이 활성화된 Lambda 함수 작성](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)을 참조하세요.
```
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 함수 작성](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html)을 참조하세요.
다음 코드 예제에서는 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 Console ]
**페이로드 응답 스트리밍과 Lambda 프록시 통합을 생성하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. **리소스 생성**을 선택합니다.
1. **리소스 이름**에 **streaming**을 입력합니다.
1. **리소스 생성**을 선택합니다.
1. **/streaming** 리소스를 선택한 상태에서 **메서드 생성**을 선택합니다.
1. **메서드 유형**에서 **모두**를 선택합니다.
1. **통합 유형**에서 **Lambda**를 선택합니다.
1. **Lambda 프록시 통합**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **Lambda 함수**에서 Lambda 함수의 이름을 선택합니다.
API Gateway 콘솔은 [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API를 사용하여 Lambda 함수를 간접적으로 호출합니다. 응답 스트리밍이 활성화된 Lambda 함수를 작성하는 것은 사용자의 책임입니다. 문제 해결 예는 [응답 스트리밍을 위한 Lambda 함수 예제](#response-streaming-lambda-example)을(를) 참조하세요.
1. **메서드 생성**을 선택합니다.
메서드를 생성한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
다음 절차에서는 `responseTransferMode`가 `STREAM`으로 설정된 새 API를 가져오는 방법을 보여 줍니다. 기존 통합 API가 있으며 `responseTransferMode`를 수정하려면 [Lambda 프록시 통합에 대한 응답 전송 모드 업데이트](#response-streaming-lambda-update) 섹션을 참조하세요.
**페이로드 응답 스트리밍을 사용하여 새 API 생성**
1. 다음 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` 명령을 사용하여 리소스 기반 권한을 추가할 수 있습니다.
1. 다음 `import-rest-api` 명령을 사용하여 OpenAPI 정의를 가져옵니다.
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. 다음 `create-deployment` 명령을 사용하여 새 API를 스테이지에 배포합니다.
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### Lambda 프록시 통합에 대한 응답 전송 모드 업데이트
다음 절차에서는 Lambda 프록시 통합에 대한 응답 전송 모드를 업데이트하는 방법을 보여 줍니다. 응답 전송 모드를 스트리밍으로 변경할 때 응답 스트리밍 요구 사항을 준수하도록 Lambda 함수를 업데이트합니다. 예제 Lambda 함수를 사용하거나 직접 생성합니다.
------
#### [ AWS Management Console ]
**Lambda 프록시 통합에 대한 응답 전송 모드 업데이트**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 방법을 선택합니다.
1. **통합 요청** 탭의 **통합 요청 설정**에서 **편집**을 선택합니다.
1. **응답 전송 모드**에서 **스트림**을 선택합니다.
1. **Lambda 함수**에서 Lambda 함수의 이름을 선택합니다.
1. **저장**을 선택합니다.
메서드를 업데이트한 후 API를 배포합니다.
**API를 배포하려면**
1. **Deploy API(API 배포)**를 선택합니다.
1. **스테이지**에서 **새 스테이지**를 선택합니다.
1. **단계 이름**에 **prod**를 입력합니다.
1. (선택 사항) **설명**에 설명을 입력합니다.
1. **배포(Deploy)**를 선택합니다.
------
#### [ AWS CLI ]
1. 스트리밍을 활성화하도록 Lambda 함수를 업데이트합니다.
1. 다음 AWS CLI 명령을 사용하여 통합의 통합 URI 및 응답 전송 모드를 업데이트합니다.
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"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\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. 변경 사항을 적용하려면 API를 재배포합니다.
------