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`、`cookies` 和 `statusCode` 键。
+ 必须在元数据 JSON 后面提供一个分隔符。该分隔符必须是 8 个空字节，且必须出现在流数据的前 16 KB 内。
+ API Gateway 对方法响应有效载荷没有特定格式要求。
如果您使用函数 URL 流式传输 Lambda 函数，必须修改 Lambda 函数的输入和输出以满足这些要求。
如果您的 Lambda 函数输出不符合此格式要求，API Gateway 仍可能调用您的 Lambda 函数，但会返回错误。下表展示了 API Gateway 支持的 API 集成请求设置与 Lambda 函数代码的组合。这包括响应传输模式为缓冲时支持的组合。
| 响应传输模式 | 函数代码符合要求的格式 | Lambda 调用 API | 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 调用您的 Lambda 函数并返回 500 错误响应。 |
| 流 | 是 | [调用](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | 否。API Gateway 不支持此集成配置。 |
| 流 | 否 | [调用](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()` 方法（不使用 pipeline 方法）将 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()` 方法。使用 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 个空字节的分隔符。
```
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 管理控制台 ]
**创建采用有效载荷响应流式传输的 Lambda 代理集成**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/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.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API 来调用 Lambda 函数。您负责编写支持响应流式传输的 Lambda 函数。有关示例，请参阅[用于响应流式传输的 Lambda 函数示例](#response-streaming-lambda-example)。
1. 选择**创建方法**。
创建方法后，部署您的 API。
**部署 API**
1. 选择**部署 API**。
1. 对于**阶段**，选择**新建阶段**。
1. 对于**阶段名称**，输入 **prod**。
1. （可选）对于**描述**，输入描述。
1. 选择**部署**。
------
#### [ 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 管理控制台 ]
**更新 Lambda 代理集成的响应传输模式**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。
1. 对于**响应传输模式**，请选择**流式传输**。
1. 对于 **Lambda 函数**，选择 Lambda 函数名称。
1. 选择**保存**。
更新方法后，部署您的 API。
**部署 API**
1. 选择**部署 API**。
1. 对于**阶段**，选择**新建阶段**。
1. 对于**阶段名称**，输入 **prod**。
1. （可选）对于**描述**，输入描述。
1. 选择**部署**。
------
#### [ 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 以使更改生效。
------
# 在 API Gateway 中排查响应流式传输问题
以下故障排除指南可帮助解决使用响应流式传输的 API 问题。
## 一般故障排除
您可以使用 [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) 或控制台的“测试”选项卡测试响应流式传输。使用测试调用功能进行响应流式传输时需注意以下事项：
+ 在测试方法时，API Gateway 会缓冲您的流式响应有效载荷。满足以下任一条件后，API Gateway 将返回包含缓冲的有效载荷的一次性响应：
+ 请求已完成
+ 已过去 35 秒
+ 已缓冲超过 1 MB 的响应有效载荷
+ 如果方法在 35 秒内未返回 HTTP 响应状态和所有标头，TestInvokeMethod 返回的响应状态为 0。
+ API Gateway 不会生成任何执行日志。
部署 API 后，可通过 curl 命令测试流式响应。建议使用 `-i` 选项在输出中包含协议响应标头。如需实时查看到达的响应数据，使用 curl 选项 `--no-buffer`。
## 排查 curl 错误
如果测试集成时出现 `curl: (18) transfer closed with outstanding read data remaining` 错误，需确保集成超时时间足够长。如果您使用的是 Lambda 函数，则需要更新 Lambda 函数的响应超时。有关更多信息，请参阅[配置 Lambda 函数超时](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html)。
## 通过访问日志排查问题
可通过 REST API 阶段的访问日志记录并排查响应流问题。除现有变量外，还可使用以下访问日志变量：
`$context.integration.responseTransferMode`
您的集成的响应传输模式。此值可以是 `BUFFERED` 或 `STREAMED`。
`$context.integration.timeToAllHeaders`
从 API Gateway 建立集成连接到从客户端接收所有集成响应头之间的时间间隔。
`$context.integration.timeToFirstContent`
API Gateway 建立集成连接到接收第一个内容字节之间的时间间隔。
`$context.integration.latency` 或 `$context.integrationLatency`
从 API Gateway 建立集成连接到集成响应流完成之间间隔的时间。
下图展示了这些访问日志变量如何表示响应流的不同组成部分。
![\[API Gateway 中响应流的访问日志变量\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/response-streaming-figure.png)
有关访问日志的更多信息，请参阅 [为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)。您也可以使用 X-Ray 来监控您的响应流。有关更多信息，请参阅 [在 API Gateway 中使用 X-Ray 跟踪用户对 REST API 的请求](apigateway-xray.md)。
# 针对 API Gateway 中的 REST API 的私有集成
通过私有集成，可将 Amazon VPC 内的 HTTP/HTTPS 资源暴露给 VPC 外的客户端访问。这会将对私有 VPC 资源的访问扩展到 VPC 边界之外。您可以使用 API Gateway 支持的任何[授权方法](apigateway-control-access-to-api.md)来控制对 API 的访问。
要创建私有集成，您必须首先创建 VPC 链接。API Gateway 支持用于 REST API 的 VPC 链接 V2。VPC 链接 V2 允许您创建私有集成，无需使用网络负载均衡器即可将 REST API 连接到应用程序负载均衡器。使用应用程序负载均衡器可以连接到 Amazon ECS 基于容器的应用程序和许多其他后端。VPC 链接 V1 被视为传统集成类型。虽然 API Gateway 支持这些类型，但建议您不要创建新的 VPC 链接 V1。
## 注意事项
以下注意事项可能会影响您对私有集成的使用：
+ 所有资源必须由同一 AWS 账户拥有。这包括负载均衡器、VPC 链接和 REST API。
+ 默认情况下，私有集成流量使用 HTTP 协议。要使用 HTTPS，请指定包含安全服务器名称的 [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)，例如 `https://example.com:443/test`。
+ 在私有集成中，API Gateway 会在发送给后端资源的请求中包括 API 端点的[阶段](set-up-stages.md)部分。例如，若请求 API 的 `test` 阶段，API Gateway 会在发送给私有集成的请求中包含 `test/path`。如需从发送给后端资源的请求中移除阶段名称，可通过[参数映射](rest-api-parameter-mapping.md)覆盖 `$context.requestOverride.path` 变量。
+ 不支持与 AWS Cloud Map 的私有集成。
**Topics**
+ [注意事项](#private-integrations-considerations)
+ [在 API Gateway 中设置 VPC 链接 V2](apigateway-vpc-links-v2.md)
+ [设置私有集成](set-up-private-integration.md)
+ [使用 VPC 链接 V1 的私有集成（旧版）](vpc-links-v1.md)
# 在 API Gateway 中设置 VPC 链接 V2
通过 VPC 链接，您可以创建私有集成，将 API 路由连接到 VPC 中的私有资源，例如应用程序负载均衡器或基于 Amazon ECS 容器的应用程序。私有集成使用 VPC 链接 V2 来封装 API Gateway 与目标 VPC 资源之间的连接。您可以跨不同的资源和 API 重用 VPC 链接。
创建 VPC 链接时，API Gateway 在您的账户中为 VPC 链接 V2 创建和管理[弹性网络接口](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)。此过程可能耗时数分钟。当 VPC 链接 V2 可供使用时，其状态将从 `PENDING` 转换为 `AVAILABLE`。
**注意**
如果 60 天内未通过 VPC 链接发送任何流量，其状态会变为 `INACTIVE`。当 VPC 链接处于 `INACTIVE` 状态时，API Gateway 删除 VPC 链接的所有网络接口。这会导致依赖于 VPC 链接的 API 请求失败。如果 API 请求恢复，API Gateway 将重新预置网络接口。创建网络接口和重新激活 VPC 链接可能需要几分钟时间。您可以使用 VPC 链接状态来监控 VPC 链接的状态。
## 使用 AWS CLI 创建 VPC 链接 V2
要创建 VPC 链接 V2，涉及的所有资源必须由同一 AWS 账户拥有。使用以下 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) 命令创建 VPC 链接：
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**注意**
VPC 链接 V2 是不可变的。创建 VPC 链接 V2 后，您无法更改其子网或安全组。
## 使用 AWS CLI 删除 VPC 链接 V2
使用以下 [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) 命令删除 VPC 链接。
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## 按区域的可用性
以下区域和可用区支持 VPC 链接 V2：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# 设置私有集成
要创建与应用程序负载均衡器或网络负载均衡器的私有集成，请创建 HTTP 代理集成，指定要使用的 [VPC 链接 V2](apigateway-vpc-links-v2.md)，并提供网络负载均衡器或应用程序负载均衡器的 ARN。默认情况下，私有集成流量使用 HTTP 协议。要使用 HTTPS，请指定包含安全服务器名称的 [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)，例如 `https://example.com:443/test`。有关如何创建使用私有集成的 REST API 的完整教程，请参阅[教程：利用私有集成创建 REST API](getting-started-with-private-integration.md)。
## 创建私有集成
以下步骤介绍如何创建私有集成，该私有集成通过 VPC 链接 V2 连接到负载均衡器。
------
#### [ AWS 管理控制台 ]
有关如何创建私有集成的教程，请参阅[教程：利用私有集成创建 REST API](getting-started-with-private-integration.md)。
------
#### [ AWS CLI ]
以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令创建私有集成，该集成通过 VPC 链接 V2 连接到负载均衡器：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
您可以改用阶段变量，而不是直接提供连接 ID。将 API 部署到阶段时，您要设置 VPC 链接 V2 ID。以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令对 VPC 链接 V2 ID 使用阶段变量来创建私有集成：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
确保使用双引号括起阶段变量表达式（\$1\$1stageVariables.vpcLinkV2Id\$1）并转义 \$1 字符。
------
#### [ OpenAPI ]
您可以通过导入 API 的 OpenAPI 文件，设置具有私有集成的 API。其设置类似于具有 HTTP 集成的 API 的 OpenAPI 定义，但有以下例外：
+ 您必须明确将 `connectionType` 设置为 `VPC_LINK`。
+ 您必须明确将 `connectionId` 设置为 `VpcLinkV2` 的 ID 或者设置为引用 `VpcLinkV2` 的 ID 的阶段变量。
+ 私有集成中的 `uri` 参数指向 VPC 中的 HTTP/HTTPS 端点，但是用于设置集成请求的 `Host` 标头。
+ 在 VPC 中，使用具有 HTTPS 端点的私有集成中的 `uri` 参数，根据在 VPC 端点上已安装证书中的名称验证所述域名。
您可以使用阶段变量来引用 `VpcLinkV2` ID。或者，您可以将 ID 值直接分配到 `connectionId`。
以下 JSON 格式的 OpenAPI 文件显示的示例中，API 具有 VPC 链接，通过阶段变量 (`${stageVariables.vpcLinkIdV2}`) 来引用：
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 更新私有集成
以下示例更新私有集成的 VPC 链接 V2。
------
#### [ AWS 管理控制台 ]
**更新私有集成**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择使用私有集成的 REST API。
1. 选择使用私有集成的资源和方法。
1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。
1. 您可以编辑私有集成的设置。如果您当前使用的是 VPC 链接 V1，则可以将您的 VPC 链接更改为 VPC 链接 V2。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ AWS CLI ]
以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) 命令将私有集成更新为使用 VPC 链接 V2：
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# 使用 VPC 链接 V1 的私有集成（旧版）
**注意**
以下私有集成实现使用 VPC 链接 V1。VPC 链接 V1 是旧版资源。建议您将 [VPC 链接 V2 用于 REST API](apigateway-vpc-links-v2.md)。
要创建私有集成，您必须首先创建网络负载均衡器。您的网络负载均衡器必须具有可将请求路由到 VPC 中的资源的[侦听器](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)。要提高 API 的可用性，请确保网络负载均衡器将流量路由到 AWS 区域 中多个可用性区域中的资源。然后，您创建一个 VPC 链接，来连接 API 和网络负载均衡器。创建 VPC 链接后，您可以创建私有集成，从而通过 VPC 链接和网络负载均衡器将流量从 API 路由到 VPC 中的资源。网络负载均衡器和 API 必须归同一个 AWS 账户所有。
**Topics**
+ [为 API Gateway 私有集成设置网络负载均衡器（旧版）](set-up-nlb-for-vpclink-using-console.md)
+ [授予 API Gateway 创建 VPC 链接的权限（旧版）](grant-permissions-to-create-vpclink.md)
+ [使用 AWS CLI 设置具有私有集成的 API Gateway API（旧版）](set-up-api-with-vpclink-cli.md)
+ [用于私有集成的 API Gateway 账户（旧版）](set-up-api-with-vpclink-accounts.md)
# 为 API Gateway 私有集成设置网络负载均衡器（旧版）
**注意**
以下私有集成实现使用 VPC 链接 V1。VPC 链接 V1 是旧版资源。建议您将 [VPC 链接 V2 用于 REST API](apigateway-vpc-links-v2.md)。
以下过程概述使用 Amazon EC2 控制台为 API Gateway 私有集成设置网络负载均衡器 (NLB) 的步骤，并提供对各个步骤的详细说明的参考。
对于其中包含有您的资源的每个 VPC，您只需要配置一个 NLB 和一个 VPCLink。NLB 支持每个 NLB 有多个[侦听器](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html)和[目标组](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html)。您可以在 NLB 上将每个服务配置成为一个特定的侦听器，然后使用一个 VPCLink 连接到 NLB。在 API Gateway 中创建私有集成时，您随后可以定义每个服务使用已为各个服务分配的特定端口。有关更多信息，请参阅 [教程：利用私有集成创建 REST API](getting-started-with-private-integration.md)。网络负载均衡器和 API 必须归同一个 AWS 账户所有。
**使用 API Gateway 控制台为私有集成创建网络负载均衡器**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon EC2 控制台：[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 在 Amazon EC2 实例上设置 Web 服务器。如需示例设置，请参阅[在 Amazon Linux 2 上安装 LAMP Web 服务器](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html)。
1. 创建网络负载均衡器，将 EC2 实例注册到目标组，然后将目标组添加到网络负载均衡器的侦听器。有关详细信息，请参阅[网络负载均衡器入门](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html)中的说明。
1. 创建网络负载均衡器之后，执行以下操作：
1. 记录网络负载均衡器的 ARN。您需要它在 API Gateway 中创建 VPC 链接，用于将 API 与位于网络负载均衡器之后的 VPC 资源集成。
1. 关闭 PrivateLink 的安全组评估。
+ 要使用控制台关闭对 PrivateLink 流量的安全组评估，可以选择**安全**选项卡，然后选择**编辑**。在**安全设置**下，清除**对 PrivateLink 流量强制执行入站规则**。
+ 要关闭对 PrivateLink 流量的安全组评估，请使用以下 [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) 命令：
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**注意**
请勿向 API Gateway CIDR 添加任何依赖项，因为这些依赖项必然会未经通知而更改。
# 授予 API Gateway 创建 VPC 链接的权限（旧版）
**注意**
以下私有集成实现使用 VPC 链接 V1。VPC 链接 V1 是旧版资源。建议您将 [VPC 链接 V2 用于 REST API](apigateway-vpc-links-v2.md)。
对于您或者您账户中的用户，如果要创建和维护 VPC 链接，您或者用户必须有权创建、删除和查看 VPC 端点服务配置，更改 VPC 端点服务权限，以及检查负载均衡器。要授予此类权限，请使用以下步骤。
**授予创建、更新和删除 VPC 链接的权限**
1. 创建类似于以下的 IAM 策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
如果您要为 VPC 链接启用标记，请确保允许标记操作。有关更多信息，请参阅 [允许标记操作](apigateway-tagging-iam-policy.md#allow-tagging)。
1. 创建或选择 IAM 角色并将前述策略附加到角色。
1. 将 IAM 角色分配给您或您账户中创建 VPC 链接的用户。
# 使用 AWS CLI 设置具有私有集成的 API Gateway API（旧版）
**注意**
以下私有集成实现使用 VPC 链接 V1。VPC 链接 V1 是旧版资源。建议您将 [VPC 链接 V2 用于 REST API](apigateway-vpc-links-v2.md)。
以下教程演示了如何使用 AWS CLI 创建 VPC 链接和私有集成。需要满足以下先决条件：
+ 您需要创建并配置了一个以 VPC 源为目标的网络负载均衡器。有关更多信息，请参阅 [为 API Gateway 私有集成设置网络负载均衡器（旧版）](set-up-nlb-for-vpclink-using-console.md)。这必须与您的 API 位于同一个 AWS 账户中。您需要网络负载均衡器 ARN 来创建 VPC 链接。
+ 要创建和管理 `VpcLink`，您必须具有在 API 中创建 `VpcLink` 的权限。您不需要具有使用 `VpcLink` 的权限。有关更多信息，请参阅 [授予 API Gateway 创建 VPC 链接的权限（旧版）](grant-permissions-to-create-vpclink.md)。
**使用 AWS CLI 设置具有私有集成的 API**
1. 使用以下 [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) 命令创建以指定的网络负载均衡器作为目标的 `VpcLink`：
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
此命令的输出确认收到请求并显示正在创建的 `VpcLink` 的 `PENDING` 状态。
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
API Gateway 需要 2-4 分钟才能完成创建 `VpcLink`。操作成功完成后，`status` 为 `AVAILABLE`。您可以通过调用以下 [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) 命令来验证这一点：
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
如果操作失败，您将收到 `FAILED` 状态，以及包含错误消息的 `statusMessage`。例如，如果您尝试使用已经与 VPC 端点关联的网络负载均衡器创建 `VpcLink`，在 `statusMessage` 属性上将获得以下内容：
```
"NLB is already associated with another VPC Endpoint Service"
```
在成功创建 `VpcLink` 之后，您可以创建 API 并通过 `VpcLink` 将其与 VPC 资源集成。
记下新创建的 `VpcLink` 的 `id` 值。在此示例输出中，它是 `gim7c3`。设置私有集成时需要该值。
1. 使用以下 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 命令创建 API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源：
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
请记录返回结果中 `RestApi` 的 `id` 值和 `RestApi` 的 `rootResourceId` 值。您需要该值才能在 API 上进一步执行操作。
接下来，我们将在根资源（`/`）上创建仅具有 `GET` 方法的 API，并将方法与 `VpcLink` 集成。
1. 使用以下 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 命令创建 `GET /` 方法：
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
如果您不将代理集成用于 `VpcLink`，则还必须至少设置 `200` 状态代码的一个方法响应。您在这里使用代理集成。
1. 创建 `GET /` 方法后，即可设置集成。对于私有集成，请使用 `connection-id` 参数来提供 `VpcLink` ID。您可以使用阶段变量或直接输入 `VpcLink` ID。`uri` 参数不用于将请求路由到端点，而是用于设置 `Host` 标头和证书验证。
------
#### [ Use the VPC link ID ]
使用以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 命令，在集成中直接使用 `VpcLink` ID：
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
使用以下 [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) 命令，来使用阶段变量引用 VPC 链接 ID。将 API 部署到阶段时，您要设置 VPC 链接 ID。
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
请确保使用双引号括起阶段变量表达式 (`${stageVariables.vpcLinkId}`) 并转义 `$` 字符。
------
也可以随时更新集成来更改 `connection-id`。使用以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 命令更新集成：
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
请确保使用字符串化的 JSON 列表作为 `patch-operations` 参数值。
由于您使用了私有代理集成，因此 API 现已准备好，可用于部署和测试运行。
1. 如果您使用了阶段变量来定义 `connection-id`，则需要部署 API 来对其进行测试。使用以下 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 命令，部署具有阶段变量的 API：
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
要使用不同 `VpcLink` ID（例如 `asf9d7`）更新阶段变量，请使用以下 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 命令：
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
使用 `VpcLink` ID 文本对 `connection-id` 属性进行硬编码时，无需部署 API 来对其进行测试。在部署 API 之前，使用 [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) 命令对其进行测试。
1. 使用以下命令来调用 API：
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
此外，您可以在 Web 浏览器中输入 API 的调用 URL 来查看结果。
# 用于私有集成的 API Gateway 账户（旧版）
在创建 `VpcLink` 时，以下特定于区域的 API Gateway 账户 ID 会作为 `AllowedPrincipals` 自动添加到 VPC 端点服务中。
| **区域** | **账户 ID** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# 针对 API Gateway 中的 REST API 的模拟集成
Amazon API Gateway 支持 API 方法的模拟集成。借助该特征，API 开发人员可以直接从 API Gateway 生成 API 响应，无需集成后端。作为 API 开发人员，您可以在项目开发结束之前使用此特征，以便不妨碍需要使用 API 开展工作的相关团队。您还可以使用此特征来预配置 API 的登录页面，该网页可提供您的 API 概述和导航。有关此类登录页面的示例，请参阅 中所述示例 API 的根资源上 GET 方法的集成请求和响应[教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)
作为 API 开发人员，您可以决定 API Gateway 响应模拟集成的方式。为此，您可以配置方法的集成请求和集成响应，以将响应与给定的状态代码相关联。对于具有模拟集成以返回 `200` 响应的方法，请配置集成请求正文映射模板以返回下列内容。
```
{"statusCode": 200}
```
配置 `200` 集成响应以具有以下正文映射模板，例如：
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
与此类似，举例而言，对于返回 `500` 错误响应的方法，请设置集成请求正文映射模板以返回下列内容。
```
{"statusCode": 500}
```
例如，使用以下映射模板设置 `500` 集成响应：
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
或者，您可以让模拟集成的方法返回默认集成响应，无需定义集成请求映射模板。默认集成响应是具有未定义 **HTTP status regex (HTTP 状态正则表达式)** 的响应。请确保设置了合适的传递行为。
**注意**
模拟集成并非用于支持大型响应模板。如果您的使用案例需要它们，您应该考虑改为使用 Lambda 集成。
使用集成请求映射模板，您可以注入应用程序逻辑，用来确定基于特定条件返回什么模拟集成响应。例如，您可以在传入请求上使用 `scope` 查询参数来确定返回成功响应还是错误响应：
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
这样，模拟集成的方法让内部调用通过，同时拒绝其他类型的调用并提供错误响应。
本部分介绍如何使用 API Gateway 控制台来启用 API 方法模拟集成。
**Topics**
+ [使用 API Gateway 控制台启用模拟集成](how-to-mock-integration-console.md)
# 使用 API Gateway 控制台启用模拟集成
您必须在 API Gateway 中有一个可用的方法。按照[教程：使用 HTTP 非代理集成创建 REST API](api-gateway-create-api-step-by-step.md)中的说明进行操作。
1. 选择 API 资源，然后选择**创建方法**。
要创建方法，请执行以下操作：
1. 对于**方法类型**，选择一种方法。
1. 对于**集成类型**，选择**模拟**。
1. 选择**创建方法**。
1. 在**方法请求**选项卡上，对于**方法请求设置**，选择**编辑**。
1. 选择 **URL 查询字符串参数**。选择**添加查询字符串**，然后为**名称**中输入 **scope**。此查询参数确定调用方是否为内部。
1. 选择**保存**。
1. 在**方法响应**选项卡上，选择**创建响应**，然后执行以下操作：
1. 对于 **HTTP 状态**，输入 **500**。
1. 选择**保存**。
1. 在**集成请求**选项卡上，对于**集成请求设置**，选择**编辑**。
1. 选择**映射模板**，然后执行以下操作：
1. 选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. 选择**保存**。
1. 在**集成响应**选项卡上，对于**默认 - 响应**，选择**编辑**。
1. 选择**映射模板**，然后执行以下操作：
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. 选择**保存**。
1. 选择**创建响应**。
要创建 500 响应，请执行以下操作：
1. 对于 **HTTP 状态正则表达式**，输入 **5\$1d\$12\$1**。
1. 对于**方法响应状态**，选择 **500**。
1. 选择**保存**。
1. 对于 **5\$1d\$12\$1 - 响应**，选择**编辑**。
1. 选择**映射模板**，然后选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. 选择**保存**。
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。要测试模拟集成，请执行以下操作：
1. 在**查询字符串**下，输入 `scope=internal`。选择 **Test (测试)**。测试结果显示：
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. 在 `scope=public` 下输入 `Query strings` 或将其留空。选择 **Test (测试)**。测试结果显示：
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
您也可以首先将标头添加到方法响应，然后在集成响应中设置标头映射，从而在模拟集成响应中返回标头。实际上，这是 API Gateway 控制台通过返回 CORS 需要的标头来启用 CORS 支持的方法。
# 针对 API Gateway 中的 REST API 的请求验证
您可以配置 API Gateway，使其在处理集成请求之前对 API 请求执行基本验证。如果验证失败，API Gateway 会立即取消请求、向调用方返回 400 错误响应，并在 CloudWatch Logs 中发布验证结果。这可以减少对后端进行的不必要调用。更重要的是，它可以让您把精力集中在特定于应用程序的验证工作上。您可以通过验证所需请求参数是否有效并且不为空，或为更复杂的数据验证指定一个模型架构，从而验证请求正文。
**Topics**
+ [API Gateway 中的基本请求验证概览](#api-gateway-request-validation-basic-definitions)
+ [针对 REST API 的数据模型](models-mappings-models.md)
+ [在 API Gateway 中设置基本请求验证](api-gateway-request-validation-set-up.md)
+ [AWS CloudFormation 模板，提供带有基本请求验证的示例 API](api-gateway-request-validation-sample-cloudformation.md)
## API Gateway 中的基本请求验证概览
API Gateway 可以执行基本请求验证，以便您可以专注于后端的应用程序特定验证。进行验证时，API Gateway 验证以下一项或两项条件：
+ 传入请求的 URI、查询字符串和标头中带有所需的请求参数且都不为空。API Gateway 仅检查参数是否存在，而不检查类型或格式。
+ 适用的请求有效载荷遵循对应于给定内容类型的方法的已配置 [JSON schema](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) 请求。如果未找到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请将数据模型的内容类型设置为 `$default`。
要开启验证，您需要在[请求验证程序](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)中指定验证规则，将验证程序添加到 API 的[请求验证程序的映射](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)中，并将验证程序分配给各个 API 方法。
**注意**
请求正文验证和[API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)是两个独立的主题。当请求负载没有匹配的模型架构时，可以选择传递或阻止原始负载。有关更多信息，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
# 针对 REST API 的数据模型
在 API Gateway 中，模型定义负载的数据结构。在 API Gateway 中，使用 [JSON 架构草案 4](https://tools.ietf.org/html/draft-zyp-json-schema-04) 定义模型。以下 JSON 对象是 Pet Store 示例中的示例数据。
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
数据包含宠物的 `id`、`type` 和 `price`。这些数据的模型允许您：
+ 使用基本请求验证。
+ 创建用于数据转换的映射模板。
+ 生成 SDK 时创建用户定义的数据类型（UDT）。
![\[PetStore API 的示例 JSON 数据模型。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/how-to-validate-requests.png)
在这个模型中：
1. `$schema` 对象表示一个有效的 JSON 架构版本标识符。此架构为 JSON 架构草案 v4。
1. `title` 对象是人类可读的模型标识符。此标题是 `PetStoreModel`。
1. `required` 验证关键字要求使用 `type` 和 `price` 进行基本请求验证。
1. 模型的 `properties` 为 `id`、`type` 和 `price`。每个对象都有模型中描述的属性。
1. 对象 `type` 只能具有值 `dog`、`cat` 或 `fish`。
1. 对象 `price` 是一个数字，并受 `minimum` 为 25 和 `maximum` 为 500 所限制。
## PetStore 模型
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
在这个模型中：
1. 在第 2 行上，`$schema` 对象表示一个有效的 JSON 架构版本标识符。此架构为 JSON 架构草案 v4。
1. 在第 3 行上，`title` 对象是用户可读的模型标识符。此标题是 `PetStoreModel`。
1. 在第 5 行上，`required` 验证关键字要求使用 `type` 和 `price` 进行基本请求验证。
1. 在第 6 -- 17 行上，模型的 `properties` 为 `id`、`type` 和 `price`。每个对象都有模型中描述的属性。
1. 在第 12 行上，对象 `type` 只能具有值 `dog`、`cat` 或 `fish`。
1. 在第 14 -- 17 行上，对象 `price` 是一个数字，并受 `minimum` 为 25 和 `maximum` 为 500 所限制。
## 创建更复杂的模型
您可以使用 `$ref` 基元为较长的模型创建可重复使用的定义。例如，可以在描述 `price` 对象的 `definitions` 部分中创建称为 `Price` 的定义。`$ref` 的值是 `Price` 定义。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
您也可以引用在外部模型文件中定义的另一个模型架构。将 `$ref` 属性的值设置为模型的位置。在以下示例中，`Price` 模型是在 API `a1234` 的 `PetStorePrice` 模型中定义的。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
较长的模型可以引用 `PetStorePrice` 模型。
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## 使用输出数据模型
如果您转换数据，则可以在集成响应中定义负载模型。生成 SDK 时可以使用负载模型。对于强类型语言（如 Java、Objective-C 或 Swift），对象对应于用户定义的数据类型 (UDT)。如果您在生成 SDK 时向其提供数据模型，API Gateway 将创建 UDT。有关数据转换的更多信息，请参阅[API Gateway 中 REST API 的映射模板转换](models-mappings.md)。
以下示例是来自集成响应的输出数据。
```
{
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
}
```
以下示例是描述输出数据的负载模型。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
借助此模型，您可以调用 SDK，以便通过读取 `PetStoreOutputModel[i].description` 和 `PetStoreOutputModel[i].askingPrice` 属性来检索 `description` 和 `askingPrice` 属性值。如果未提供模型，API Gateway 将使用空模型创建默认 UDT。
## 后续步骤
+ 本节提供的资源可用于获得有关本主题中介绍的概念的更多知识。
您可以按照请求验证教程进行操作：
+ [使用 API Gateway 控制台设置请求验证](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [使用 AWS CLI 设置基本请求验证](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [使用 OpenAPI 定义设置基本请求验证](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ 有关数据转换和映射模板的更多信息，请参阅[API Gateway 中 REST API 的映射模板转换](models-mappings.md)。
# 在 API Gateway 中设置基本请求验证
本节介绍如何使用控制台、AWS CLI 和 OpenAPI 定义为 API Gateway 设置请求验证。
**Topics**
+ [使用 API Gateway 控制台设置请求验证](#api-gateway-request-validation-setup-in-console)
+ [使用 AWS CLI 设置基本请求验证](#api-gateway-request-validation-setup-cli)
+ [使用 OpenAPI 定义设置基本请求验证](#api-gateway-request-validation-setup-importing-swagger)
## 使用 API Gateway 控制台设置请求验证
您可以使用 API Gateway 控制台从 API 请求的三个验证程序中选择一个来验证请求：
+ **验证正文**。
+ **验证查询字符串参数和标头**。
+ **验证正文、查询字符串参数和标头**。
当您对 API 方法应用以上一种验证程序时，API Gateway 控制台会向 API 的 [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) 映射添加该验证程序。
要按本教程操作，您将使用 CloudFormation 模板来创建不完整的 API Gateway API。此 API 拥有的 `/validator` 资源具有 `GET` 和 `POST` 方法。两种方法都与 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端点集成。您将配置两种请求验证：
+ 在 `GET` 方法中，您将为 URL 查询字符串参数配置请求验证。
+ 在 `POST` 方法中，您将为请求正文配置请求验证。
这将只允许特定的 API 调用传递给 API。
下载并解压缩[适用于 CloudFormation 的应用程序创建模板](samples/request-validation-tutorial-console.zip)。您将使用此模板创建不完整的 API。您将在 API Gateway 控制台中完成其余步骤。
**创建 CloudFormation 堆栈**
1. 打开 CloudFormation 控制台，地址：[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 选择**创建堆栈**，然后选择**使用新资源(标准)**。
1. 对于**指定模板**，选择**上传模板文件**。
1. 选择您下载的模板。
1. 选择**下一步**。
1. 对于**堆栈名称**，输入 **request-validation-tutorial-console**，然后选择**下一步**。
1. 对于**配置堆栈选项**，请选择**下一步**。
1. 对于**功能**，请确认 CloudFormation 可以在您的账户中创建 IAM 资源。
1. 选择**下一步**，然后选择**提交**。
CloudFormation 预置在模板中指定的资源。完成资源预置可能需要几分钟时间。当 CloudFormation 堆栈的状态为 **CREATE\$1COMPLETE** 时，您就可以继续下一步了。
**选择您新创建的 API**
1. 选择新创建的 **request-validation-tutorial-console** 堆栈。
1. 选择**资源**。
1. 在**物理 ID** 下，选择您的 API。此链接将引导您进入 API Gateway 控制台。
在修改 `GET` 和 `POST` 方法之前，必须创建模型。
**创建模型**
1. 需要一个模型来对传入请求的正文使用请求验证。要创建模型，请在主导航窗格中选择**模型**。
1. 选择**创建模型**。
1. 对于**名称**，请输入 **PetStoreModel**。
1. 对于**内容类型**，输入 **application/json**。如果未找到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请输入 **\$1default**。
1. 对于**描述**，输入 **My PetStore Model** 作为模型描述。
1. 对于**模型架构**，将以下模型粘贴到代码编辑器中，然后选择**创建**。
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
有关模型的更多信息，请参阅[针对 REST API 的数据模型](models-mappings-models.md)。
**为 `GET` 方法配置请求验证**
1. 在主导航窗格中，选择**资源**，然后选择 **GET** 方法。
1. 在**方法请求**选项卡上的**方法请求设置**下，选择**编辑**。
1. 对于**请求验证程序**，选择**验证查询字符串参数和标头**。
1. 在 **URL 查询字符串参数**下，执行以下操作：
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **petType**。
1. 打开**必需**。
1. 将**缓存**保持为关闭状态。
1. 选择**保存**。
1. 在**集成请求**选项卡的**集成请求设置**下，选择**编辑**。
1. 在 **URL 查询字符串参数**下，执行以下操作：
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **petType**。
1. 对于**映射自**，输入 **method.request.querystring.petType**。这会将 **petType** 映射到宠物的类型。
有关数据映射的更多信息，请参阅[数据映射教程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
1. 将**缓存**保持为关闭状态。
1. 选择**保存**。
**为 `GET` 方法测试请求验证**
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 对于**查询字符串**，输入 **petType=dog**，然后选择**测试**。
1. 方法测试将返回 `200 OK` 并提供狗的列表。
有关如何转换此输出数据的信息，请参阅[数据映射教程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
1. 删除 **petType=dog** 并选择**测试**。
1. 方法测试将返回 `400` 错误并显示以下错误消息：
```
{
"message": "Missing required request parameters: [petType]"
}
```
**为 `POST` 方法配置请求验证**
1. 在主导航窗格中，选择**资源**，然后选择 **POST** 方法。
1. 在**方法请求**选项卡上的**方法请求设置**下，选择**编辑**。
1. 对于**请求验证程序**，选择**验证正文**。
1. 在**请求正文**下，选择**添加模型**。
1. 对于**内容类型**，输入 **application/json**。如果未找到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请输入 `$default`。
对于**模型**，请选择 **PetStoreModel**。
1. 选择**保存**。
**为 `POST` 方法测试请求验证**
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 对于**请求正文**，将以下内容粘贴到代码编辑器中：
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
选择**测试**。
1. 方法测试将返回 `200 OK` 和成功消息。
1. 对于**请求正文**，将以下内容粘贴到代码编辑器中：
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
选择**测试**。
1. 方法测试将返回 `400` 错误并显示以下错误消息：
```
{
"message": "Invalid request body"
}
```
在测试日志的底部，将返回请求正文无效的原因。在这种情况下，宠物的价格超出了模型中规定的最高价格。
**删除 CloudFormation 堆栈**
1. 打开 CloudFormation 控制台，地址：[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 选择您的 CloudFormation 堆栈。
1. 选择**删除**，然后确认您的选择。
### 后续步骤
+ 有关如何转换输出数据和执行更多数据映射的信息，请参阅[数据映射教程](set-up-data-transformations-in-api-gateway.md#mapping-example-console)。
+ 按照[使用 AWS CLI 设置基本请求验证](#api-gateway-request-validation-setup-cli)教程操作，使用 AWS CLI 执行类似的步骤。
## 使用 AWS CLI 设置基本请求验证
您可以使用 AWS CLI 创建验证程序来设置请求验证。要按本教程操作，您将使用 CloudFormation 模板来创建不完整的 API Gateway API。
**注意**
这与控制台教程的 CloudFormation 模板不同。
使用预先公开的 `/validator` 资源，您将创建 `GET` 和 `POST` 方法。两种方法都将与 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端点集成。您将配置以下两个请求验证：
+ 在 `GET` 方法上，您将创建一个 `params-only` 验证程序来验证 URL 查询字符串参数。
+ 在 `POST` 方法上，您将创建一个 `body-only` 验证程序来验证请求正文。
这将只允许特定的 API 调用传递给 API。
**创建 CloudFormation 堆栈**
下载并解压缩[适用于 CloudFormation 的应用程序创建模板](samples/request-validation-tutorial-cli.zip)。
要完成以下教程，您需要 [AWS Command Line Interface（AWS CLI）版本 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
对于长命令，使用转义字符 (`\`) 将命令拆分为多行。
**注意**
在 Windows 中，操作系统的内置终端不支持您经常使用的某些 Bash CLI 命令（例如 `zip`）。[安装 Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)，获取 Ubuntu 和 Bash 与 Windows 集成的版本。本指南中的示例 CLI 命令使用 Linux 格式。如果您使用的是 Windows CLI，则必须重新格式化包含内联 JSON 文档的命令。
1. 输入以下命令创建 CloudFormation 堆栈。
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation 预置在模板中指定的资源。完成资源预置可能需要几分钟时间。使用以下命令查看 CloudFormation 的状态。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. 当 CloudFormation 堆栈的状态为 `StackStatus: "CREATE_COMPLETE"` 时，使用以下命令检索将来步骤的相关输出值。
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
输出值包括：
+ ApiId，这是 API 的 ID。对于本教程，API ID 为 `abc123`。
+ ResourceId，这是在其中公开 `GET` 和 `POST` 方法的验证程序资源的 ID。对于本教程，资源 ID 为 `efg456`
**创建请求验证程序并导入模型**
1. 需要验证程序才能通过 AWS CLI 使用请求验证。使用以下命令创建仅验证请求参数的验证程序。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
记下 `params-only` 验证程序的 ID。
1. 使用以下命令创建仅验证请求正文的验证程序。
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
记下 `body-only` 验证程序的 ID。
1. 需要一个模型来对传入请求的正文使用请求验证。使用以下命令导入模型。
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
如果未找到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请指定 `$default` 作为键。
**创建 `GET` 和 `POST` 方法**
1. 使用以下命令对 `/validate` 资源添加 `GET` HTTP 方法。此命令创建 `GET` 方法，添加 `params-only` 验证程序，并根据需要设置查询字符串 `petType`。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
使用以下命令对 `/validate` 资源添加 `POST` HTTP 方法。此命令创建 `POST` 方法，添加 `body-only` 验证程序，并将模型附加到仅限正文的验证程序。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. 使用以下命令设置 `GET /validate` 方法的 `200 OK` 响应。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
使用以下命令设置 `POST /validate` 方法的 `200 OK` 响应。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 使用以下命令通过指定的 HTTP 端点为 `GET /validation` 方法设置 `Integration`。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
使用以下命令通过指定的 HTTP 端点为 `POST /validation` 方法设置 `Integration`。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. 使用以下命令设置 `GET /validation` 方法的集成响应。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
使用以下命令设置 `POST /validation` 方法的集成响应。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**测试 API**
1. 要测试将对查询字符串执行请求验证的 `GET` 方法，请使用以下命令：
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
结果将返回 `200 OK` 和狗的列表。
1. 使用以下命令在不包含查询字符串 `petType` 的情况下进行测试
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
结果将返回 `400` 错误。
1. 要测试将对请求正文执行请求验证的 `POST` 方法，请使用以下命令：
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
结果将返回 `200 OK` 和一条成功消息。
1. 使用以下命令通过无效的正文进行测试。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
结果将返回 `400` 错误，因为狗的价格超过了模型定义的最高价格。
**删除 CloudFormation 堆栈**
+ 使用以下命令删除您的 CloudFormation 资源。
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## 使用 OpenAPI 定义设置基本请求验证
您可以在 API 级别声明请求验证程序，方法是在 [x-amazon-apigateway-request-validators 对象](api-gateway-swagger-extensions-request-validators.md) 映射中指定一组 [x-amazon-apigateway-request-validators.requestValidator 对象](api-gateway-swagger-extensions-request-validators.requestValidator.md) 对象，以选择将对请求的哪个部分进行验证。在示例 OpenAPI 定义中，有两个验证程序：
+ `all` 验证程序，它验证正文（使用 `RequestBodyModel` 数据模型）和参数。
`RequestBodyModel` 数据模型要求输入 JSON 对象包含 `name`、`type` 和 `price` 属性。`name` 属性可以是任何字符串，`type` 必须是一种指定枚举字段 (`["dog", "cat", "fish"]`)，而 `price` 必须介于 25 和 500 之间。`id` 参数不是必需参数。
+ `param-only`，它只验证参数。
要在 API 的所有方法上开启请求验证程序，请在 API 级别指定 OpenAPI 定义的 [x-amazon-apigateway-request-validator 属性](api-gateway-swagger-extensions-request-validator.md) 属性。在示例 OpenAPI 定义中，`all` 验证器用于所有 API 方法，除非被覆盖。使用模型验证正文时，如果找不到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请指定 `$default` 作为键。
要针对单独的方法开启请求验证程序，请在方法级别指定 `x-amazon-apigateway-request-validator` 属性。在示例 OpenAPI 定义中，`param-only` 验证程序会覆盖 `GET` 方法上的 `all` 验证程序。
要将 OpenAPI 示例导入 API Gateway，请参阅以下有关[将区域 API 导入到 API Gateway 中](import-export-api-endpoints.md)或[将边缘优化的 API 导入 API Gateway](import-edge-optimized-api.md)的说明。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# AWS CloudFormation 模板，提供带有基本请求验证的示例 API
以下 CloudFormation 示例模板定义一个启用了请求验证的示例 API。该 API 是 [PetStore API](http://petstore-demo-endpoint.execute-api.com/petstore/pets) 的一部分。其使用 `POST` 方法将宠物添加到 `pets` 集合，并使用 `GET` 方法按指定类型查询宠物。
其中声明了两个请求验证程序：
**`GETValidator`**
此验证程序已在 `GET` 方法上启用。它允许 API Gateway 验证所需的查询参数 (`q1`) 是否包含在传入请求内且不为空。
**`POSTValidator`**
此验证程序已在 `POST` 方法上启用。它允许 API Gateway 在内容类型为 `application/json` 时，验证负载请求格式是否遵循指定的 `RequestBodyModel`，如果未找到匹配的内容类型，则不执行请求验证。要使用同一模型而不考虑内容类型，请指定`$default`。`RequestBodyModel` 包含一个额外的模型 `RequestBodyModelId`，用于定义宠物 ID。
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# 针对 API Gateway 中 REST API 的数据转换
**注意**
本节介绍您在非代理集成中使用的功能。但是，我们建议您尽可能为 REST API 使用代理集成。代理集成具有简化的集成设置，可以随后端演变，而无需停用现有设置。有关更多信息，请参阅 [选择 API Gateway API 集成类型](api-gateway-api-integration-types.md)。
如果您使用非代理集成，则可以使用 API Gateway 的两个功能来转换方法请求和集成响应。如果方法请求采用的有效载荷格式与集成请求有效载荷不同，则可以对方法请求进行转换。如果集成响应返回的有效载荷格式与您需要在方法响应中返回的格式不同，则可以对集成响应进行转换。有关请求生命周期的更多信息，请参阅 [REST API 的示例资源](rest-api-develop.md#rest-api-develop-example)。
以下示例显示了一个数据转换，其中对于标头 `"x-version:beta"`，`x-version` 标头参数转换为 `app-version` 标头参数。从 `x-version` 到 `app-version` 的数据转换发生在集成请求中。这样，集成端点就会收到转换后的标头参数值。当集成端点返回状态代码时，状态代码将在方法响应之前从 `200` 转换为 `204`。
![\[API Gateway 数据转换图\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/develop-non-proxy.png)
要创建数据转换，可以使用以下功能：
**参数映射**
在参数映射中，可以修改集成请求 URL 路径参数、URL 查询字符串参数或 HTTP 标头值，但不能修改集成请求有效载荷。也可以修改 HTTP 响应标头值。使用参数映射为跨源资源共享（CORS）创建静态标头值。
您可以在代理和非代理集成的集成请求中使用参数映射，但要将参数映射用于集成响应，则需要非代理集成。参数映射不需要使用 [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 编写任何脚本。有关更多信息，请参阅 [API Gateway 中 REST API 的参数映射](rest-api-parameter-mapping.md)。
**映射模板转换**
在映射模板转换中，可以使用映射模板来映射 URL 路径参数、URL 查询字符串参数、HTTP 标头和集成请求或集成响应正文。**映射模板是使用 [JSONPath 表达式](https://goessner.net/articles/JsonPath/)以 [Velocity Template Language（VTL）](https://velocity.apache.org/engine/devel/vtl-reference.html)表示的脚本，并基于 `Content-type` 标头应用于有效载荷。
使用映射模板，您可以执行以下操作：
+ 选择要使用与 AWS 服务（例如 Amazon DynamoDB 或 Lambda 函数或 HTTP 端点）的集成发送哪些数据。有关更多信息，请参阅 [教程：修改集成请求和响应以集成到 AWS 服务](set-up-data-transformations-in-api-gateway.md)。
+ 有条件地覆盖 API 的集成请求和集成响应参数、创建新的标头值并覆盖状态代码。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。
当集成请求正文的 `Content-type` 标头没有匹配的映射模板时，还可以指定 API 的行为。这称为集成传递行为。有关更多信息，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
## 在参数映射与映射模板转换之间进行选择
我们建议您尽可能使用参数映射来转换数据。如果 API 要求您更改正文，或者要求您根据传入的集成请求或集成响应执行有条件覆盖和修改，并且您无法使用代理集成，请使用映射模板转换。
# API Gateway 中 REST API 的参数映射
**注意**
如果您使用的是 HTTP API，请参阅[针对 API Gateway 中的 HTTP API 转换 API 请求和响应](http-api-parameter-mapping.md)。
在参数映射中，您可以映射请求或响应参数。您可以使用参数映射表达式或静态值来映射参数。有关映射表达式的列表，请参阅 [API Gateway 中 REST API 的参数映射源参考](rest-api-parameter-mapping-sources.md)。您可以在代理和非代理集成的集成请求中使用参数映射，但要将参数映射用于集成响应，则需要非代理集成。
例如，您可以将方法请求标头参数 `puppies` 映射到集成请求标头参数 `DogsAge0`。然后，如果客户端将标头 `puppies:true` 发送到您的 API，则集成请求会将请求标头 `DogsAge0:true` 发送到集成端点。下图显示了此示例的请求生命周期。
![\[请求的 API Gateway 参数映射示例图\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
要使用 API Gateway 创建此示例，请参阅[示例 1：将方法请求参数映射到集成请求参数](request-response-data-mappings.md#request-response-data-mappings-example-1)。
再举一个例子，您也可以将集成响应标头参数 `kittens` 映射到方法响应标头参数 `CatsAge0`。然后，如果集成端点返回 `kittens:false`，则客户端将收到标头 `CatsAge0:false`。下图显示了此示例的请求生命周期。
![\[响应的 API Gateway 参数映射示例图\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [API Gateway 中 REST API 的参数映射示例](request-response-data-mappings.md)
+ [API Gateway 中 REST API 的参数映射源参考](rest-api-parameter-mapping-sources.md)
# API Gateway 中 REST API 的参数映射示例
以下示例显示如何使用 API Gateway 控制台、OpenAPI 和 CloudFormation 模板创建参数映射表达式。有关如何使用参数映射来创建所需 CORS 标头的示例，请参阅[针对 API Gateway 中的 REST API 的 CORS](how-to-cors.md)。
## 示例 1：将方法请求参数映射到集成请求参数
以下示例将方法请求标头参数 `puppies` 映射到集成请求标头参数 `DogsAge0`。
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 对于**方法请求设置**，选择**编辑**。
1. 选择 **HTTP 请求标头**。
1. 选择**添加标头**。
1. 对于**名称**，请输入 **puppies**。
1. 选择**保存**。
1. 选择**集成请求**选项卡，然后对于**集成请求设置**，选择**编辑**。
AWS 管理控制台会自动为您添加从 `method.request.header.puppies ` 到 `puppies` 的参数映射，但您需要更改**名称**，以匹配集成端点所期望的请求标头参数。
1. 对于**名称**，请输入 **DogsAge0**。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
以下步骤向您展示如何验证参数映射是否成功。
**（可选）测试参数映射**
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 对于标头，输入 **puppies:true**。
1. 选择**测试**。
1. 在**日志**中，结果应该类似以下内容：
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
请求标头参数已从 `puppies` 更改为 `DogsAge0`。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 示例 2：将多个方法请求参数映射到不同的集成请求参数
以下示例将多值方法请求查询字符串参数 `methodRequestQueryParam` 映射到集成请求查询字符串参数 `integrationQueryParam`，并将方法请求标头参数 `methodRequestHeaderParam` 映射到集成请求路径参数 `integrationPathParam`。
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 对于**方法请求设置**，选择**编辑**。
1. 选择 **URL 查询字符串参数**。
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **methodRequestQueryParam**。
1. 选择 **HTTP 请求标头**。
1. 选择**添加标头**。
1. 对于**名称**，请输入 **methodRequestHeaderParam**。
1. 选择**保存**。
1. 选择**集成请求**选项卡，然后对于**集成请求设置**，选择**编辑**。
1. 选择 **URL 路径参数**。
1. 选择**添加路径参数**。
1. 对于**名称**，请输入 **integrationPathParam**。
1. 对于**映射自**，输入 **method.request.header.methodRequestHeaderParam**。
这会将您在方法请求中指定的方法请求标头映射到新的集成请求路径参数。
1. 选择 **URL 查询字符串参数**。
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **integrationQueryParam**。
1. 对于**映射自**，输入 **method.request.multivaluequerystring.methodRequestQueryParam**。
这会将多值查询字符串参数映射到新的单值集成请求查询字符串参数。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
以下 OpenAPI 定义为 HTTP 集成创建以下参数映射：
+ 将方法请求的名为 `methodRequestHeaderParam` 的标头映射到名为 `integrationPathParam` 的集成请求路径参数
+ 将名为 `methodRequestQueryParam` 的多值方法请求查询字符串映射到名为 `integrationQueryParam` 的集成请求查询字符串
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义为 HTTP 集成创建以下参数映射：
+ 将方法请求的名为 `methodRequestHeaderParam` 的标头映射到名为 `integrationPathParam` 的集成请求路径参数
+ 将名为 `methodRequestQueryParam` 的多值方法请求查询字符串映射到名为 `integrationQueryParam` 的集成请求查询字符串
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 示例 3：将 JSON 请求正文中的字段映射到集成请求参数
还可以使用 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2) 从 JSON 请求正文中的字段映射集成请求参数。以下示例将方法请求正文映射到名为 `body-header` 的集成请求标头，并将部分请求正文（由 JSON 表达式表示）映射到名为 `pet-price` 的集成请求标头。
要测试此示例，请提供包含价格类别的输入，如下所示：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择 `POST`、`PUT`、`PATCH` 或 `ANY` 方法。
您的方法必须具有非代理集成。
1. 对于**集成请求设置**，选择**编辑**。
1. 选择 **URL 请求标头参数**。
1. 选择**添加请求标头参数**。
1. 对于**名称**，请输入 **body-header**。
1. 对于**映射自**，输入 **method.request.body**。
这会将方法请求正文映射到新的集成请求标头参数。
1. 选择**添加请求标头参数**。
1. 对于**名称**，请输入 **pet-price**。
1. 对于**映射自**，输入 ** method.request.body[0].price**。
这会将方法请求正文的一部分映射到新的集成请求标头参数。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义从 JSON 请求正文中的字段映射集成请求参数。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 示例 4：将集成响应映射到方法响应
还可以将集成响应映射到方法响应。以下示例将集成响应正文映射到名为 `location` 的方法响应标头，将集成响应标头 `x-app-id` 映射到方法响应标头 `id`，并将多值集成响应标头 `item` 映射到方法响应标头 `items`。
------
#### [ AWS 管理控制台 ]
**映射集成响应**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 选择**方法响应**选项卡，然后对于**响应 200** 选择**编辑**。
1. 对于**标头名称**，选择**添加标头**。
1. 创建三个名为 **id**、**item**、和 **location** 的标头。
1. 选择**保存**。
1. 选择**集成响应**选项卡，然后对于**默认 - 响应**，选择**编辑**。
1. 在**标头映射**下，输入以下内容。
1. 对于 **id**，输入 **integration.response.header.x-app-id**
1. 对于**项目**，输入 **integration.response.multivalueheader.item**
1. 对于**位置**，输入 **integration.response.body.redirect.url**
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义将集成响应映射到方法响应。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway 中 REST API 的参数映射源参考
创建参数映射时，可以指定要修改的方法请求或集成响应参数，并指定如何修改这些参数。
下表显示了可以映射的方法请求参数以及用于创建映射的表达式。在这些表达式中，*name* 是方法请求参数的名称。例如，要映射请求标头参数 `puppies`，请使用表达式 `method.request.header.puppies`。您的表达式必须与正则表达式 `'^[a-zA-Z0-9._$-]+$]'` 匹配。您可以在代理和非代理集成的集成请求中使用参数映射。
| **映射的数据来源** | **映射表达式** |
| --- | --- |
| 方法请求路径 | method.request.path.name |
| 方法请求查询字符串 | method.request.querystring.name |
| 多值方法请求查询字符串 | method.request.multivaluequerystring.name |
| 方法请求标头 | method.request.header.name |
| 多值方法请求标头 | method.request.multivalueheader.name |
| 方法请求正文 | method.request.body |
| 方法请求正文 (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* 是请求正文的 JSON 字段的 JSONPath 表达式。有关更多信息，请参阅 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 阶段变量 | stageVariables.name |
| 上下文变量 | `context.name` 名称必须为[受支持的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 静态值 | `'static_value'`. *static\$1value* 为字符串文本值，必须括在一对单引号内。例如 `'https://www.example.com'`。 |
下表显示了可以映射的集成响应参数以及用于创建映射的表达式。在这些表达式中，*name* 是集成响应参数的名称。您可以从任何集成响应标头或集成响应正文、\$1context 变量或静态值映射方法响应标头。要将参数映射用于集成响应，您需要使用非代理集成。
| 映射数据源 | 映射表达式 |
| --- | --- |
| 集成响应标头 | integration.response.header.name |
| 集成响应标头 | integration.response.multivalueheader.name |
| 集成响应正文 | integration.response.body |
| 集成响应正文 (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* 是响应正文的 JSON 字段的 JSONPath 表达式。有关更多信息，请参阅 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 阶段变量 | stageVariables.name |
| 上下文变量 | `context.name` 名称必须为[受支持的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 静态值 | ` 'static_value'` *static\$1value* 为字符串文本值，必须括在一对单引号内。例如 `'https://www.example.com'`。 |
# API Gateway 中 REST API 的映射模板转换
映射模板转换使用映射模板来修改集成请求或集成响应。**映射模板是以 [Velocity Template Language（VTL）](https://velocity.apache.org/engine/devel/vtl-reference.html)表示的脚本，并使用 [JSONPath](https://goessner.net/articles/JsonPath/) 基于 `Content-type` 标头应用于有效载荷。使用映射模板转换时使用映射模板。此部分介绍与映射模板相关的概念性信息。
下图显示了与 PetStore 集成端点集成的 `POST /pets` 资源的请求生命周期。在此 API 中，用户发送有关宠物的数据，而集成端点返回与宠物关联的收养费。在此请求生命周期中，映射模板转换会将请求正文筛选到集成端点，并从集成端点筛选响应正文。
![\[请求生命周期示例\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/mapping-template-transforms.png)
以下各节解释请求和响应生命周期。
## 方法请求和集成请求
在前面的示例中，如果这是发送到方法请求的请求正文：
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
此请求正文的格式不适合集成端点使用，因此 API Gateway 执行映射模板转换。API Gateway 仅执行映射模板转换，因为已为 Content-Type `application/json` 定义了映射模板。如果您没有为 Content-Type 定义映射模板，则默认情况下，API Gateway 会通过集成请求将正文传递到集成端点。要修改此行为，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
以下映射模板先转换集成请求中的方法请求数据，然后将数据发送到集成端点：
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot` 变量表示上一部分的原始 JSON 数据中的根对象。指令以 `#` 符号开头。
1. `dog` 是用户的 `id` 和字符串值的串联。
1. `Age` 来自方法请求正文。
然后，将以下输出转发到集成端点：
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## 集成响应和方法响应
成功请求集成端点后，端点会向 API Gateway 的集成响应发送响应。以下是来自集成端点的示例输出数据：
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
方法响应预期的有效载荷与集成响应返回的有效载荷不同。API Gateway 执行映射模板转换。API Gateway 仅执行映射模板转换，因为已为 Content-Type `application/json` 定义了映射模板。如果您没有为 Content-Type 定义映射模板，则默认情况下，API Gateway 会通过对方法响应的集成响应传递正文。要修改此行为，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
以下输出发送到方法响应：
```
{"adoptionFee": 19.95}
```
这就完成了示例映射模板转换。我们建议尽可能使用代理集成来转换数据，而不是使用映射模板转换。有关更多信息，请参阅 [选择 API Gateway API 集成类型](api-gateway-api-integration-types.md)。
# API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为
如果方法请求有一个有效载荷，而您没有为 `Content-Type` 标头定义映射模板，则可以选择通过集成请求将客户端提供的请求有效载荷传递到后端，而不进行转换。此过程称为集成传递。
传入请求的实际传递行为由此设置决定。这里有三个选项：
**当没有模板与请求的 Content-Type 标头匹配时**
如果您希望在方法请求内容类型不匹配任何与映射模板关联的内容类型时，将方法请求正文通过集成请求发送到后端而不进行转换，则选择此选项。
调用 API Gateway API 时，您通过将 `WHEN_NO_MATCH` 设置为[集成](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)的 `passthroughBehavior` 属性值来选择此选项。
**未定义任何模板时（推荐）**
如果您希望在集成请求中未定义映射模板时，将方法请求正文通过集成请求发送到后端而不进行转换，则选择此选项。如果在选择此选项时定义了模板，则具有与任何定义的映射模板都不匹配的有效载荷和内容类型的方法请求将遭到拒绝，并返回“HTTP 415 媒体类型不受支持”响应。
调用 API Gateway API 时，您通过将 `WHEN_NO_TEMPLATES` 设置为[集成](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)的 `passthroughBehavior` 属性值来选择此选项。
**从不**
如果您不希望在集成请求中未定义映射模板时，将方法请求正文通过集成请求发送到后端而不进行转换，则选择此选项。如果选择此选项时定义了模板，则会以“HTTP 415 Unsupported Media Type”响应拒绝未映射内容类型的方法请求。
调用 API Gateway API 时，您通过将 `NEVER` 设置为[集成](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)的 `passthroughBehavior` 属性值来选择此选项。
以下示例显示了可能的传递行为。
示例 1：`application/json` 内容类型的集成请求中定义了一个映射模板。
| Content-type | 传递选项 | 行为 |
| --- | --- | --- |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1MATCH | 使用模板转换请求负载。 |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1TEMPLATES | 使用模板转换请求负载。 |
| 无 API Gateway 默认为 `application/json` | NEVER | 使用模板转换请求负载。 |
| application/json | WHEN\$1NO\$1MATCH | 使用模板转换请求负载。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 使用模板转换请求负载。 |
| application/json | NEVER | 使用模板转换请求负载。 |
| application/xml | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/xml | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
示例 2：`application/xml` 内容类型的集成请求中定义了一个映射模板。
| Content-type | 传递选项 | 行为 |
| --- | --- | --- |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1TEMPLATES | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| 无 API Gateway 默认为 `application/json` | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/json | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/json | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/xml | WHEN\$1NO\$1MATCH | 使用模板转换请求负载。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 使用模板转换请求负载。 |
| application/xml | NEVER | 使用模板转换请求负载。 |
示例 3：集成请求中未定义映射模板。
| Content-type | 传递选项 | 行为 |
| --- | --- | --- |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| 无 API Gateway 默认为 `application/json` | WHEN\$1NO\$1TEMPLATES | 请求负载未转换，并按原样发送到后端。 |
| 无 API Gateway 默认为 `application/json` | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/json | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| application/json | WHEN\$1NO\$1TEMPLATES | 请求负载未转换，并按原样发送到后端。 |
| application/json | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
| application/xml | WHEN\$1NO\$1MATCH | 请求负载未转换，并按原样发送到后端。 |
| application/xml | WHEN\$1NO\$1TEMPLATES | 请求负载未转换，并按原样发送到后端。 |
| application/xml | NEVER | 请求被拒绝，得到 HTTP 415 Unsupported Media Type 响应。 |
# API Gateway 中 REST API 的附加映射模板示例
以下示例显示了 API Gateway 中的相册 API，该 API 使用映射模板转换集成请求和集成响应数据。它还使用数据模型来定义方法请求和集成响应有效载荷。有关数据模型的更多信息，请参阅[针对 REST API 的数据模型](models-mappings-models.md)。
## 方法请求和集成请求
以下是定义方法请求正文的模型。此输入模型要求调用方上传一张照片页面，每页至少需要 10 张照片。您可以使用此输入模型生成 SDK 或为您的 API 使用请求验证。在使用请求验证时，如果方法请求正文不符合模型的数据结构，则 API Gateway 会使请求失败。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
以下是遵循先前数据模型的数据结构的方法请求正文示例。
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
在此示例中，如果之前的方法请求正文是由客户端提交的，则此映射模板会转换有效载荷，以匹配集成端点所需的格式。
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
以下示例是来自转换的输出数据：
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
这些数据发送到集成请求，然后发送到集成端点。
## 集成响应和方法响应
以下是来自集成端点的照片数据的输出模型示例。您可以将此模型用于方法响应模型，这在为 API 生成强类型 SDK 时是必需的。这会导致输出将在 Java 或 Objective-C 中强制转换为适当的类。
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
集成端点可能不会以符合此模型的数据结构的响应进行响应。例如，集成响应可能如下所示：
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
以下示例映射模板将集成响应数据转换为方法响应所期望的格式：
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
以下示例是来自转换的输出数据：
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
这些数据发送到方法响应，然后再发送回客户端。
# 针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码
您可以使用映射模板转换来覆盖任何类型的请求参数、响应标头或响应状态代码。可以使用映射模板来执行以下操作：
+ 执行多对一参数映射
+ 在应用标准 API Gateway 映射后覆盖参数
+ 根据正文内容或其他参数值有条件地映射参数
+ 以编程方式创建新参数
+ 覆盖由集成端点返回的状态代码
覆盖是最终的。对于每个参数，覆盖只能应用一次。如果您多次尝试覆盖同一个参数，则 API Gateway 会返回 `5XX` 响应。如果您必须在整个模板中多次覆盖相同的参数，我们建议创建一个变量并在模板末尾应用覆盖。仅在解析整个模板后应用模板。
## 示例 1：基于集成正文覆盖状态代码
以下示例使用[示例 API](api-gateway-create-api-from-example.md) 基于集成响应正文覆盖状态代码。
------
#### [ AWS 管理控制台 ]
**基于集成响应正文覆盖状态代码**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择**创建 API**。
1. 对于 **REST API**，选择**构建**。
1. 对于 **API 详细信息**，选择**示例 API**。
1. 选择**创建 API**。
API Gateway 创建一个示例宠物商店 API。要检索有关宠物的信息，您使用 API 方法请求 `GET /pets/{petId}`，其中 `{petId}` 是与宠物的 ID 号相对应的路径参数。
在此示例中，当检测到错误条件时，您将 `GET` 方法的响应代码覆盖为 `400`。
1. 在**资源**树中，选择 `/{petId}` 下的 `GET` 方法。
1. 首先，测试 API 的当前实现。
选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 对于 **petId**，输入 **-1**，然后选择**测试**。
**响应正文**指示超出范围错误：
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
此外，**日志**下的最后一行的结尾为：`Method completed with status: 200`。
集成已成功完成，但出现错误。现在，您将根据集成响应覆盖状态代码。
1. 在**集成响应**选项卡上，对于**默认 - 响应**，选择**编辑**。
1. 选择**映射模板**。
1. 选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
如果集成响应包含字符串 `error`，则此映射模板使用 `$context.responseOverride.status` 变量将状态代码覆盖为 `400`。
1. 选择**保存**。
1. 选择**测试**选项卡。
1. 对于 **petId**，输入 **-1**。
1. 在结果中，**响应正文**表示超出范围错误：
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
不过，**日志**下的最后一行现在的结尾为：`Method completed with status: 400`。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义创建 `GET pets/{petId}` 资源并根据集成主体覆盖状态代码。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## 示例 2：覆盖请求标头并创建新标头
以下示例使用[示例 API](api-gateway-create-api-from-example.md) 来覆盖请求标头并创建新的标头。
------
#### [ AWS 管理控制台 ]
**通过创建新标头覆盖方法的请求标头**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择您在先前教程中创建的示例 API。API 的名称应为 **PetStore**。
1. 在**资源**树中，选择 `/pet` 下的 `GET` 方法。
1. 在**方法请求**选项卡上，对于**方法请求设置**，选择**编辑**。
1. 选择 **HTTP 请求标头**，然后选择**添加标头**。
1. 对于**名称**，请输入 **header1**。
1. 选择**添加标头**，然后创建第二个标头，名为 **header2**。
1. 选择**保存**。
现在，您可以使用映射模板将这些标头合并为一个标头值。
1. 在**集成请求**选项卡上，对于**集成请求设置**，选择**编辑**。
1. 对于**请求正文传递**，选择**当未定义模板时（推荐）**。
1. 选择**映射模板**，然后执行以下操作：
1. 选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
此映射模板使用字符串 `pets` 覆盖 `header1`，并创建一个名为 `$header3Value` 的多值标头，该标头将 `header1` 和 `header2` 组合在一起。
1. 选择**保存**。
1. 选择**测试**选项卡。
1. 在**标头**下，复制以下代码：
```
header1:header1Val
header2:header2Val
```
1. 选择 **Test (测试)**。
在**日志**中，您应看到一个包含此文本的条目：
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义创建 `GET pets` 资源，并覆盖请求标头和创建新的标头。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
要使用映射模板覆盖，请添加以下一个或多个 `$context` 变量。有关 `$context` 变量的列表，请参阅[数据转换的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)。
# 教程：修改集成请求和响应以集成到 AWS 服务
以下教程展示了如何使用映射模板转换来设置映射模板，以使用控制台和 AWS CLI 转换集成请求和响应。
**Topics**
+ [使用 API Gateway 控制台设置数据转换](#mapping-example-console)
+ [使用 AWS CLI 设置数据转换](#mapping-example-cli)
+ [已完成的数据转换 CloudFormation 模板](#api-gateway-data-transformations-full-cfn-stack)
## 使用 API Gateway 控制台设置数据转换
在本教程中，您将使用以下 .zip 文件 [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip) 创建不完整的 API 和 DynamoDB 表。这个不完整的 API 拥有的 `/pets` 资源具有 `GET` 和 `POST` 方法。
+ `GET` 方法将从 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端点获取数据。输出数据将根据[API Gateway 中 REST API 的映射模板转换](models-mappings.md)中的映射模板进行转换。
+ `POST` 方法将允许用户使用映射模板将宠物信息 `POST` 到 Amazon DynamoDB 表中。
下载并解压缩[适用于 CloudFormation 的应用程序创建模板](samples/data-transformation-tutorial-console.zip)。您将使用此模板创建 DynamoDB 表来发布宠物信息和不完整的 API。您将在 API Gateway 控制台中完成其余步骤。
**创建 CloudFormation 堆栈**
1. 打开 CloudFormation 控制台，地址：[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 选择**创建堆栈**，然后选择**使用新资源(标准)**。
1. 对于**指定模板**，选择**上传模板文件**。
1. 选择您下载的模板。
1. 选择**下一步**。
1. 对于**堆栈名称**，输入 **data-transformation-tutorial-console**，然后选择**下一步**。
1. 对于**配置堆栈选项**，请选择**下一步**。
1. 对于**功能**，请确认 CloudFormation 可以在您的账户中创建 IAM 资源。
1. 选择**下一步**，然后选择**提交**。
CloudFormation 预置在模板中指定的资源。完成资源预置可能需要几分钟时间。当 CloudFormation 堆栈的状态为 **CREATE\$1COMPLETE** 时，您就可以继续下一步了。
**测试 `GET` 集成响应**
1. 在 **data-transformation-tutorial-console** 的 CloudFormation 堆栈的**资源**选项卡上，选择您的 API 的物理 ID。
1. 在主导航窗格中，选择**资源**，然后选择 **GET** 方法。
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
测试的输出将显示以下内容：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
您将根据[API Gateway 中 REST API 的映射模板转换](models-mappings.md)中的映射模板转换此输出。
**转换 `GET` 集成响应**
1. 选择**集成响应**选项卡。
目前，没有定义任何映射模板，因此不会转换集成响应。
1. 对于**默认 - 响应**，选择**编辑**。
1. 选择**映射模板**，然后执行以下操作：
1. 选择**添加映射模板**。
1. 对于**内容类型**，输入 **application/json**。
1. 对于**模板正文**，输入以下内容：
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
选择**保存**。
**测试 `GET` 集成响应**
+ 选择**测试**选项卡，然后选择**测试**。
测试的输出将显示转换后的响应。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**转换来自 `POST` 方法的输入数据**
1. 选择 **POST** 方法。
1. 选择**集成请求**选项卡，然后对于**集成请求设置**，选择**编辑**。
CloudFormation 模板已填充了一些集成请求字段。
+ 集成类型为 AWS 服务。
+ AWS 服务是 DynamoDB。
+ HTTP 方法为 `POST`。
+ 操作是 `PutItem`。
+ 允许 API Gateway 将项目放入 DynamoDB 表的执行角色是 `data-transformation-tutorial-console-APIGatewayRole`。CloudFormation 创建此角色以允许 API Gateway 拥有与 DynamoDB 交互的最低权限。
尚未指定 DynamoDB 表的名称。您将在以下步骤中指定名称。
1. 对于**请求正文传递**，选择**从不**。
这意味着 API 将拒绝其 Content-Type（内容类型）没有映射模板的数据。
1. 选择**映射模板**。
1. **内容类型**设置为 `application/json`。这意味着 API 将拒绝所有不是 application/json 的内容类型。有关集成传递行为的更多信息，请参阅[API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)
1. 在文本编辑器中输入以下代码。
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
此模板将表指定为 `data-transformation-tutorial-console-ddb` 并将项目设置为 `id`、`type` 和 `price`。这些项目将来自 `POST` 方法的正文。您也可以使用数据模型来帮助创建映射模板。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 的请求验证](api-gateway-method-request-validation.md)。
1. 选择**保存**以保存映射模板。
**从 `POST` 方法添加方法和集成响应**
CloudFormation 创建了一个空白方法和集成响应。您将编辑此回复以提供更多信息。有关如何编辑响应的更多信息，请参阅[API Gateway 中 REST API 的参数映射示例](request-response-data-mappings.md)。
1. 在**集成响应**选项卡上，对于**默认 - 响应**，选择**编辑**。
1. 选择**映射模板**，然后选择**添加映射模板**。
1. 对于 **Content-Type**，输入 **application/json**。
1. 在代码编辑器中，输入以下输出映射模板以发送输出消息：
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
有关上下文变量的更多信息，请参阅[数据转换的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)。
1. 选择**保存**以保存映射模板。
**测试 `POST` 方法**
选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 在请求正文中，输入以下示例。
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. 选择**测试**。
输出应显示您的成功消息。
您可以通过 [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 打开 DynamoDB 控制台，以验证示例项目是否在您的表中。
**删除 CloudFormation 堆栈**
1. 打开 CloudFormation 控制台，地址：[https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 选择您的 CloudFormation 堆栈。
1. 选择**删除**，然后确认您的选择。
## 使用 AWS CLI 设置数据转换
在本教程中，您将使用以下 .zip 文件 [data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip) 创建不完整的 API 和 DynamoDB 表。这个不完整的 API 所具有的 `/pets` 资源包含与 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端点集成的 `GET` 方法。您将创建 `POST` 方法以连接到 DynamoDB 表，并使用映射模板将数据输入到 DynamoDB 表中。
+ 您将根据[API Gateway 中 REST API 的映射模板转换](models-mappings.md)中的映射模板转换输出数据。
+ 您将创建 `POST` 方法，以允许用户使用映射模板将宠物信息 `POST` 到 Amazon DynamoDB 表中。
**创建 CloudFormation 堆栈**
下载并解压缩[适用于 CloudFormation 的应用程序创建模板](samples/data-transformation-tutorial-cli.zip)。
要完成以下教程，您需要 [AWS Command Line Interface（AWS CLI）版本 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
对于长命令，使用转义字符 (`\`) 将命令拆分为多行。
**注意**
在 Windows 中，操作系统的内置终端不支持您经常使用的某些 Bash CLI 命令（例如 `zip`）。[安装 Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)，获取 Ubuntu 和 Bash 与 Windows 集成的版本。本指南中的示例 CLI 命令使用 Linux 格式。如果您使用的是 Windows CLI，则必须重新格式化包含内联 JSON 文档的命令。
1. 输入以下命令创建 CloudFormation 堆栈。
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation 预置在模板中指定的资源。完成资源预置可能需要几分钟时间。使用以下命令查看 CloudFormation 的状态。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. 当 CloudFormation 堆栈的状态为 `StackStatus: "CREATE_COMPLETE"` 时，使用以下命令检索将来步骤的相关输出值。
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
输出值包括：
+ ApiRole，这是允许 API Gateway 在 DynamoDB 表中放置项目的角色名称。对于本教程，角色名称为 `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`。
+ DDBTableName，这是 DynamoDB 表的名称。对于本教程，表名称为 `data-transformation-tutorial-cli-ddb`
+ ResourceId，这是公开 `GET` 和 `POST` 方法的宠物资源的 ID。对于本教程，资源 ID 为 `efg456`
+ ApiId，这是 API 的 ID。对于本教程，API ID 为 `abc123`。
**在数据转换之前测试 `GET` 方法**
+ 使用以下命令测试 `GET` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
测试的输出将显示以下内容。
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
您将根据[API Gateway 中 REST API 的映射模板转换](models-mappings.md)中的映射模板转换此输出。
**转换 `GET` 集成响应**
+ 使用以下命令更新 `GET` 方法的集成响应。将 *rest-api-id* 和 *resource-id* 替换为您的值。
使用以下命令创建集成响应。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**测试 `GET` 方法**
+ 使用以下命令测试 `GET` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
测试的输出将显示转换后的响应。
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**创建 `POST` 方法**
1. 使用以下命令在您的 `/pets` 资源上创建新的方法。
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
此方法允许您将宠物信息发送到您在 CloudFormation 堆栈中创建的 DynamoDB 表。
1. 使用以下命令在 `POST` 方法上创建 AWS 服务 集成。
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. 使用以下命令为成功调用 `POST` 方法创建方法响应。
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. 使用以下命令为成功调用 `POST` 方法创建集成响应。
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**测试 `POST` 方法**
+ 使用以下命令测试 `POST` 方法。
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
输出将显示成功消息。
**删除 CloudFormation 堆栈**
+ 使用以下命令删除您的 CloudFormation 资源。
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## 已完成的数据转换 CloudFormation 模板
以下示例是一个已完成的 CloudFormation 模板，它创建了一个 API 和一个 DynamoDB 表，该表的 `/pets` 资源具有 `GET` 和 `POST` 方法。
+ `GET` 方法将从 `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP 端点获取数据。输出数据将根据[API Gateway 中 REST API 的映射模板转换](models-mappings.md)中的映射模板进行转换。
+ `POST` 方法将允许用户使用映射模板将宠物信息 `POST` 到 DynamoDB 表中。
### 示例 CloudFormation 模板
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# 使用变量来映射 API Gateway 的模板转换的示例
以下示例显示了如何在映射模板中使用 `$context`、`input` 和 `util` 变量。您可以使用模拟集成或用于将输入事件返回到 API Gateway 的 Lambda 非代理集成。有关数据转换的所有支持的变量的列表，请参阅 [API Gateway 的用于数据转换的变量](api-gateway-mapping-template-reference.md)。
## 示例 1：将多个 `$context` 变量传递到集成端点
以下示例显示了一个映射模板，该模板将传入的 `$context` 变量映射到后端变量，这些变量在集成请求负载中的名称稍有不同：
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
此映射模板的输出应与以下内容类似：
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
其中一个变量是 API 密钥。此示例假设方法需要 API 密钥。
## 示例 2：通过 JSON 有效载荷将所有请求参数传递给集成端点
以下示例通过 JSON 有效载荷将所有请求参数（包括 `path`、`querystring` 和 `header` 参数）传递到集成端点：
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
如果请求具有以下输入参数：
+ 名为 `myparam` 的路径参数
+ 查询字符串参数 `querystring1=value1,value2`
+ 标头 `"header1" : "value1"`。
此映射模板的输出应与以下内容类似：
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## 示例 3：将方法请求的一部分传递给集成端点
以下示例使用输入参数 `name` 仅检索 `name` 参数，并使用输入参数 `input.json('$')` 检索方法请求的整个正文：
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
对于包含查询字符串参数 `name=Bella&type=dog` 和以下正文的请求：
```
{
"Price" : "249.99",
"Age": "6"
}
```
此映射模板的输出应与以下内容类似：
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
此映射模板移除了查询字符串参数 `type=dog`。
如果 JSON 输入包含无法通过 JavaScript 解析的非转义字符，则 API Gateway 可能会返回 400 响应。应用 `$util.escapeJavaScript($input.json('$'))` 来确保正确解析 JSON 输入。
上面的示例在应用了 `$util.escapeJavaScript($input.json('$'))` 之后会如下所示：
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
在这种情况下，此映射模板的输出应与以下内容类似：
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## 示例 4：使用 JSONPath 表达式将方法请求的一部分传递给集成端点
以下示例使用 JSONPath 表达式从请求正文中仅检索输入参数 `name` 和 `Age`：
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
对于包含查询字符串参数 `name=Bella&type=dog` 和以下正文的请求：
```
{
"Price" : "249.99",
"Age": "6"
}
```
此映射模板的输出应与以下内容类似：
```
{
"name" : "Bella",
"body" : "6"
}
```
此映射模板从正文中移除查询字符串参数 `type=dog` 和 `Price` 字段。
如果方法请求负载包含无法通过 JavaScript 解析的非转义字符，则 API Gateway 可能会返回 `400` 响应。应用 `$util.escapeJavaScript()` 来确保正确解析 JSON 输入。
上面的示例在应用了 `$util.escapeJavaScript($input.json('$.Age'))` 之后会如下所示：
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
在这种情况下，此映射模板的输出应与以下内容类似：
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## 示例 5：使用 JSONPath 表达式将有关方法请求的信息传递到集成端点
以下示例使用 `$input.params()`、`$input.path()` 和 `$input.json()` 向集成端点发送有关方法请求的信息。此映射模板使用 `size()` 方法来提供列表中元素的数量。
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
对于包含路径参数 `123` 和以下正文的请求：
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
此映射模板的输出应与以下内容类似：
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
如果方法请求负载包含无法通过 JavaScript 解析的非转义字符，则 API Gateway 可能会返回 `400` 响应。应用 `$util.escapeJavaScript()` 来确保正确解析 JSON 输入。
上面的示例在应用了 `$util.escapeJavaScript($input.json('$.things'))` 之后会如下所示：
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
此映射模板的输出应与以下内容类似：
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# API Gateway 的用于数据转换的变量
创建参数映射时，可以使用上下文变量作为数据来源。创建映射模板转换时，可以在用 [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 编写的脚本中使用上下文变量、输入和 util 变量。有关使用这些参考变量的映射模板的示例，请参阅[使用变量来映射 API Gateway 的模板转换的示例](api-gateway-mapping-variable-examples.md)。
有关访问日志记录的参考变量的列表，请参阅 [API Gateway 的访问日志记录的变量](api-gateway-variables-for-access-logging.md)。
## 数据转换的上下文变量
可以使用以下区分大小写的 `$context` 变量来进行数据转换。
| 参数 | 说明 |
| --- | --- |
| \$1context.accountId | API 拥有者的 AWS 账户 ID。 |
| \$1context.apiId | API Gateway 分配给您的 API 的标识符。 |
| \$1context.authorizer.claims.property | 成功对方法调用方进行身份验证后从 Amazon Cognito 用户池返回的声明的属性。有关更多信息，请参阅 [使用 Amazon Cognito 用户池作为授权方控制对 REST API 的访问](apigateway-integrate-with-cognito.md)。 调用 `$context.authorizer.claims` 将返回 null。 |
| \$1context.authorizer.principalId | 与由客户端发送的令牌关联并从 API Gateway Lambda 授权方（以前称为自定义授权方）返回的委托人用户标识。有关更多信息，请参阅 [使用 API Gateway Lambda 授权方](apigateway-use-lambda-authorizer.md)。 |
| \$1context.authorizer.property | 从 API Gateway Lambda 授权方函数返回的 `context` 映射的指定键/值对的字符串化值。例如，如果授权方返回以下 `context` 映射： "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} 调用 `$context.authorizer.key` 将返回 `"value"` 字符串，调用 `$context.authorizer.numKey` 将返回 `"1"` 字符串，而调用 `$context.authorizer.boolKey` 将返回 `"true"` 字符串。 对于*属性*，唯一支持的特殊字符是下划线 `(_)` 字符。 有关更多信息，请参阅 [使用 API Gateway Lambda 授权方](apigateway-use-lambda-authorizer.md)。 |
| \$1context.awsEndpointRequestId | AWS 端点的请求 ID。 |
| \$1context.deploymentId | API 部署的 ID。 |
| \$1context.domainName | 用于调用 API 的完整域名。这应与传入的 `Host` 标头相同。 |
| \$1context.domainPrefix | `$context.domainName` 的第一个标签。 |
| \$1context.error.message | 包含 API Gateway 错误消息的字符串。此变量只能用于 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 正文映射模板中（不由 Velocity 模板语言引擎处理）和访问日志记录中的简单变量替换。有关更多信息，请参阅 [使用 CloudWatch 指标监控 WebSocket API 执行](apigateway-websocket-api-logging.md) 和 [设置网关响应以自定义错误响应](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。 |
| \$1context.error.messageString | \$1context.error.message 的带引号的值，即 "\$1context.error.message"。 |
| \$1context.error.responseType | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 的[类型](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) 此变量只能用于 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 正文映射模板中（不由 Velocity 模板语言引擎处理）和访问日志记录中的简单变量替换。有关更多信息，请参阅 [使用 CloudWatch 指标监控 WebSocket API 执行](apigateway-websocket-api-logging.md) 和 [设置网关响应以自定义错误响应](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。 |
| \$1context.error.validationErrorString | 包含详细验证错误消息的字符串。 |
| \$1context.extendedRequestId | API Gateway 生成并分配给 API 请求的扩展 ID。扩展请求 ID 包含调试和故障排除的有用信息。 |
| \$1context.httpMethod | 所用的 HTTP 方法。有效值包括：`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 和 `PUT`。 |
| \$1context.identity.accountId | 与请求关联的 AWS 账户 ID。 |
| \$1context.identity.apiKey | 对于需要 API 密钥的 API 方法，此变量是与该方法请求关联的 API 密钥。对于无需 API 密钥的方法，此变量为 null。有关更多信息，请参阅 [API Gateway 中针对 REST API 的使用计划和 API 密钥](api-gateway-api-usage-plans.md)。 |
| \$1context.identity.apiKeyId | 与需要 API 密钥的 API 请求关联的 API 密钥 ID。 |
| \$1context.identity.caller | 签发请求的调用方的委托人标识符。对于使用 IAM 授权的资源支持此项。 |
| \$1context.identity.cognitoAuthenticationProvider | 发出请求的调用方使用的所有 Amazon Cognito 身份验证提供商的逗号分隔列表。仅当使用 Amazon Cognito 凭证对请求签名时才可用。 例如，对于 Amazon Cognito 身份池中的身份，`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 有关更多信息，请参阅 *Amazon Cognito 开发人员指南* 中的[使用联合身份](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)。 |
| \$1context.identity.cognitoAuthenticationType | 发出请求的调用方的 Amazon Cognito 身份验证类型。仅当使用 Amazon Cognito 凭证对请求签名时才可用。可能的值包括经过身份验证的身份的 `authenticated` 和未经身份验证的身份的 `unauthenticated`。 |
| \$1context.identity.cognitoIdentityId | 发出请求的调用方的 Amazon Cognito 身份 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。 |
| \$1context.identity.cognitoIdentityPoolId | 发出请求的调用方的 Amazon Cognito 身份池 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。 |
| \$1context.identity.principalOrgId | [AWS 组织 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)。 |
| \$1context.identity.sourceIp | 向 API Gateway 端点发出请求的即时 TCP 连接的源 IP 地址。 |
| \$1context.identity.clientCert.clientCertPem | 客户端在双向 TLS 身份验证过程中提供的 PEM 编码的客户端证书。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.clientCert.subjectDN | 客户端提供的证书的主题的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.clientCert.issuerDN | 客户端提供的证书的颁发者的可分辨名称。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.clientCert.serialNumber | 证书的序列号。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.clientCert.validity.notBefore | 证书无效之前的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.clientCert.validity.notAfter | 证书无效后的日期。当客户端使用已启用双向 TLS 的自定义域名访问 API 时提供。仅在双向 TLS 身份验证失败时才出现在访问日志中。 |
| \$1context.identity.vpcId | 向 API Gateway 端点发出请求的 VPC 的 VPC ID。 |
| \$1context.identity.vpceId | 向 API Gateway 端点发出请求的 VPC 端点的 VPC 端点 ID。仅当您具有私有 API 时才会显示。 |
| \$1context.identity.user | 将获得资源访问权限授权的用户的委托人标识符。对于使用 IAM 授权的资源支持此项。 |
| \$1context.identity.userAgent | API 调用方的 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 标头。 |
| \$1context.identity.userArn | 身份验证后标识的有效用户的 Amazon Resource Name (ARN)。有关更多信息，请参阅 [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)。 |
| \$1context.isCanaryRequest | 如果请求定向到金丝雀，将返回 `true`，如果请求没有定向到金丝雀，将返回 `false`。仅当您启用金丝雀时才会显示。 |
| \$1context.path | 请求路径。例如，对于 https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child 的非代理请求 URL，\$1context.path 值为 /\$1stage\$1/root/child。 |
| \$1context.protocol | 请求的协议，例如，HTTP/1.1。 API Gateway API 可以接受 HTTP/2 请求，但 API Gateway 使用 HTTP/1.1 向后端集成发送请求。因此，即使客户端发送的请求使用 HTTP/2，请求协议也会记录为 HTTP/1.1。 |
| \$1context.requestId | 请求的 ID。客户可以覆盖此请求 ID。使用 `$context.extendedRequestId` 用于 API Gateway 生成的唯一请求 ID。 |
| \$1context.requestOverride.header.header\$1name | 请求标头覆盖。如果定义此参数，则它将包含要使用的标题，而不是**集成请求**窗格中定义的 **HTTP 标头**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestOverride.path.path\$1name | 请求路径覆盖。如果定义此参数，则它将包含要使用的请求路径，而不是**集成请求**窗格中定义的 **URL 路径参数**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestOverride.querystring.querystring\$1name | 请求查询字符串覆盖。如果定义此参数，则它将包含要使用的请求查询字符串，而不是**集成请求**窗格中定义的 **URL 查询字符串参数**。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 |
| \$1context.responseOverride.header.header\$1name | 响应标头覆盖。如果定义此参数，则它包含要使用的标头，而不是集成响应窗格中定义为默认映射的响应标头。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 |
| \$1context.responseOverride.status | 响应状态代码覆盖。如果定义此参数，则它包含要使用的状态代码，而不是集成响应窗格中定义为默认映射的方法响应状态。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 覆盖 API 的请求和响应参数以及状态代码](apigateway-override-request-response-parameters.md)。 |
| \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 |
| \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式的请求时间，以毫秒为单位。 |
| \$1context.resourceId | API Gateway 分配给您的资源的标识符。 |
| \$1context.resourcePath | 资源路径。例如，对于 `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child` 的非代理请求 URI，`$context.resourcePath` 值为 `/root/child`。有关更多信息，请参阅 [教程：使用 HTTP 非代理集成创建 REST API](api-gateway-create-api-step-by-step.md)。 |
| \$1context.stage | API 请求的部署阶段（例如，`Beta` 或 `Prod`）。 |
| \$1context.wafResponseCode | 从 [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 中收到的响应：`WAF_ALLOW` 或 `WAF_BLOCK`。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅 [在 API Gateway 中使用 AWS WAF 保护 REST API](apigateway-control-access-aws-waf.md)。 |
| \$1context.webaclArn | Web ACL 的完整 ARN，用于决定是允许还是阻止请求。如果阶段未与 Web ACL 关联，则不会设置。有关更多信息，请参阅 [在 API Gateway 中使用 AWS WAF 保护 REST API](apigateway-control-access-aws-waf.md)。 |
## 输入变量
可以使用以下区分大小写的 `$input` 变量来引用方法请求有效载荷和方法请求参数。可以执行以下功能：
| 变量和函数 | 说明 |
| --- | --- |
| \$1input.body | 以字符串形式返回原始请求负载。您可以使用 `$input.body` 来保留整个浮点数，例如 `10.00`。 |
| \$1input.json(x) | 此函数计算 JSONPath 表达式并以 JSON 字符串形式返回结果。 例如，`$input.json('$.pets')` 返回一个表示 `pets` 结构的 JSON 字符串。 有关 JSONPath 的更多信息，请参阅 [JSONPath](https://goessner.net/articles/JsonPath/) 或[适用于 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 |
| \$1input.params() | 返回所有请求参数的映射。我们建议您使用 `$util.escapeJavaScript` 对结果进行清理，以避免潜在的注入攻击。要完全控制请求清理，可以使用没有模板的代理集成，并在集成中处理请求清理。 |
| \$1input.params(x) | 在给定参数名称字符串 `x` 的情况下，返回路径中的方法请求参数值、查询字符串或标头值（按照该顺序搜索）。我们建议您使用 `$util.escapeJavaScript` 对参数进行清理，以避免潜在的注入攻击。要完全控制参数清理，可以使用没有模板的代理集成，并在集成中处理请求清理。 |
| \$1input.path(x) | 获取一个 JSONPath 表达式字符串 (`x`) 并返回结果的 JSON 对象表达式。这样，您便可通过 [Apache Velocity 模板语言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 在本机访问和操作负载的元素。 例如，如果表达式 `$input.path('$.pets')` 返回一个如下所示的对象： [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` 将返回 `"3"`。 有关 JSONPath 的更多信息，请参阅 [JSONPath](https://goessner.net/articles/JsonPath/) 或[适用于 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 |
## 阶段变量
在方法集成中，可以使用以下阶段变量作为 ARN 和 URL 的占位符。有关更多信息，请参阅 [在 API Gateway 中对 REST API 使用阶段变量](stage-variables.md)。
| 语法 | 说明 |
| --- | --- |
| \$1stageVariables.variable\$1name、\$1stageVariables['variable\$1name'] 或 \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* 表示阶段变量名称。 |
## Util 变量
您可以使用以下区分大小写的 `$util` 变量，以便将实用程序函数用于映射模板。除非另行指定，否则默认字符集为 UTF-8。
| 函数 | 说明 |
| --- | --- |
| \$1util.escapeJavaScript() | 使用 JavaScript 字符串规则对字符串中的字符进行转义。 此函数会将任何常规单引号 (`'`) 变成转义单引号 (`\'`)。但是，转义单引号在 JSON 中无效。因此，当此函数的输出用于 JSON 属性时，必须将任何转义单引号 (`\'`) 变回常规单引号 (`'`)。如下例所示: "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | 获取“字符串化的”JSON 并返回结果的对象表示形式。您可以使用此函数的结果通过 Apache Velocity 模板语言 (VTL) 在本机访问和操作负载的元素。例如，如果您具有以下负载： {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} 并使用以下映射模板 #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
您将得到以下输出： {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | 将字符串转换为“application/x-www-form-urlencoded”格式。 |
| \$1util.urlDecode() | 对“application/x-www-form-urlencoded”字符串进行解码。 |
| \$1util.base64Encode() | 将数据编码为 base64 编码的字符串。 |
| \$1util.base64Decode() | 对 base64 编码字符串中的数据进行解码。 |
# 针对 API Gateway 中 REST API 的网关响应
网关响应使用 API Gateway 定义的响应类型进行标识。响应由 HTTP 状态代码（这是一组由参数映射指定的额外标头）和由非 [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html) 映射模板生成的有效载荷组成。
在 API Gateway REST API 中，[GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 表示网关响应。在 OpenAPI 中，[x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) 扩展表示 `GatewayResponse` 实例。
要启用网关响应，您需要在 API 级别为[受支持的响应类型](supported-gateway-response-types.md)设置网关响应。每当 API Gateway 返回该类型的响应时，都将使用在网关响应中定义的标头映射和负载映射模板，以将映射结果返回 API 调用方。
下一节我们将介绍如何使用 API Gateway 控制台和 API Gateway REST API 设置网关响应。
## 设置网关响应以自定义错误响应
如果 API Gateway 无法处理某个传入请求，它会向客户端返回一个错误响应，而不会将请求转发到集成后端。默认情况下，错误响应会包含一个简短的描述性错误消息。例如，如果您尝试对未定义的 API 资源调用操作，您将收到一个显示 `{ "message": "Missing Authentication Token" }` 消息的错误响应。如果首次使用 API Gateway，您可能会发现很难找到真正的问题。
对于某些错误响应，API Gateway 允许 API 开发人员通过自定义返回不同格式的响应。对于 `Missing Authentication Token` 示例，您可以为原始响应负载添加提示标注可能的原因，如下例所示：`{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`。
当您的 API 在外部交换和 AWS 云之间提供协调时，您可以使用集成请求或集成响应的 VTL 映射模板将负载从一种格式映射到另一种格式。但是，VTL 映射模板仅适用于能够成功响应的有效请求。
对于无效请求，API Gateway 可以完全绕过该集成，返回错误响应。您必须通过自定义，以可支持交换的格式发出错误响应。此时，使用仅支持简单变量替换的非 VTL 映射模板进行自定义。
将 API Gateway 生成的错误响应泛化处理成由 API Gateway 生成的任何响应，我们将它们称为*网关响应*。以此区分 API Gateway 生成的响应与集成响应。网关响应映射模板能以 `$context` 的形式访问 `$stageVariables` 变量值和 `method.request.param-position.param-name` 属性值以及方法请求参数。
有关 `$context` 变量的更多信息，请参阅 [数据转换的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)。有关 `$stageVariables` 的更多信息，请参阅 [阶段变量](api-gateway-mapping-template-reference.md#stagevariables-template-reference)。有关方法请求参数的更多信息，请参阅 [输入变量](api-gateway-mapping-template-reference.md#input-variable-reference)。
**Topics**
+ [设置网关响应以自定义错误响应](#customize-gateway-responses)
+ [使用 API Gateway 控制台为 REST API 设置网关响应](set-up-gateway-response-using-the-console.md)
+ [使用 API Gateway REST API 设置网关响应](set-up-gateway-response-using-the-api.md)
+ [在 OpenAPI 中设置网关响应自定义](set-up-gateway-responses-in-swagger.md)
+ [API Gateway 的网关响应类型](supported-gateway-response-types.md)
# 使用 API Gateway 控制台为 REST API 设置网关响应
以下示例说明如何使用 API Gateway 控制台为 REST API 设置网关响应
**使用 API Gateway 控制台自定义网关响应**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在主导航窗格中，选择**网关响应**。
1. 选择响应类型，然后选择**编辑**。在本次演练中，我们将以**缺少身份验证令牌**为例。
1. 您可以更改 API Gateway 生成的**状态代码**，以返回满足您的 API 要求的不同状态代码。在此示例中，自定义会将状态代码从默认值 (`403`) 更改为 `404`，因为在客户端调用可被视为未找到的不受支持或无效的资源时，会出现此错误消息。
1. 要返回自定义标头，请选择**响应标头**下的**添加响应标头**。为方便说明，我们将添加以下自定义标头：
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
在前面的标头映射中，将静态域名 (`'a.b.c'`) 映射到 `Allow-Control-Allow-Origin` 标头以允许 CORS 访问 API；将 `x-amzn-RequestId` 的输入请求标头映射到响应中的 `request-id`；将传入请求的 `petId` 路径变量映射到响应中的 `request-path` 标头；以及将原始请求的 `q` 查询参数映射到响应的 `request-query` 标头。
1. 在**响应模板**下，将 `application/json` 保留为**内容类型**，然后在**模板正文**编辑器中输入以下正文映射模板：
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
此示例显示了如何将 `$context` 和 `$stageVariables` 属性映射到网关响应正文的属性。
1. 选择**保存更改**。
1. 将 API 部署到新阶段或现有阶段。
通过调用以下 CURL 命令测试您的网关响应，假设相应 API 方法的调用 URL 是 `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`：
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
额外查询字符串参数 `q=1` 与 API 不兼容，因此指定的网关响应中返回了错误。您应收到与以下内容类似的网关响应：
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
前面的示例假定 API 后端为 [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets)，并且 API 有一个定义的阶段变量 `a`。
# 使用 API Gateway REST API 设置网关响应
在使用 API Gateway REST API 自定义网关响应之前，您必须已创建 API 并获得其标识符。要检索 API 标识符，您可以使用 [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) 链接关系并检查结果。
**使用 API Gateway REST API 自定义网关响应**
1. 要覆盖整个 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 实例，请调用 [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html) 操作。在 URL 路径参数中指定所需的 [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType)，并在请求负载中提供 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode)、[responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) 和 [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates) 映射。
1. 要更新 `GatewayResponse` 实例的一部分，请调用 [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html) 操作。在 URL 路径参数中指定所需的 `responseType`，并在请求中提供所需的单个 `GatewayResponse` 属性，例如，`responseParameters` 或 `responseTemplates` 映射。
# 在 OpenAPI 中设置网关响应自定义
在 OpenAPI 中，您可以在 API 根级别使用 `x-amazon-apigateway-gateway-responses` 扩展来自定义网关响应。下面的 OpenAPI 定义显示了自定义 `MISSING_AUTHENTICATION_TOKEN` 类型的 [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) 的示例。
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
在此示例中，自定义设置将状态代码从默认 (`403`) 更改为 `404`。此外，它还会为网关响应添加了四个标头参数和一个 `application/json` 媒体类型的正文映射模板。
# API Gateway 的网关响应类型
API Gateway 公开了以下网关响应以供 API 开发人员进行自定义。
| 网关响应类型 | 默认状态代码 | 说明 |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | 授权失败的网关响应；例如，被自定义授权方或 Amazon Cognito 授权方拒绝访问时。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| API\$1CONFIGURATION\$1ERROR | 500 | 无效 API 配置的网关响应，包括提交无效的端点地址时，在设置二进制支持时对二进制数据进行 Base64 解码失败时，或者集成响应映射无法匹配任何模板且未配置默认模板时。如果未指定响应类型，则默认该响应为 `DEFAULT_5XX` 类型。 |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | 未能连接到自定义或 Amazon Cognito 授权方的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_5XX` 类型。 |
| AUTHORIZER\$1FAILURE | 500 | 当自定义或 Amazon Cognito 授权方无法对调用方进行身份验证时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_5XX` 类型。 |
| BAD\$1REQUEST\$1PARAMETERS | 400 | 当无法根据已启用的请求验证程序验证请求参数时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| BAD\$1REQUEST\$1BODY | 400 | 当无法根据已启用的请求验证程序验证请求正文时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| DEFAULT\$14XX | Null | 状态代码为 `4XX` 的未指定响应类型的默认网关响应。更改此回退网关响应的状态代码会将所有其他 `4XX` 响应的状态代码更改为新值。将此状态代码重置为 Null 会使所有其他 `4XX` 响应的状态代码恢复到原始值。 [AWS WAF 自定义响应](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)优先于自定义网关响应。 |
| DEFAULT\$15XX | Null | 状态代码为 `5XX` 的未指定响应类型的默认网关响应。更改此回退网关响应的状态代码会将所有其他 `5XX` 响应的状态代码更改为新值。将此状态代码重置为 Null 会使所有其他 `5XX` 响应的状态代码恢复到原始值。 |
| EXPIRED\$1TOKEN | 403 | 发生 AWS 身份验证令牌过期错误时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| INTEGRATION\$1FAILURE | 504 | 发生集成失败错误时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_5XX` 类型。 |
| INTEGRATION\$1TIMEOUT | 504 | 发生集成超时错误时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_5XX` 类型。 |
| INVALID\$1API\$1KEY | 403 | 为要求 API 密钥的方法提交无效 API 密钥时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| INVALID\$1SIGNATURE | 403 | 发生无效的 AWS 签名错误时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | 发生缺少身份验证令牌错误时的网关响应，包括客户端尝试调用不受支持的 API 方法或资源的情况。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| QUOTA\$1EXCEEDED | 429 | 发生超出使用计划配额错误时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| REQUEST\$1TOO\$1LARGE | 413 | 发生请求太大错误时的网关响应。如果未指定响应类型，则该响应默认为：`HTTP content length exceeded 10485760 bytes`。 |
| RESOURCE\$1NOT\$1FOUND | 404 | 在 API 请求通过身份验证和授权（不包括 API 密钥身份验证和授权）后，API Gateway 找不到指定资源时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| THROTTLED | 429 | 当超出使用计划、方法、阶段或账户的节流限制时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| UNAUTHORIZED | 401 | 当自定义或 Amazon Cognito 授权方无法对调用方进行身份验证时的网关响应。 |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | 当启用严格的传递限制后，负载为不受支持的媒体类型时的网关类型。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 |
| WAF\$1FILTERED | 403 | 当请求被 AWS WAF 阻止时的网关响应。如果未指定响应类型，则默认该响应为 `DEFAULT_4XX` 类型。 [AWS WAF 自定义响应](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html)优先于自定义网关响应。 |
# 针对 API Gateway 中的 REST API 的 CORS
[跨源资源共享 (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 是一项浏览器安全特征，该特征限制从在浏览器中运行的脚本启动的跨源 HTTP 请求。有关更多信息，请参阅[什么是 CORS？](https://aws.amazon.com/what-is/cross-origin-resource-sharing/)。
## 确定是否启用 CORS 支持
*跨源* HTTP 请求将向以下项发出：
+ 一个不同的*域*（例如，从 `example.com` 到 `amazondomains.com`）
+ 一个不同的*子域*（例如，从 `example.com` 到 `petstore.example.com`）
+ 一个不同的*端口*（例如，从 `example.com` 到 `example.com:10777`）
+ 一个不同的*协议*（例如，从 `https://example.com` 到 `http://example.com`）
如果您无法访问自己的 API 并收到包含 `Cross-Origin Request Blocked` 的错误消息，则可能需要启用 CORS。
跨源 HTTP 请求可分为两种类型：*简单* 请求和*非简单* 请求。
## 为简单请求启用 CORS
如果满足以下所有条件，则 HTTP 请求为*简单* 请求：
+ 其针对仅允许 `GET`、`HEAD` 和 `POST` 请求的 API 资源发出。
+ 如果它是一个 `POST` 方法请求，则它必须包含 `Origin` 标头。
+ 请求负载内容类型为 `text/plain`、`multipart/form-data` 或 `application/x-www-form-urlencoded`。
+ 请求不包含自定义标头。
+ [简单请求的 Mozilla CORS 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests)中列出的任何其他要求。
对于简单的跨源 `POST` 方法请求，来自资源的响应需要包含标头 `Access-Control-Allow-Origin: '*'` 或 `Access-Control-Allow-Origin:'origin'`。
所有其他跨源 HTTP 请求均为*非简单* 请求。
## 为非简单请求启用 CORS
如果 API 的资源收到非简单请求，则必须根据集成类型启用额外的 CORS 支持。
### 为非代理集成启用 CORS
对于这些集成，[CORS 协议](https://fetch.spec.whatwg.org/#http-cors-protocol)要求浏览器在发送实际请求之前向服务器发送一个预检请求，并等待来自服务器的批准（或对于凭证的请求）。您必须配置您的 API 以向预检请求发送适当的响应。
要创建预检响应，请执行以下操作：
1. 使用模拟集成创建 `OPTIONS` 方法。
1. 将以下响应标头添加到 200 方法响应中：
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. 将集成传递行为设置为 `NEVER`。在这种情况下，将拒绝未映射内容类型的方法请求，并返回“HTTP 415 不支持的媒体类型”响应。有关更多信息，请参阅[API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
1. 输入响应标头的值。要允许所有来源、所有方法和通用标头，请使用以下标头值：
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
创建预检请求后，对于至少所有 200 响应，必须为所有启用 CORS 的方法返回 `Access-Control-Allow-Origin: '*'` 或 `Access-Control-Allow-Origin:'origin'` 标头。
### 使用 AWS 管理控制台为非代理集成启用 CORS
您可以使用 AWS 管理控制台来启用 CORS。API Gateway 会创建 `OPTIONS` 方法，并尝试将 `Access-Control-Allow-Origin` 标头添加到现有的方法集成响应中。这并不总是有效，有时您需要手动修改集成响应，以便为至少所有 200 响应的所有启用 CORS 的方法返回 `Access-Control-Allow-Origin` 标头。
如果 API 的二进制媒体类型设置为 `*/*`，则当 API Gateway 创建 `OPTIONS` 方法时，请将 `contentHandling` 更改为 `CONVERT_TO_TEXT`。
以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) 命令将集成请求的 `contentHandling` 更改为 `CONVERT_TO_TEXT`：
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
以下 [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) 命令将集成响应的 `contentHandling` 更改为 `CONVERT_TO_TEXT`：
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## 为代理集成启用 CORS 支持
对于 Lambda 代理集成或 HTTP 代理集成，您的后端负责返回 `Access-Control-Allow-Origin`、`Access-Control-Allow-Methods` 和 `Access-Control-Allow-Headers` 标头，因为代理集成不返回集成响应。
以下 Lambda 函数示例返回所需的 CORS 标头：
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [确定是否启用 CORS 支持](#apigateway-cors-request-types)
+ [为简单请求启用 CORS](#apigateway-cors-simple-request)
+ [为非简单请求启用 CORS](#apigateway-enable-cors-non-simple)
+ [为代理集成启用 CORS 支持](#apigateway-enable-cors-proxy)
+ [使用 API Gateway 控制台对资源启用 CORS](how-to-cors-console.md)
+ [使用 API Gateway 导入 API 在资源上启用 CORS](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [在 CORS 中测试 API Gateway API](apigateway-test-cors.md)
# 使用 API Gateway 控制台对资源启用 CORS
您可以使用 API Gateway 控制台为已创建的 REST API 资源上的一个或所有方法启用 CORS 支持。启用 COR 支持后，将集成传递行为设置为 `NEVER`。在这种情况下，将拒绝未映射内容类型的方法请求，并返回“HTTP 415 不支持的媒体类型”响应。有关更多信息，请参阅 [API Gateway 中适用于 REST API 且无映射模板的有效载荷的方法请求行为](integration-passthrough-behaviors.md)。
**重要**
资源可以包含子资源。为某个资源及其方法启用 CORS 支持不会以递归方式为子资源及其方法启用它。
**在 REST API 资源上启用 CORS 支持**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 API。
1. 在**资源**下选择一个资源。
1. 在**资源详细信息**部分，选择**启用 CORS**。
![\[在“资源”窗格中，选择“启用 CORS”。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. 在**启用 CORS** 框中，执行以下操作：
1. （可选）如果您创建了自定义网关响应并希望为响应启用 CORS 支持，请选择一种网关响应。
1. 选择各方法以启用 CORS 支持。`OPTION` 方法必须启用 CORS。
如果您为某个 `ANY` 方法启用 CORS 支持，则会为所有方法启用 CORS。
1. 在 **Access-Control-Allow-Headers** 输入字段中，输入静态字符串，该字符串是客户端必须在实际资源请求中提交的标头列表，以逗号分隔。使用控制台提供的 `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` 标头列表，或指定您自己的标头。
1. 将控制台提供的值 `'*'` 用作 **Access-Control-Allow-Origin** 标头值，以支持来自所有源的访问请求，或指定可以访问该资源的源。
1. 选择**保存**。
![\[选择允许的标头\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**重要**
如果在代理集成中将以上说明应用于 `ANY` 方法，那么将不会设置任何适用的 CORS 标头。相反，您的后端必须返回适用的 CORS 标头，例如 `Access-Control-Allow-Origin`。
在 `GET` 方法上启用 CORS 后，如果资源中没有 `OPTIONS` 方法，则该方法将添加到资源中。`OPTIONS` 方法的 `200` 响应会自动配置为返回三个 `Access-Control-Allow-*` 标头，以完成预检握手。此外，默认情况下，实际 (`GET`) 方法还会配置为在 200 响应内返回 `Access-Control-Allow-Origin` 标头。对于其他类型的响应，如果您不希望返回 `Cross-origin access` 错误，您将需要手动对其进行配置，以返回带有“\$1”或特定源的 `Access-Control-Allow-Origin'` 标头。
在您的资源上启用 CORS 支持后，您必须部署或重新部署 API 以使新设置生效。有关更多信息，请参阅 [创建 部署。](set-up-deployments.md#create-deployment)。
**注意**
如果按照此过程操作后无法在资源上启用 CORS 支持，我们建议您将您的 CORS 配置与示例 API `/pets` 资源进行比较。要了解如何创建示例 API，请参阅[教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)。
# 使用 API Gateway 导入 API 在资源上启用 CORS
如果您使用 [API Gateway 导入 API](api-gateway-import-api.md)，则可以使用 OpenAPI 文件设置 CORS 支持。您必须先在您的资源中定义可返回所需标头的 `OPTIONS` 方法。
**注意**
Web 浏览器预计接受 CORS 请求的每个 API 方法中会设置 Access-Control-Allow 标头和 Access-Control-Allow-Origin 标头。此外，某些浏览器首先向同一资源中的 `OPTIONS` 方法发出 HTTP 请求，然后预计收到相同的标头。
## `Options` 方法示例
以下示例创建了一个 `OPTIONS` 方法以进行模拟集成。
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
在您为资源配置 `OPTIONS` 方法后，可以将所需的标头添加到同一资源中需要接受 CORS 请求的其他方法。
1. 将 **Access-Control-Allow-Origin** 和**标头**声明为响应类型。
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. 在 `x-amazon-apigateway-integration` 标签中，为这些标头设置到静态值的映射：
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## API 示例
以下示例创建一个完整的 API，其中包含一个 `OPTIONS` 方法和一个集成了 `HTTP` 的 `GET` 方法。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# 在 CORS 中测试 API Gateway API
您可以通过调用 API 并检查响应中的 CORS 标头来测试 API 的 CORS 配置。以下 `curl` 命令将 OPTIONS 请求发送到已部署的 API。
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
响应中的 `Access-Control-Allow-Origin`、`Access-Control-Allow-Headers` 和 `Access-Control-Allow-Methods` 标头显示此 API 支持 CORS。有关更多信息，请参阅 [针对 API Gateway 中的 REST API 的 CORS](how-to-cors.md)。
# 针对 API Gateway 中的 REST API 的二进制媒体类型
在 API Gateway 中，API 请求和响应具有文本或二进制负载。文本负载是 `UTF-8` 编码的 JSON 字符串。二进制负载是文本负载以外的负载。例如，二进制负载可以是 JPEG 文件、GZip 文件或 XML 文件。支持二进制媒体所需的 API 配置取决于 API 是使用代理集成还是非代理集成。
如果您使用带有效载荷响应流式传输的代理集成，则无需配置二进制媒体类型。有关更多信息，请参阅 [在 API Gateway 中流式传输代理集成的集成响应](response-transfer-mode.md)。
## AWS Lambda 代理集成
要处理 AWS Lambda 代理集成的二进制负载，您必须对函数的响应进行 base64 编码。还必须为 API 配置 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)。API 的 `binaryMediaTypes` 配置是 API 视为二进制数据的内容类型的列表。示例二进制媒体类型包括 `image/png` 或 `application/octet-stream`。您可以使用通配符 (`*`) 来涵盖多种媒体类型。
API Gateway 使用来自客户端的第一个 `Accept` 标头来确定响应是否应返回二进制媒体。要在无法控制 `Accept` 标头值（如浏览器中的请求）的顺序时返回二进制媒体，请将 API 的二进制媒体类型设置为 `*/*`。
有关代码示例，请参阅 [从 API Gateway 中的 Lambda 代理集成返回二进制媒体](lambda-proxy-binary-media.md)。
如果您使用带有效载荷响应流式传输的 Lambda 代理集成，则无需配置二进制媒体类型。有关更多信息，请参阅 [在 API Gateway 中设置采用有效载荷响应流式传输的 Lambda 代理集成](response-transfer-mode-lambda.md)。
## 非代理集成
要处理非代理集成的二进制负载，请将媒体类型添加到 `RestApi` 资源的 [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) 列表中。API 的 `binaryMediaTypes` 配置是 API 视为二进制数据的内容类型的列表。或者，您可以设置 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 和 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 资源上的 [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) 属性。`contentHandling` 值可以是 `CONVERT_TO_BINARY`、`CONVERT_TO_TEXT` 或未定义。
**注意**
对于 `MOCK` 或私有集成，AWS 管理控制台中不支持设置 `contentHandling` 属性。您必须使用 AWS CLI、CloudFormation 或 SDK 来设置 `contentHandling` 属性。
根据 `contentHandling` 值，以及响应的 `Content-Type` 标头或传入请求的 `Accept` 标头是否匹配 `binaryMediaTypes` 列表中的某个条目，API Gateway 可以将原始二进制字节编码为 Base64 编码的字符串，将 Base64 编码的字符串解码回其原始字节，或者直接传递正文而不作修改。
您必须按如下方式配置 API，以对 API Gateway 中 API 的二进制负载提供支持：
+ 将所需的二进制媒体类型添加到 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源的 `binaryMediaTypes` 列表中。如果未定义此属性和 `contentHandling` 属性，会将负载作为 UTF-8 编码的 JSON 字符串进行处理。
+ 解决 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 资源的 `contentHandling` 属性。
+ 要将请求负载从 base64 编码的字符串转换为其二进制 blob，请将此属性设置为 `CONVERT_TO_BINARY`。
+ 要将请求负载从二进制 blob 转换为 base64 编码的字符串，请将此属性设置为 `CONVERT_TO_TEXT`。
+ 要在不修改的情况下传递负载，请将此属性保留为未定义。要在不修改的情况下传递二进制负载，还必须确保 `Content-Type` 与其中一个 `binaryMediaTypes` 条目匹配，并且已为 API 启用[传递行为](integration-passthrough-behaviors.md)。
+ 设置 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 资源的 `contentHandling` 属性。`contentHandling` 属性、客户端请求中的 `Accept` 标头以及 API 的 `binaryMediaTypes` 组合决定了 API Gateway 如何处理内容类型转换。有关详细信息，请参阅[API Gateway 中的内容类型转换](api-gateway-payload-encodings-workflow.md)。
**重要**
如果某个请求在其 `Accept` 标头中包含多个媒体类型，API Gateway 将只接受第一个 `Accept` 媒体类型。如果无法控制 `Accept` 媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个，则添加 API 的 `Accept` 列表中的第一个 `binaryMediaTypes` 媒体类型。API Gateway 将以二进制形式处理此列表中的所有内容类型。
例如，要在浏览器中使用 `![]()
` 元素发送 JPEG 文件，该浏览器可能会在请求中发送 `Accept:image/webp,image/*,*/*;q=0.8`。将 `image/webp` 添加到 `binaryMediaTypes` 列表后，终端节点将收到二进制形式的 JPEG 文件。
有关 API Gateway 如何处理文本和二进制负载的详细信息，请参阅 [API Gateway 中的内容类型转换](api-gateway-payload-encodings-workflow.md)。
# API Gateway 中的内容类型转换
API 的 `binaryMediaTypes`、客户端请求中的标头和集成 `contentHandling` 属性的组合决定了 API Gateway 对负载编码的方式。
下表显示了 API Gateway 如何转换某个请求的 `Content-Type` 标头的特定配置的请求有效载荷、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源的 `binaryMediaTypes` 列表以及 [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) 资源的 `contentHandling` 属性值。
| 方法请求负载 | 请求 `Content-Type` 标头 | `binaryMediaTypes` | `contentHandling` | 集成请求负载 |
| --- | --- | --- | --- | --- |
| 文本数据 | 任意数据类型 | 未定义 | 未定义 | UTF8 编码的字符串 |
| 文本数据 | 任意数据类型 | 未定义 | CONVERT\$1TO\$1BINARY | Base64 解码的二进制 blob |
| 文本数据 | 任意数据类型 | 未定义 | CONVERT\$1TO\$1TEXT | UTF8 编码的字符串 |
| 文本数据 | 文本数据类型 | 包含匹配的媒体类型的集合 | 未定义 | 文本数据 |
| 文本数据 | 文本数据类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | Base64 解码的二进制 blob |
| 文本数据 | 文本数据类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | 文本数据 |
| 二进制数据 | 二进制数据类型 | 包含匹配的媒体类型的集合 | 未定义 | 二进制数据 |
| 二进制数据 | 二进制数据类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | 二进制数据 |
| 二进制数据 | 二进制数据类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | Base64 编码的字符串 |
下表显示了 API Gateway 如何转换某个请求的 `Accept` 标头的特定配置的响应有效载荷、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源的 `binaryMediaTypes` 列表以及 [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) 资源的 `contentHandling` 属性值。
**重要**
如果某个请求在其 `Accept` 标头中包含多个媒体类型，API Gateway 将只接受第一个 `Accept` 媒体类型。如果无法控制 `Accept` 媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个，则添加 API 的 `Accept` 列表中的第一个 `binaryMediaTypes` 媒体类型。API Gateway 将以二进制形式处理此列表中的所有内容类型。
例如，要在浏览器中使用 `![]()
` 元素发送 JPEG 文件，该浏览器可能会在请求中发送 `Accept:image/webp,image/*,*/*;q=0.8`。将 `image/webp` 添加到 `binaryMediaTypes` 列表后，端点将收到二进制形式的 JPEG 文件。
| 集成响应负载 | 请求 `Accept` 标头 | `binaryMediaTypes` | `contentHandling` | 方法响应负载 |
| --- | --- | --- | --- | --- |
| 文本或二进制数据 | 文本类型 | 未定义 | 未定义 | UTF8 编码的字符串 |
| 文本或二进制数据 | 文本类型 | 未定义 | CONVERT\$1TO\$1BINARY | Base64 解码的 blob |
| 文本或二进制数据 | 文本类型 | 未定义 | CONVERT\$1TO\$1TEXT | UTF8 编码的字符串 |
| 文本数据 | 文本类型 | 包含匹配的媒体类型的集合 | 未定义 | 文本数据 |
| 文本数据 | 文本类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | Base64 解码的 blob |
| 文本数据 | 文本类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | UTF8 编码的字符串 |
| 文本数据 | 二进制类型 | 包含匹配的媒体类型的集合 | 未定义 | Base64 解码的 blob |
| 文本数据 | 二进制类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | Base64 解码的 blob |
| 文本数据 | 二进制类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | UTF8 编码的字符串 |
| 二进制数据 | 文本类型 | 包含匹配的媒体类型的集合 | 未定义 | Base64 编码的字符串 |
| 二进制数据 | 文本类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | 二进制数据 |
| 二进制数据 | 文本类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | Base64 编码的字符串 |
| 二进制数据 | 二进制类型 | 包含匹配的媒体类型的集合 | 未定义 | 二进制数据 |
| 二进制数据 | 二进制类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1BINARY | 二进制数据 |
| 二进制数据 | 二进制类型 | 包含匹配的媒体类型的集合 | CONVERT\$1TO\$1TEXT | Base64 编码的字符串 |
将文本负载转换为二进制 blob 时，API Gateway 假定文本数据是 Base64 编码的字符串，并将二进制数据作为 Base64 解码的 blob 输出。如果转换失败，它将返回一个 `500` 响应，指示出现 API 配置错误。尽管必须对 API 启用[传递行为](integration-passthrough-behaviors.md)，但您不用提供此类转换的映射模板。
将二进制负载转换为文本字符串时，API Gateway 始终对二进制数据应用 Base64 编码。您可以定义此类负载的映射模板，但只能通过 `$input.body` 访问映射模板中的 Base64 编码字符串，如映射模板示例的以下摘录中所示。
```
{
"data": "$input.body"
}
```
要直接传递二进制负载而不作修改，必须对 API 启用[传递行为](integration-passthrough-behaviors.md)。
# 使用 API Gateway 控制台启用二进制支持
本节说明如何使用 API Gateway 控制台启用二进制支持。例如，我们使用一个与 Amazon S3 集成的 API。我们的任务重点是设置受支持的媒体类型并指定如何处理负载。有关如何创建与 Amazon S3 集成的 API 的详细信息，请参阅[教程：创建 REST API 作为 Amazon S3 代理](integrating-api-with-aws-services-s3.md)。
**使用 API Gateway 控制台启用二进制支持**
1. 设置 API 的二进制媒体类型：
1. 创建新 API 或选择现有 API。在本例中，我们将 API 命名为 `FileMan`。
1. 在主导航面板中所选的 API 之下，选择 **API 设置**。
1. 在 **API 设置**窗格中的**二进制媒体类型**部分，选择**管理媒体类型**。
1. 选择**添加二进制媒体类型**。
1. 在文本输入字段中输入所需的媒体类型，例如 **image/png**。如果需要，请重复此步骤，添加更多媒体类型。要支持所有二进制媒体类型，请指定 `*/*`。
1. 选择**保存更改**。
1. 设置如何针对 API 方法处理消息负载：
1. 创建新资源或选择 API 中的现有资源。在本例中，我们使用 `/{folder}/{item}` 资源。
1. 对该资源创建新方法或选择一个现有方法。例如，我们使用与 Amazon S3 中的 `GET /{folder}/{item}` 操作集成的 `Object GET` 方法。
1. 对于**内容处理**，选择一个选项。
![\[在 API Gateway 控制台中设置 GET 方法。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
如果不想在客户端和后端接受相同的二进制格式时转换正文，则选择**传递**。当存在后端要求将二进制请求负载作为 JSON 属性传入等情况时，选择**转换为文本**以将二进制正文转换为 Base64 编码的字符串。当客户端提交 Base64 编码的字符串且后端需要原始二进制格式，或者当端点返回 Base64 编码的字符串且客户端只接受二进制输出时，选择**转换为二进制**。
1. 对于**请求正文传递**，选择**当未定义模板时（推荐）**，以在请求正文上启用传递行为。
您也可以选择**从不**。这意味着 API 将拒绝其内容类型没有映射模板的数据。
1. 在集成请求中保留传入请求的 `Accept` 标头。如果您已将 `contentHandling` 设置为 `passthrough` 并且希望在运行时覆盖该设置，则应执行此操作。
![\[在集成请求中保留 Accept 标头。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. 转换为文本时，请定义映射模板，以将 Base64 编码的二进制数据转换为所需格式。
以下是用于转换为文本的映射模板的示例：
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
此映射模板的格式取决于输入的端点要求。
1. 选择**保存**。
# 使用 API Gateway REST API 启用二进制支持
以下任务演示如何使用 API Gateway REST API 调用来启用二进制支持。
**Topics**
+ [向 API 添加和更新受支持的二进制媒体类型](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [配置请求负载转换](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [配置响应负载转换](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [将二进制数据转换为文本数据](#api-gateway-payload-encodings-convert-binary-to-string)
+ [将文本数据转换为二进制负载](#api-gateway-payload-encodings-convert-string-to-binary)
+ [传递二进制负载](#api-gateway-payload-encodings-pass-binary-as-is)
## 向 API 添加和更新受支持的二进制媒体类型
要允许 API Gateway 支持新的二进制媒体类型，必须将该二进制媒体类型添加到 `binaryMediaTypes` 资源的 `RestApi` 列表中。例如，要让 API Gateway 处理 JPEG 图像，应向 `PATCH` 资源提交 `RestApi` 请求：
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
属于 `image/jpeg` 属性值一部分的 MIME 类型规范 `path` 将转义为 `image~1jpeg`。
要更新受支持的二进制媒体类型，请替换或删除 `binaryMediaTypes` 资源的 `RestApi` 列表中的该媒体类型。例如，要将二进制支持从 JPEG 文件更改为原始字节，请向 `PATCH` 资源提交 `RestApi` 请求，如下所示：
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## 配置请求负载转换
如果端点需要二进制输入，则将 `contentHandling` 资源的 `Integration` 属性设置为 `CONVERT_TO_BINARY`。为此，请提交 `PATCH` 请求，如下所示：
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 配置响应负载转换
如果客户端接受二进制 blob 形式的结果而不是从端点返回的 Base64 编码的负载，则将 `IntegrationResponse` 资源的 `contentHandling` 属性设置为 `CONVERT_TO_BINARY`。为此，请提交 `PATCH` 请求，如下所示：
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## 将二进制数据转换为文本数据
要通过 API Gateway 将二进制数据作为输入的 JSON 属性发送到 AWS Lambda 或 Kinesis，请执行以下操作：
1. 通过将新的二进制媒体类型 `application/octet-stream` 添加到 API 的 `binaryMediaTypes` 列表，启用 API 的二进制负载支持。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. 在 `CONVERT_TO_TEXT` 资源的 `contentHandling` 属性上设置 `Integration`，并提供映射模板以将二进制数据的 Base64 编码字符串分配给 JSON 属性。在以下示例中，JSON 属性为 `body`，并且 `$input.body` 保存 Base64 编码的字符串。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## 将文本数据转换为二进制负载
假设 Lambda 函数返回一个 Base64 编码字符串形式的图像文件。要通过 API Gateway 将此二进制输出传递到客户端，请执行以下操作：
1. 通过添加二进制媒体类型 `binaryMediaTypes` (如果该类型尚不在列表中) 来更新 API 的 `application/octet-stream` 列表。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. 将 `contentHandling` 资源的 `Integration` 属性设置为 `CONVERT_TO_BINARY`。请勿定义映射模板。如果不定义映射模板，API Gateway 会调用传递模板，以将 Base64 解码的二进制 blob 作为图像文件返回给客户端。
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## 传递二进制负载
要使用 API Gateway 将图像存储在 Amazon S3 存储桶中，请执行以下操作：
1. 通过添加二进制媒体类型 `binaryMediaTypes`（如果该类型尚不在列表中）来更新 API 的 `application/octet-stream` 列表。
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. 在 `contentHandling` 资源的 `Integration` 属性上，设置 `CONVERT_TO_BINARY`。将 `WHEN_NO_MATCH` 设置为 `passthroughBehavior` 属性值，而不定义映射模板。这使 API Gateway 能够调用传递模板。
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# 导入和导出 API Gateway 的内容编码
要导入 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 上的 `binaryMediaTypes` 列表，请使用 API 的 OpenAPI 定义文件的以下 API Gateway 扩展。该扩展也用于导出 API 设置。
+ [x-amazon-apigateway-binary-media-types 属性](api-gateway-swagger-extensions-binary-media-types.md)
要导入和导出 `contentHandling` 或 `Integration` 资源的 `IntegrationResponse` 属性值，请使用 OpenAPI 定义的以下 API Gateway 扩展：
+ [x-amazon-apigateway-integration 对象](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integration.response 对象](api-gateway-swagger-extensions-integration-response.md)
# 从 API Gateway 中的 Lambda 代理集成返回二进制媒体
要从 [AWS Lambda 代理集成](set-up-lambda-proxy-integrations.md)返回二进制媒体，请对来自 Lambda 函数的响应进行 base64 编码。还必须[配置 API 的二进制媒体类型](api-gateway-payload-encodings-configure-with-console.md)。当您配置 API 的二进制媒体类型时，您的 API 会将该内容类型视为二进制数据。负载大小限制为 10 MB。
**注意**
要使用 Web 浏览器调用具有此示例集成的 API，请将 API 的二进制媒体类型设置为 `*/*`。API Gateway 使用来自客户端的第一个 `Accept` 标头来确定响应是否应返回二进制媒体。要在无法控制 `Accept` 标头值（如浏览器中的请求）的顺序时返回二进制媒体，请将 API 的二进制媒体类型设置为 `*/*`（对于所有内容类型）。
以下 Lambda 函数示例可以从 Amazon S3 返回二进制图像或将文本返回到客户端。该函数的响应包括一个 `Content-Type` 标头，用于向客户端指示它返回的数据类型。函数有条件地设置其响应中的 `isBase64Encoded` 属性，具体取决于它返回的数据类型。
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
}
}
```
------
#### [ Python ]
```
import base64
import boto3
import json
import random
s3 = boto3.client('s3')
def lambda_handler(event, context):
number = random.randint(0,1)
if number == 1:
response = s3.get_object(
Bucket='bucket-name',
Key='image.png',
)
image = response['Body'].read()
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64.b64encode(image).decode('utf-8'),
'isBase64Encoded': True
}
else:
return {
'headers': { "Content-type": "text/html" },
'statusCode': 200,
'body': "This is text
",
}
```
------
要了解有关二进制媒体类型的更多信息，请参阅 [针对 API Gateway 中的 REST API 的二进制媒体类型](api-gateway-payload-encodings.md)。
# 通过 API Gateway API 访问 Amazon S3 中的二进制文件
以下示例显示了用于访问 Amazon S3 中图像的 OpenAPI 文件如何从 Amazon S3 下载图像以及如何将图像上传到 Amazon S3。
**Topics**
+ [用于访问 Amazon S3 中图像的示例 API 的 OpenAPI 文件](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [从 Amazon S3 下载图像](#api-gateway-content-encodings-example-download-image-from-s3)
+ [将图像上传到 Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3)
## 用于访问 Amazon S3 中图像的示例 API 的 OpenAPI 文件
以下 OpenAPI 文件显示了一个示例 API，阐明了如何从 Amazon S3 下载图像文件以及如何将图像文件上传到 Amazon S3。此 API 公开了下载和上传指定图像文件所用的 `GET /s3?key={file-name}` 和 `PUT /s3?key={file-name}` 方法。`GET` 方法按照所提供的映射模板，在一个 200 OK 响应中返回 Base64 编码字符串形式的图像文件作为 JSON 输出的一部分。`PUT` 方法将原始二进制 blob 作为输入，并返回一个负载为空的 200 OK 响应。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 从 Amazon S3 下载图像
从 Amazon S3 下载二进制 blob 形式的图像文件 (`image.jpg`)：
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
成功的响应类似于以下示例：
```
200 OK HTTP/1.1
[raw bytes]
```
因为 `Accept` 标头设置为二进制媒体类型 `application/octet-stream`，并且您对 API 启用了二进制支持，所以返回原始字节。
要从 Amazon S3 下载采用 JSON 属性格式的 Base64 编码字符串形式的图像文件 (`image.jpg`)，请向 200 集成响应添加一个响应模板，如以下粗体 OpenAPI 定义块所示：
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
下载图像文件的请求如下所示：
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
成功响应如下所示：
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## 将图像上传到 Amazon S3
将二进制 blob 形式的图像文件 (`image.jpg`) 上传到 Amazon S3：
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
成功响应如下所示：
```
200 OK HTTP/1.1
```
将 Base64 编码字符串形式的图像文件 (`image.jpg`) 上传到 Amazon S3：
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
输入负载必须是 Base64 编码的字符串，因为 `Content-Type` 标头值设置为 `application/json`。成功响应如下所示：
```
200 OK HTTP/1.1
```
# 使用 API Gateway API 访问 Lambda 中的二进制文件
以下 OpenAPI 示例展示了如何通过 API Gateway API 访问 AWS Lambda 中的二进制文件。此 API 公开了用于下载和上传指定图像文件的 `GET /lambda?key={file-name}` 和 `PUT /lambda?key={file-name}` 方法。`GET` 方法按照所提供的映射模板，在一个 200 OK 响应中返回 Base64 编码字符串形式的图像文件作为 JSON 输出的一部分。`PUT` 方法将原始二进制 blob 作为输入，并返回一个负载为空的 200 OK 响应。
您创建 API 调用的 Lambda 函数，该函数必须返回 `Content-Type` 标头为 `application/json` 的 base64 编码字符串。
**Topics**
+ [用于访问 Lambda 中图像的示例 API 的 OpenAPI 文件](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [从 Lambda 下载图像](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [将图像上传到 Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda)
## 用于访问 Lambda 中图像的示例 API 的 OpenAPI 文件
以下 OpenAPI 文件显示了一个 API 示例，阐明了如何从 Lambda 下载图像文件以及如何将图像文件上传到 Lambda。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## 从 Lambda 下载图像
从 Lambda 下载二进制 blob 形式的图像文件 (`image.jpg`)：
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
成功响应如下所示：
```
200 OK HTTP/1.1
[raw bytes]
```
从 Lambda 下载 Base64 编码字符串（格式化为 JSON 属性）形式的图像文件 (`image.jpg`)：
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
成功响应如下所示：
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## 将图像上传到 Lambda
将二进制 blob 形式的图像文件 (`image.jpg`) 上传到 Lambda：
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
成功响应如下所示：
```
200 OK
```
将 Base64 编码字符串形式的图像文件 (`image.jpg`) 上传到 Lambda：
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
成功响应如下所示：
```
200 OK
```
# 调用 API Gateway 中的 REST API
为调用已部署的 API，客户端需要向 API Gateway 组件服务的 URL 提交请求以完成 API 执行（称为 `execute-api`）。
REST API 的基本 URL 采用以下格式：
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
其中，*api-id* 是 API 标识符，*region* 是 AWS 区域，*stage* 是 API 部署的阶段名称。
**重要**
在可以调用 API 之前，必须将其部署在 API Gateway 中。有关部署 API 的说明，请参阅[在 API Gateway 中部署 REST API。](how-to-deploy-api.md)。
**Topics**
+ [获取 API 的调用 URL](#apigateway-how-to-call-rest-api)
+ [调用 API](#apigateway-call-api)
+ [使用 API Gateway 控制台测试 REST API 方法](how-to-test-method.md)
+ [使用由 API Gateway 为 REST API 生成的 Java 开发工具包](how-to-call-apigateway-generated-java-sdk.md)
+ [使用由 API Gateway 为 REST API 生成的 Android 开发工具包](how-to-generate-sdk-android.md)
+ [使用由 API Gateway 为 REST API 生成的 JavaScript 开发工具包](how-to-generate-sdk-javascript.md)
+ [使用由 API Gateway 为 REST API 生成的 Ruby 开发工具包](how-to-call-sdk-ruby.md)
+ [在 Objective-C 或 Swift 中使用由 API Gateway 为 REST API 生成的 iOS 开发工具包](how-to-generate-sdk-ios.md)
## 获取 API 的调用 URL
您可以使用控制台、AWS CLI 或导出的 OpenAPI 定义来获取 API 的调用 URL。
### 使用控制台获取 API 的调用 URL
以下过程介绍了如何在 REST API 控制台中获取 API 的调用 URL。
**使用 REST API 控制台获取 API 的调用 URL**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择已部署的 API。
1. 从主导航窗格中选择**阶段**。
1. 在**阶段详细信息**下，选择复制图标以复制您 API 的调用 URL。
此 URL 用于您的 API 的根资源。
![\[创建 REST API 后，控制台会显示 API 的调用 URL。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. 要获取 API 中其它资源的 API 的调用 URL，请在二级导航窗格下展开此阶段，然后选择一个方法。
1. 选择复制图标来复制 API 的资源级调用 URL。
![\[您的 REST API 的资源级别 URL 位于阶段的二级导航窗格下方。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### 使用 AWS CLI 获取 API 的调用 URL
以下过程介绍了如何使用 AWS CLI 获取 API 的调用 URL。
**使用 AWS CLI 获取 API 的调用 URL**
1. 使用以下命令来获取 `rest-api-id`。此命令返回您的区域中的所有 `rest-api-id` 值。有关更多信息，请参阅 [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html)。
```
aws apigateway get-rest-apis
```
1. 将示例 `rest-api-id` 替换为您的 `rest-api-id`，将示例 *\$1stage-name\$1* 替换为您的 *\$1stage-name\$1*，将 *\$1region\$1* 替换为您的区域。
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### 使用 API 的已导出 OpenAPI 定义文件获取 API 的调用 URL
此外，您也可以构造根 URL，方法是组合 API 的已导出 OpenAPI 定义文件的 `host` 和 `basePath` 字段。有关如何导出 API 的说明，请参阅[从 API Gateway 导出 REST API](api-gateway-export-api.md)。
## 调用 API
您可以使用浏览器、curl 或其它应用程序（例如 [Postman](https://www.postman.com/)）调用已部署的 API。
此外，您可以使用 API Gateway 控制台测试 API 调用。测试使用 API Gateway 的 `TestInvoke` 特征，该特征允许在部署 API 之前对 API 进行测试。有关更多信息，请参阅 [使用 API Gateway 控制台测试 REST API 方法](how-to-test-method.md)。
**注意**
调用 URL 中的查询字符串参数值不得包含 `%%`。
### 使用 Web 浏览器调用 API
如果 API 允许匿名访问，您可以使用任何 Web 浏览器来调用任何 `GET` 方法。在浏览器的地址栏中输入完整的调用 URL。
对于其它方法或任何要求身份验证的调用，您必须指定负载或签署请求。您可以在 HTML 页面背后的脚本中，或者在使用 AWS 开发工具包之一的客户端应用程序中处理这些调用。
#### 使用 curl 调用 API
您可以在终端中使用像 [curl](https://curl.se/) 这样的工具来调用 API。以下示例 curl 命令在 API 的 `prod` 阶段的 `getUsers` 资源上调用 GET 方法。
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# 使用 API Gateway 控制台测试 REST API 方法
使用 API Gateway 控制台测试 REST API 方法。
**Topics**
+ [先决条件](#how-to-test-method-prerequisites)
+ [使用 API Gateway 控制台测试方法](#how-to-test-method-console)
## 先决条件
+ 您必须指定要测试的方法的设置。按照[API Gateway 中用于 REST API 的方法](how-to-method-settings.md)中的说明进行操作。
## 使用 API Gateway 控制台测试方法
**重要**
使用 API Gateway 控制台测试方法可能会导致对资源进行无法撤销的更改。使用 API Gateway 控制台测试方法与在 API Gateway 控制台之外调用方法相同。例如，如果您使用 API Gateway 控制台调用用于删除 API 资源的方法，并且方法调用成功，那么将删除 API 资源。
**测试方法**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 在**资源**窗格中，选择要测试的方法。
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
![\[使用“测试”选项卡来测试您的 API。它位于”方法响应”选项卡旁边。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
在任何显示的框中输入值（例如**查询字符串**、**标头**和**请求正文**。控制台会以默认 application/json 形式将这些值包括在方法请求中。
对于您可能需要指定的其它选项，请联系 API 所有者。
1. 选择**测试**。此时将显示以下信息：
+ **请求**是为方法调用的资源路径。
+ **状态**是响应的 HTTP 状态代码。
+ **延迟（毫秒）**是收到调用方请求和返回响应之间的时间。
+ **响应正文**是 HTTP 响应正文。
+ **响应标头**是 HTTP 响应标头。
**提示**
根据映射的不同，HTTP 状态代码、响应正文和响应标头可能不同于从 Lambda 函数、HTTP 代理或 AWS 服务代理发送的内容。
+ **日志** 是模拟的 Amazon CloudWatch Logs 条目，如果在 API Gateway 控制台之外调用此方法，则会写入这些条目。
**注意**
尽管 CloudWatch Logs 条目是模拟的，但方法调用的结果是真实的。
除了使用 API Gateway 控制台之外，您还可以使用 AWS CLI 或适用于 API Gateway 的 AWS 开发工具包来测试调用方法。要使用 AWS CLI 执行此操作，请参阅 [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)。
# 使用由 API Gateway 为 REST API 生成的 Java 开发工具包
在此部分中，我们将使用[简单结算器](simple-calc-lambda-api-swagger-definition.md) API 作为示例，概述使用由 API Gateway 为 REST API 生成的 Java 开发工具包的步骤。您必须先完成[为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md)中的步骤，然后才能继续操作。
**安装和使用 API Gateway 生成的 Java 开发工具包**
1. 提取您之前下载的 API Gateway 生成的 .zip 文件中的内容。
1. 下载并安装 [Apache Maven](https://maven.apache.org/)（必须为版本 3.5 或更高版本）。
1. 下载并安装 [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)。
1. 设置 `JAVA_HOME` 环境变量。
1. 转到 pom.xml 文件所在的解压缩的开发工具包文件夹。默认情况下，此文件夹为 `generated-code`。运行 **mvn install** 命令，将编译的构件文件安装到您的本地 Maven 存储库中。这将创建包含编译的开发工具包库的 `target` 文件夹。
1. 在空目录中输入以下命令来创建客户端项目存根，以使用已安装的开发工具包库来调用 API。
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**注意**
为提高可读性，在上述命令中添加了分隔符 `\`。整个命令应在一行中且不带分隔符。
此命令会创建一个应用程序存根。应用程序存根在项目的根目录（上述命令中的 *SimpleCalc-sdkClient*）下包含一个 `pom.xml` 文件和一个 `src` 文件夹。最初，有两个源文件：`src/main/java/{package-path}/App.java` 和 `src/test/java/{package-path}/AppTest.java`。在本示例中，*\$1package-path\$1* 为 `examples/aws/apig/simpleCalc/sdk/app`。此程序包路径源自 `DarchetypeGroupdId` 值。您可以使用 `App.java` 文件作为您的客户端应用程序模板，并且可以根据需要在同一文件夹中添加其他文件。您可以使用 `AppTest.java` 文件作为应用程序的单元测试模板，并且可以根据需要将其他测试代码文件添加到同一个测试文件夹中。
1. 在生成的 `pom.xml` 文件中将程序包依赖关系更新为以下内容，根据需要替换项目的 `groupId` `artifactId`、`version` 和 `name` 属性：
```
4.0.0
examples.aws.apig.simpleCalc.sdk.app
SimpleCalc-sdkClient
jar
1.0-SNAPSHOT
SimpleCalc-sdkClient
http://maven.apache.org
com.amazonaws
aws-java-sdk-core
1.11.94
my-apig-api-examples
simple-calc-sdk
1.0.0
junit
junit
4.12
test
commons-io
commons-io
2.5
org.apache.maven.plugins
maven-compiler-plugin
3.5.1
1.8
1.8
```
**注意**
当 `aws-java-sdk-core` 从属构件的较新版本与以上指定的版本 (`1.11.94`) 不兼容时，您必须将 `` 标记更新到新版本。
1. 接下来，我们将介绍如何通过调用开发工具包的 `getABOp(GetABOpRequest req)`、`getApiRoot(GetApiRootRequest req)` 和 `postApiRoot(PostApiRootRequest req)` 方法，来使用开发工具包调用 API。这些方法分别与 `GET /{a}/{b}/{op}`、`GET /?a={x}&b={y}&op={operator}` 和 `POST /` 方法对应，具有 `{"a": x, "b": y, "op": "operator"}` API 请求的负载。
按如下所示更新 `App.java` 文件：
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
在上述示例中，用于实例化开发工具包客户端的配置设置用于说明用途，并不一定是建议的最佳实践。此外，调用 `sdkClient.shutdown()` 是可选的，尤其是在您需要精确控制何时释放资源的情况下。
我们已介绍使用 Java 开发工具包调用 API 的基本模式。您可以扩展说明以调用其他 API 方法。
# 使用由 API Gateway 为 REST API 生成的 Android 开发工具包
在本部分中，我们介绍由 API Gateway 为 REST API 生成的 Android 开发工具包的使用步骤。您必须先完成[为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md)中的步骤，然后才能继续进行操作。
**注意**
生成的开发工具包与 Android 4.4 及更早版本不兼容。有关更多信息，请参阅 [Amazon API Gateway 重要说明](api-gateway-known-issues.md)。
**安装和使用由 API Gateway 生成的 Android 开发工具包**
1. 提取您之前下载的 API Gateway 生成的 .zip 文件中的内容。
1. 下载并安装 [Apache Maven](https://maven.apache.org/)（最好是版本 3.x）。
1. 下载并安装 [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)。
1. 设置 `JAVA_HOME` 环境变量。
1. 运行 **mvn install** 命令，将编译的构件文件安装到您的本地 Maven 存储库中。这将创建包含编译的开发工具包库的 `target` 文件夹。
1. 将 `target` 文件夹中的开发工具包文件（其名称源自您在生成开发工具包时指定的 **Artifact Id** 和 **Artifact Version**，如 `simple-calcsdk-1.0.0.jar`），以及 `target/lib` 文件夹中的所有文件夹库复制到项目的 `lib` 文件夹中。
如果您使用的是 Android Studio，请在客户端应用程序模块下创建一个 `libs` 文件夹，并将所需的 .jar 文件复制到此文件夹中。验证该模块的 Gradle 文件中的依赖项部分是否包含以下内容。
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
确保没有声明重复的 .jar 文件。
1. 使用 `ApiClientFactory` 类初始化 API Gateway 生成的开发工具包。例如：
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. 要使用 Amazon Cognito 凭证提供程序授权调用您的 API，请通过 API Gateway 生成的开发工具包使用 `ApiClientFactory` 类传递一组 AWS 凭证，如下例所示。
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. 要使用 API Gateway 生成的开发工具包设置 API 键，请使用与以下示例类似的代码。
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# 使用由 API Gateway 为 REST API 生成的 JavaScript 开发工具包
以下过程介绍如何使用 API Gateway 生成的 JavaScript SDK。
**注意**
这些说明假设您已完成[为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md)中的说明。
**重要**
如果您的 API 仅定义了 ANY 方法，则生成的开发工具包将不会包含 `apigClient.js` 文件，您将需要自己定义 ANY 方法。
**要安装，请启动并调用由 API Gateway 为 REST API 生成的 JavaScript 开发工具包**
1. 提取您之前下载的 API Gateway 生成的 .zip 文件中的内容。
1. 针对 API Gateway 生成的开发工具包将调用的所有方法启用跨源资源共享 (CORS)。有关说明，请参阅 [针对 API Gateway 中的 REST API 的 CORS](how-to-cors.md)。
1. 在您的网页中，添加对以下脚本的引用。
```
```
1. 在代码中，使用类似于以下内容的代码初始化 API Gateway 生成的开发工具包。
```
var apigClient = apigClientFactory.newClient();
```
要使用 AWS 凭证初始化 API Gateway 生成的开发工具包，请使用类似于以下内容的代码。如果您使用 AWS 凭证，系统将签署针对 API 的所有请求。
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
要将 API 密钥用于 API Gateway 生成的开发工具包，您可以使用类似于以下内容的代码，将 API 密钥作为参数传递给 `Factory` 对象。如果您使用 API 密钥，它将被指定为 `x-api-key` 标头的一部分，并且系统将签署针对 API 的所有请求。这意味着您必须为每个请求设置相应的 CORS Accept 标头。
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. 使用类似于以下内容的代码调用 API Gateway 中的 API 方法。每次调用都会返回成功和失败回调的承诺。
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
此处，*methodName* 由方法请求的资源路径和 HTTP 动词构成。对于 SimpleCalc API，API 方法的开发工具包方法为
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
相应的开发工具包方法如下所示：
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# 使用由 API Gateway 为 REST API 生成的 Ruby 开发工具包
以下过程介绍如何使用 API Gateway 生成的 Ruby SDK。
**注意**
这些说明假设您已完成[为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md)中的说明。
**要开始安装，请实例化并调用由 API Gateway 为 REST API 生成的 Ruby 开发工具包**
1. 解压缩下载的 Ruby 开发工具包文件。生成的开发工具包源如下所示。
![\[将下载的 Ruby 开发工具包文件解压缩到 Ruby 模块中\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. 从生成的开发工具包源构建 Ruby Gem，在终端窗口中使用以下 shell 命令：
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
在此之后，**simplecalc-sdk-1.0.0.gem** 变为可用状态。
1. 安装 gem：
```
gem install simplecalc-sdk-1.0.0.gem
```
1. 创建客户端应用程序。在应用程序中实例化和初始化 Ruby 开发工具包客户端：
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
如果 API 已经配置了 `AWS_IAM` 类型的授权，您可以在初始化期间提供 `accessKey` 和 `secretKey`，包括调用方的 AWS 凭证。
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. 在应用程序中通过开发工具包进行 API 调用。
**提示**
如果您不熟悉开发工具包方法调用约定，可以查看生成的开发工具包 `client.rb` 文件夹中的 `lib` 文件。该文件夹包含支持的各个 API 方法调用的文档。
搜索支持的操作：
```
# to show supported operations:
puts client.operation_names
```
这将生成以下显示内容，分别对应于 `GET /?a={.}&b={.}&op={.}`、`GET /{a}/{b}/{op}` 的 API 方法，以及 `POST /`，加上 `{a:"…", b:"…", op:"…"}` 格式的负载：
```
[:get_api_root, :get_ab_op, :post_api_root]
```
要调用 `GET /?a=1&b=2&op=+` API 方法，请调用以下 Ruby 开发工具包方法：
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
要使用 `POST /` 的负载调用 `{a: "1", b: "2", "op": "+"}` API 方法，请调用以下 Ruby 开发工具包方法：
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
要调用 `GET /1/2/+` API 方法，请调用以下 Ruby 开发工具包方法：
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
成功的开发工具包方法调用返回以下响应：
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# 在 Objective-C 或 Swift 中使用由 API Gateway 为 REST API 生成的 iOS 开发工具包
在本教程中，我们将介绍如何在 Objective-C 或 Swift 应用程序中使用由 API Gateway 为 REST API 生成的 iOS 开发工具包来调用底层 API。我们将使用 [SimpleCalc API](simple-calc-lambda-api.md) 作为示例来说明以下主题：
+ 如何将所需的 AWS 移动开发工具包组件安装到您的 Xcode 项目中
+ 如何在调用 API 的方法前创建 API 客户端对象
+ 如何通过 API 客户端对象上相应的 SDK 方法调用 API 方法
+ 如何使用 SDK 的相应模型类来准备方法输入并分析其结果
**Topics**
+ [使用生成的 iOS 开发工具包 (Objective-C) 来调用 API](#how-to-use-sdk-ios-objc)
+ [使用生成的 iOS 开发工具包 (Swift) 来调用 API](#how-to-generate-sdk-ios-swift)
## 使用生成的 iOS 开发工具包 (Objective-C) 来调用 API
在开始以下过程之前，您必须完成[为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md)中适用于 Objective-C 版 iOS 的步骤，并下载已生成的软件开发工具包的 .zip 文件。
### 在 Objective-C 项目中安装 AWS 移动开发工具包和 API Gateway 生成的 iOS 开发工具包
以下过程将介绍如何安装开发工具包。
**安装并使用 API Gateway 生成的 Objective-C 版 iOS 开发工具包**
1. 提取您之前下载的 API Gateway 生成的 .zip 文件中的内容。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能需要将解压的软件开发工具包文件夹重命名为类似 **sdk\$1objc\$1simple\$1calc** 的名字。此开发工具包文件夹中有一个 `README.md` 文件和一个 `Podfile` 文件。`README.md` 文件包含介绍如何安装和使用开发工具包的说明。本教程将提供有关这些说明的详细信息。安装过程会利用 [CocoaPods](https://cocoapods.org) 导入必需的 API Gateway 库和其他依赖的AWS移动开发工具包组件。您必须更新 `Podfile`，才能将开发工具包导入应用程序的 Xcode 项目中。解档开发工具包文件夹还包含一个 `generated-src` 文件夹，其中包含 API 已生成开发工具包的源代码。
1. 启动 Xcode，并创建一个新的 iOS Objective-C 项目。请记下该项目的目标。您需要在 `Podfile` 中对其进行设置。
![\[在 Xcode 中找到目标。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. 要使用 CocoaPods 将 AWS Mobile SDK for iOS 导入 Xcode 项目中，请执行以下操作：
1. 通过在终端窗口运行以下命令来安装 CocoaPods：
```
sudo gem install cocoapods
pod setup
```
1. 将 `Podfile` 文件从提取的开发工具包文件夹复制到包含 Xcode 项目文件的同一目录。将以下代码块：
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
替换为您的项目的目标名称：
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
如果 Xcode 项目已经包含名为 `Podfile` 的文件，请向其添加以下代码行：
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 打开终端窗口，并运行以下命令：
```
pod install
```
这将安装 API Gateway 组件和其他依赖的 AWS 移动开发工具包组件。
1. 关闭 Xcode 项目，然后打开 `.xcworkspace` 文件，以重新启动 Xcode。
1. 将已提取开发工具包的 `.h` 目录中的所有 `.m` 和 `generated-src` 文件添加到 Xcode 项目中。
![\[.h 和 .m 文件位于 generated-src 中\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
要通过显式下载 AWS Mobile SDK for iOS 移动开发工具包或使用 AWSCarthage[ 的方式将 ](https://github.com/Carthage/Carthage#installing-carthage) Objective-C 导入您的项目中，请遵循 *README.md* 文件中的说明。确保只使用以下选项之一来导入 AWS 移动开发工具包。
### 在 Objective-C 项目中使用 API Gateway 生成的 iOS 开发工具包调用 API 方法
当您为此 [SimpleCalc API](simple-calc-lambda-api.md) 生成具有 `SIMPLE_CALC` 前缀的开发工具包，并将两个模型用于方法的输入 (`Input`) 和输出 (`Result`) 时，在开发工具包中，由此产生的 API 客户端类将变成 `SIMPLE_CALCSimpleCalcClient`，而且相应数据类分别是 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 请求和响应映射到开发工具包方法，如下所示：
+ 以下 API 请求
```
GET /?a=...&b=...&op=...
```
将变为以下开发工具包方法
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
`AWSTask.result` 属性的类型是 `SIMPLE_CALCResult`，前提是 `Result` 模型已添加到该方法响应中。否则，属性的类型将是 `NSDictionary`。
+ 以下 API 请求
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
将变为以下开发工具包方法
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ 以下 API 请求
```
GET /{a}/{b}/{op}
```
将变为以下开发工具包方法
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
以下过程将介绍如何在 Objective-C 应用程序源代码中调用 API 方法；例如，作为 `viewDidLoad` 文件中 `ViewController.m` 委派的一部分进行调用。
**通过 API Gateway 生成的 iOS 开发工具包调用 API**
1. 导入 API 客户端类标头文件，使 API 客户端类可在该应用程序内调用：
```
#import "SIMPLE_CALCSimpleCalc.h"
```
`#import` 语句还将为两个模型类导入 `SIMPLE_CALCInput.h` 和 `SIMPLE_CALCResult.h`。
1. 实例化 API 客户端类：
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
要将 Amazon Cognito 和该 API 结合使用，请在默认的 `AWSServiceManager` 对象上设置 `defaultServiceConfiguration` 属性（如下所示），然后再调用 `defaultClient` 方法，以创建 API 客户端对象（如上一示例所示）：
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. 调用 `GET /?a=1&b=2&op=+` 方法以执行 `1+2`：
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
其中，帮助程序函数 `handleApiResponse:task` 会将结果格式设定为要在文本字段 (`_textField1`) 中显示的字符串。
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
最终显示为 `1 + 2 = 3`。
1. 使用负载调用 `POST /` 以执行 `1-2`：
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
最终显示为 `1 - 2 = -1`。
1. 调用 `GET /{a}/{b}/{op}` 以执行 `1/2`：
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
最终显示为 `1 div 2 = 0.5`。在这里，`div` 用于代替 `/`，因为后端的[简单 Lambda 函数](simple-calc-nodejs-lambda-function.md)不会处理 URL 编码的路径变量。
## 使用生成的 iOS 开发工具包 (Swift) 来调用 API
在开始以下过程之前，您必须完成 [为 API Gateway 中的 REST API 生成 SDK](how-to-generate-sdk.md) 中适用于 Swift 版 iOS 的步骤，并下载已生成的开发工具包的 .zip 文件。
**Topics**
+ [在 Swift 项目中安装 AWS 移动开发工具包和 API Gateway 生成的开发工具包](#use-sdk-ios-swift-install-sdk)
+ [在 Swift 项目中通过 API Gateway 生成的 iOS 开发工具包调用 API 方法](#use-sdk-ios-swift-call-api)
### 在 Swift 项目中安装 AWS 移动开发工具包和 API Gateway 生成的开发工具包
以下过程将介绍如何安装开发工具包。
**安装并使用 API Gateway 生成的 Swift 版 iOS 开发工具包**
1. 提取您之前下载的 API Gateway 生成的 .zip 文件中的内容。使用 [SimpleCalc API](simple-calc-lambda-api.md)，您可能需要将解压的软件开发工具包文件夹重命名为类似 **sdk\$1swift\$1simple\$1calc** 的名字。此开发工具包文件夹中有一个 `README.md` 文件和一个 `Podfile` 文件。`README.md` 文件包含介绍如何安装和使用开发工具包的说明。本教程将提供有关这些说明的详细信息。安装过程会利用 [CocoaPods](https://cocoapods.org) 导入必需的 AWS 移动开发工具包组件。您必须更新 `Podfile`，才能将开发工具包导入 Swift 应用程序的 Xcode 项目中。解档开发工具包文件夹还包含一个 `generated-src` 文件夹，其中包含 API 已生成开发工具包的源代码。
1. 启动 Xcode，并创建一个新的 iOS Swift 项目。请记下该项目的目标。您需要在 `Podfile` 中对其进行设置。
![\[在 Xcode 中找到目标。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. 要使用 CocoaPods 将必需的 AWS 移动开发工具包组件导入 Xcode 项目中，请执行以下操作：
1. 如果 CocoaPods 还未安装，请在终端窗口中运行以下命令进行安装：
```
sudo gem install cocoapods
pod setup
```
1. 将 `Podfile` 文件从提取的开发工具包文件夹复制到包含 Xcode 项目文件的同一目录。将以下代码块：
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
替换为您的项目的目标名称，如下所示：
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
如果 Xcode 项目已经包含带有正确目标的 `Podfile`，您只需将以下代码行添加到 `do ... end` 循环：
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. 打开终端窗口，并在应用程序目录中运行以下命令：
```
pod install
```
这会将 API Gateway 组件及任何依赖的 AWS 移动开发工具包组件安装到应用程序的项目中。
1. 关闭 Xcode 项目，然后打开 `*.xcworkspace` 文件，以重新启动 Xcode。
1. 将已提取 `.h` 目录中所有开发工具包的标头文件 (`.swift`) 和 Swift 源代码文件 (`generated-src`) 添加到您的 Xcode 项目中。
![\[.h 和 .swift 文件位于 generated-src 中\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. 为了能够从 Swift 代码项目调用 AWS 移动开发工具包的 Objective-C 库，请在 Xcode 项目配置的 `Bridging_Header.h`Swift Compiler - General** 设置下，在 **Objective-C Bridging Header** 属性上设置 ** 文件路径：
![\[在“Swift 编译器 - 通用”下设置 Bridging_Header.h 文件路径。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**提示**
您可以通过在 Xcode 的搜索框中键入 **bridging** 来找到 **Objective-C Bridging Header** 属性。
1. 构建 Xcode 项目，以在继续进行操作之前验证它是否正确配置。如果与 AWS 移动开发工具包支持的 Swift 版本相比，您的 Xcode 使用了更新的版本，那么您将收到 Swift 编译器错误。在这种情况下，在 **Swift Compiler - Version** 设置下方将 **Use Legacy Swift Language Version (使用传统 Swift 语言版本)** 属性设置为**是**：
![\[将“旧版 Swift 语言版本”属性设置为“是”。\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
要通过显式下载AWS移动软件开发工具包或使用 [Carthage](https://github.com/Carthage/Carthage#installing-carthage)，将 Swift 中的AWS移动版 SDK for iOS 导入您的项目中，请按照开发工具包随附的 `README.md` 文件中的说明操作。确保只使用以下选项之一来导入 AWS 移动开发工具包。
### 在 Swift 项目中通过 API Gateway 生成的 iOS 开发工具包调用 API 方法
当您为此 [SimpleCalc API](simple-calc-lambda-api.md) 生成具有 `SIMPLE_CALC` 前缀的开发工具包，并通过两个模型描述 API 请求和响应的输入 (`Input`) 和输出 (`Result`) 时，在开发工具包中，由此产生的 API 客户端类将变成 `SIMPLE_CALCSimpleCalcClient`，而且相应数据类分别是 `SIMPLE_CALCInput` 和 `SIMPLE_CALCResult`。API 请求和响应映射到开发工具包方法，如下所示：
+ 以下 API 请求
```
GET /?a=...&b=...&op=...
```
将变为以下开发工具包方法
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
`AWSTask.result` 属性的类型是 `SIMPLE_CALCResult`，前提是 `Result` 模型已添加到该方法响应中。否则，它的类型将是 `NSDictionary`。
+ 以下 API 请求
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
将变为以下开发工具包方法
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ 以下 API 请求
```
GET /{a}/{b}/{op}
```
将变为以下开发工具包方法
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
以下过程将介绍如何在 Swift 应用程序源代码中调用 API 方法；例如，作为 `viewDidLoad()` 文件中 `ViewController.m` 委派的一部分进行调用。
**通过 API Gateway 生成的 iOS 开发工具包调用 API**
1. 实例化 API 客户端类：
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
要将 Amazon Cognito 与 API 结合使用，请设置默认 AWS 服务配置（如下所示），然后再获取 `default` 方法（如之前所示）：
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. 调用 `GET /?a=1&b=2&op=+` 方法以执行 `1+2`：
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
其中，帮助程序函数 `self.showResult(task)` 会将结果或错误打印到控制台；例如：
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
在生产应用程序中，您可以在文本字段中显示结果或错误。最终显示为 `1 + 2 = 3`。
1. 使用负载调用 `POST /` 以执行 `1-2`：
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
结果显示为 `1 - 2 = -1`。
1. 调用 `GET /{a}/{b}/{op}` 以执行 `1/2`：
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
最终显示为 `1 div 2 = 0.5`。在这里，`div` 用于代替 `/`，因为后端的[简单 Lambda 函数](simple-calc-nodejs-lambda-function.md)不会处理 URL 编码的路径变量。
# 在 API Gateway 中使用 OpenAPI 开发 REST API
您可以使用 API Gateway 将 REST API 从外部定义文件导入到 API Gateway。目前，API Gateway 支持 [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 和 [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 定义文件，但[Amazon API Gateway 关于 REST API 的重要说明](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis)中列出了例外。您可以使用新定义覆盖 API 以进行更新，还可以将定义与现有 API 合并。您使用 `mode` 查询参数指定请求 URL 中的选项。
有关从 API Gateway 控制台使用导入 API 功能的教程，请参阅 [教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [将边缘优化的 API 导入 API Gateway](import-edge-optimized-api.md)
+ [将区域 API 导入到 API Gateway 中](import-export-api-endpoints.md)
+ [导入 OpenAPI 文件以更新现有 API 定义](api-gateway-import-api-update.md)
+ [设置 OpenAPI `basePath` 属性](api-gateway-import-api-basePath.md)
+ [用于 OpenAPI 导入的 AWS 变量](import-api-aws-variables.md)
+ [将 API 导入 API Gateway 时出现的错误和警告](api-gateway-import-api-errors-warnings.md)
+ [从 API Gateway 导出 REST API](api-gateway-export-api.md)
# 将边缘优化的 API 导入 API Gateway
您可以导入 API 的 OpenAPI 定义文件，在 OpenAPI 文件之外通过指定 `EDGE` 端点类型作为导入操作的附加输入，创建新的边缘优化的 API。您可以使用 API Gateway 控制台、AWS CLI 或 AWS SDK 执行此操作。
有关从 API Gateway 控制台使用导入 API 特征的教程，请参阅 [教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [使用 API Gateway 控制台导入边缘优化的 API](#import-edge-optimized-api-with-console)
+ [使用 AWS CLI 导入边缘优化的 API](#import-edge-optimized-api-with-awscli)
## 使用 API Gateway 控制台导入边缘优化的 API
要使用 API Gateway 控制台导入边缘优化的 API，请执行以下操作：
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择**创建 API**。
1. 在**REST API**中，选择 **Import**（导入）。
1. 复制 API 的 OpenAPI 定义并将其粘贴到代码编辑器中，或者选择**选择文件**以从本地驱动器加载 OpenAPI 文件。
1. 对于 **API 端点类型**，选择**边缘优化**。
1. 选择**创建 API** 以开始导入 OpenAPI 定义。
## 使用 AWS CLI 导入边缘优化的 API
以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令从 OpenAPI 定义文件导入 API，以创建边缘优化的新 API：
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
或者使用到 `EDGE` 的 `endpointConfigurationTypes` 查询字符串参数的明确规范：
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 将区域 API 导入到 API Gateway 中
导入 API 时，您可以为 API 选择区域端点配置。您可以使用 API Gateway 控制台、AWS CLI 或 AWS SDK。
导出 API 时，API 端点配置不包括在导出的 API 定义中。
有关从 API Gateway 控制台使用导入 API 特征的教程，请参阅 [教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)。
**Topics**
+ [使用 API Gateway 控制台导入区域 API](#import-regional-api-with-console)
+ [使用 AWS CLI 导入区域 API](#import-regional-api-with-awscli)
## 使用 API Gateway 控制台导入区域 API
要使用 API Gateway 控制台导入区域端点的 API，请执行以下操作：
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择**创建 API**。
1. 在**REST API**中，选择 **Import**（导入）。
1. 复制 API 的 OpenAPI 定义并将其粘贴到代码编辑器中，或者选择**选择文件**以从本地驱动器加载 OpenAPI 文件。
1. 对于 **API 端点类型**，选择**区域**。
1. 选择**创建 API** 以开始导入 OpenAPI 定义。
## 使用 AWS CLI 导入区域 API
使用以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令导入 OpenAPI 定义文件，并将端点类型设置为“区域”：
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 导入 OpenAPI 文件以更新现有 API 定义
您只能导入 API 定义来更新现有 API，无需更改其终端节点配置以及阶段或阶段变量，或者引用 API 密钥。
导入到更新操作可以使用两种模式进行：合并和覆盖。
当一个 API (`A`) 合并到另一个 (`B`) 中时，如果两个 API 中没有互相冲突的定义，生成的 API 会保留 `A` 和 `B` 两者的定义。如果出现冲突，合并 API (`A`) 的方法定义会覆盖接受并入的 API (`B`) 的相应方法定义。例如，假设 `B` 声明了以下方法，用于返回 `200` 和 `206` 响应：
```
GET /a
POST /a
```
`A` 声明了以下方法，用于返回 `200` 和 `400` 响应：
```
GET /a
```
如果 `A` 并入 `B` 中，生成的 API 会生成以下方法：
```
GET /a
```
返回 `200` 和 `400` 响应，以及
```
POST /a
```
返回 `200` 和 `206` 响应。
当您将外部 API 定义分解为多个较小的部分，并希望一次只应用其中一个部分的更改时，合并 API 非常有用。例如，如果多个团队负责一个 API 的不同部分并以不同的速度提供更改，则可能会出现此情况。在这种模式下，没有在导入的定义中明确定义的现有 API 中的项目会被忽略。
如果一个 API (`A`) 覆盖另一个 API (`B`)，生成的 API 将采纳覆盖方 API (`A`) 的定义。当外部 API 定义包含一个 API 的完整定义时，覆盖 API 非常有用。在这种模式下，没有在导入的定义中明确定义的现有 API 中的项目会被删除。
要合并 API，请将一个 `PUT` 请求提交至 `https://apigateway..amazonaws.com/restapis/?mode=merge`。`restapi_id` 路径参数值指定了将要与提供的 API 定义合并的 API。
以下代码段显示了一个 `PUT` 请求的示例，该请求将作为负载的 JSON 格式的 OpenAPI API 定义与 API Gateway 中已指定的 API 合并。
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
合并更新操作需要提取两个完整的 API 定义并将它们合并到一起。对于小型增量变更，您可以使用[资源更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)操作。
要覆盖 API，请将一个 `PUT` 请求提交至 `https://apigateway..amazonaws.com/restapis/?mode=overwrite`。`restapi_id` 路径参数指定了将要被提供的 API 定义覆盖的 API。
以下代码段显示了一个覆盖请求的示例，该请求的负载为 JSON 格式 OpenAPI 定义：
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
如果未指定 `mode` 查询参数，则系统会假定合并。
**注意**
`PUT` 操作是幂等操作，不是原子操作。这意味着如果在处理过程中出现系统错误，则 API 可能会以不良状态结束。但是，重复该操作会成功将 API 置于相同的最终状态，如同第一次操作已成功一样。
# 设置 OpenAPI `basePath` 属性
在 [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 中，您可以使用 `basePath` 属性来提供 `paths` 属性中定义的每个路径之前的一个或多个路径部分。由于 API Gateway 具有多种表达资源路径的方式，因此导入 API 功能可提供以下选项用于解释导入过程中的 `basePath` 属性：ignore、prepend 和 split。
在 [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/) 中，`basePath` 不再是顶级属性。相反，作为惯例，API Gateway 使用[服务器变量](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)。导入 API 功能提供了相同选项用于解释导入过程中的基本路径。按如下所示标识基本路径：
+ 如果 API 不包含任何 `basePath` 变量，则导入 API 功能将检查 `server.url` 字符串以查看其是否包含 `"/"` 之外的路径。如果包含，则将该路径用作基本路径。
+ 如果 API 仅包含一个 `basePath` 变量，则导入 API 功能将使用其作为基本路径，即使该变量未在 `server.url` 中进行引用。
+ 如果 API 包含多个 `basePath` 变量，则导入 API 功能将仅使用第一个变量作为基本路径。
## 忽略
如果 OpenAPI 文件的 `basePath` 值为 `/a/b/c` 且 `paths` 属性包含 `/e` 和 `/f`，则以下 `POST` 或 `PUT` 请求：
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
将在 API 中生成以下资源：
+ `/`
+ `/e`
+ `/f`
效果是将 `basePath` 视为不存在，所有声明的 API 资源均相对于主机提供。例如，如果您有一个自定义域名，其 API 映射不包含*基础路径*和表示生产阶段的*阶段*值，则可以使用这一选项。
**注意**
API Gateway 自动为您创建一个根资源，即使该资源未在定义文件中明确声明。
如未指定，`basePath` 以 `ignore` 为默认值。
## 前置
如果 OpenAPI 文件的 `basePath` 值为 `/a/b/c` 且 `paths` 属性包含 `/e` 和 `/f`，则以下 `POST` 或 `PUT` 请求：
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
将在 API 中生成以下资源：
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
效果是将 `basePath` 视为指定其他资源 (不含方法) 并将这些资源添加到声明的资源组中。例如，如果不同的团队负责一个 API 的不同部分且 `basePath` 可以为每个团队所负责 API 部分引用路径位置，则可以使用这一选项。
**注意**
API Gateway 自动为您创建中间资源，即使这些资源未在定义中明确声明。
## Split
如果 OpenAPI 文件的 `basePath` 值为 `/a/b/c` 且 `paths` 属性包含 `/e` 和 `/f`，则以下 `POST` 或 `PUT` 请求：
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
将在 API 中生成以下资源：
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
效果是将最顶层的路径部分 `/a` 视为每个资源路径的开始，并在 API 自身内创建其他资源 (不含方法)。例如，如果 `a` 是一个您想在 API 中使用的阶段名称，则可以使用这一选项。
# 用于 OpenAPI 导入的 AWS 变量
您可以在 OpenAPI 定义中使用以下 AWS 变量。API Gateway 在导入 API 时解析变量。要指定变量，请使用 `${variable-name}`。下表介绍了可用的 AWS 变量。
| 变量名称 | 描述 |
| --- | --- |
| AWS::AccountId | 导入 API 的 AWS 账户 ID。例如，123456789012。 |
| AWS::Partition | 在其中导入 API 的 AWS 分区。对于标准 AWS 区域，分区是 aws。 |
| AWS::Region | 在其中导入 API 的 AWS 区域。例如，us-east-2。 |
## AWS 变量示例
以下示例使用 AWS 变量为集成指定 AWS Lambda 函数。
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# 将 API 导入 API Gateway 时出现的错误和警告
在将外部定义文件导入 API Gateway 时，API Gateway 可能会生成警告和错误。以下部分讨论导入过程中可能出现的错误和警告。
## 导入过程中出现错误
在导入过程中，可能会因 OpenAPI 文档无效等严重问题而产生错误。系统会在不成功响应中将错误作为异常（如 `BadRequestException`）返回。出现错误时，新的 API 定义会被丢弃，现有 API 不会发生更改。
## 导入过程中出现警告
在导入过程中，可能会因缺失模型引用等轻微问题而产生警告。出现警告时，如果请求 URL 中附加了 `failonwarnings=false` 查询表达式，则操作将会继续。否则更新就会回滚。默认情况下，将 `failonwarnings` 设置为 `false`。在这种情况下，系统会在生成的 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 资源中以字段形式返回警告。否则，系统会将警告作为异常中的一条消息返回。
# 从 API Gateway 导出 REST API
使用 API Gateway 控制台或其他方式在 API Gateway 中创建和配置 REST API 后，您可以使用 API Gateway 导出 API（该 API 是 Amazon API Gateway 控制服务的一部分）将其导出到 OpenAPI 文件。要使用 API Gateway 导出 API，您需要签署您的 API 请求。有关签署请求的更多信息，请参阅《IAM 用户指南》**中的[签署 AWS API 请求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。您可以在导出的 OpenAPI 定义文件中包含 API Gateway 集成扩展以及 [Postman](https://www.postman.com) 扩展。
**注意**
使用 AWS CLI 导出 API 时，请务必包含扩展参数，如以下示例所示，以确保包含 `x-amazon-apigateway-request-validator` 扩展：
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
如果 API 的负载并非 `application/json` 类型，则您无法将其导出。如果尝试导出，您将收到一条错误响应，指出未找到 JSON 正文模型。
## 请求导出 REST API
借助 Export API，您可以提交 GET 请求，将要导出的 REST 指定为 URL 路径的一部分，以此来导出现有 REST API。请求 URL 的格式如下：
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
您可以附加 `extensions` 查询字符串，以指定是否要包含 API Gateway 扩展（含 `integration` 值）或 Postman 扩展（含 `postman` 值）。
此外，您还可以将 `Accept` 标头设置为 `application/json` 或 `application/yaml`，以分别接收 JSON 格式或 YAML 格式的 API 定义输出。
有关使用 API Gateway 导出 API 提交 GET 请求的更多信息，请参阅 [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)。
**注意**
如果您在 API 中定义模型，那么这些模型的内容类型必须为“application/json”，这样 API Gateway 才能将其导出。否则，API Gateway 会引发异常，并显示“仅找到适用于……的非 JSON 正文模型”的错误消息。
模型必须包含属性或者被定义为特定 JSONSchema 类型。
## 下载 JSON 格式的 REST API OpenAPI 定义
要下载 JSON 格式的 REST API OpenAPI 定义，请执行以下操作：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
这里的 `` 可以是 (比如说) `us-east-1`。有关提供 API Gateway 的所有区域，请参阅 [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)。
## 下载 YAML 格式的 REST API OpenAPI 定义
要下载 YAML 格式的 REST API OpenAPI 定义，请执行以下操作：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## 借助 Postman 扩展下载 JSON 格式的 REST API OpenAPI 定义
借助 Postman 导出并下载 JSON 格式的 REST API OpenAPI 定义，请执行以下操作：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## 借助 API Gateway 集成下载 YAML 格式的 REST API OpenAPI 定义
要借助 API Gateway 集成导出并下载 YAML 格式的 REST API OpenAPI 定义，请执行以下操作：
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## 使用 API Gateway 控制台导出 REST API
[将 REST API 部署到一个阶段](set-up-deployments.md#create-deployment)之后，您可以使用 API Gateway 控制台将此阶段中的 API 导出到 OpenAPI 文件。
在 API Gateway 控制台的**阶段**窗格中，选择**阶段操作**，然后选择**导出**。
![\[使用 API Gateway 控制台导出 REST API\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/export-new-console.png)
指定 **API 规范类型**、**格式**和**扩展**以下载您 API 的 OpenAPI 定义。