# 在 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.amazonaws.cn/lambda/latest/dg/configuration-timeout.html)。
+ 使用最新的 Node.js 运行时。
+ 使用已提供 Lambda 响应流式传输的区域。
------
#### [ Using HttpResponseStream.from ]
以下代码示例通过 `awslambda.HttpResponseStream()` 方法（不使用 pipeline 方法）将 JSON 元数据对象和有效载荷流式传输回客户端，您无需创建分隔符。有关更多信息，请参阅[编写支持响应流式传输的 Lambda 函数](https://docs.amazonaws.cn/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()` 方法。使用 pipeline 方法时，您无需创建分隔符，Lambda 会自动处理。有关更多信息，请参阅[编写支持响应流式传输的 Lambda 函数](https://docs.amazonaws.cn/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 个空字节的分隔符。
```
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 函数或创建自己的函数。
------
#### [ Amazon Web Services 管理控制台 ]
**创建采用有效载荷响应流式传输的 Lambda 代理集成**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.amazonaws.cn/apigateway)。
1. 选择一个 REST API。
1. 选择**创建资源**。
1. 对于**资源名称**，输入 **streaming**。
1. 选择**创建资源**。
1. 选中 **/streaming** 资源后，选择**创建方法**。
1. 对于**方法类型**，请选择 **ANY**。
1. 对于**集成类型**，选择 **Lambda**。
1. 选择 **Lambda 代理集成**。
1. 对于**响应传输模式**，请选择**流式传输**。
1. 对于 **Lambda 函数**，选择 Lambda 函数名称。
API Gateway 控制台会自动使用 [InvokeWithResponseStream](https://docs.amazonaws.cn/lambda/latest/api/API_InvokeWithResponseStream.html) API 来调用 Lambda 函数。您负责编写支持响应流式传输的 Lambda 函数。有关示例，请参阅[用于响应流式传输的 Lambda 函数示例](#response-streaming-lambda-example)。
1. 选择**创建方法**。
创建方法后，部署您的 API。
**部署 API**
1. 选择**部署 API**。
1. 对于**阶段**，选择**新建阶段**。
1. 对于**阶段名称**，输入 **prod**。
1. （可选）对于**描述**，输入描述。
1. 选择**部署**。
------
#### [ Amazon 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 函数或创建自己的函数。
------
#### [ Amazon Web Services 管理控制台 ]
**更新 Lambda 代理集成的响应传输模式**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.amazonaws.cn/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。
1. 对于**响应传输模式**，请选择**流式传输**。
1. 对于 **Lambda 函数**，选择 Lambda 函数名称。
1. 选择**保存**。
更新方法后，部署您的 API。
**部署 API**
1. 选择**部署 API**。
1. 对于**阶段**，选择**新建阶段**。
1. 对于**阶段名称**，输入 **prod**。
1. （可选）对于**描述**，输入描述。
1. 选择**部署**。
------
#### [ Amazon CLI ]
1. 更新您的 Lambda 函数以支持流式传输。
1. 使用以下 Amazon 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 以使更改生效。
------