# Amazon API Gateway 重要说明
下一节详细说明了可能影响您使用 API Gateway 的注意事项。
**Topics**
+ [Amazon API Gateway 关于 HTTP API 的重要说明](#api-gateway-known-issues-http-apis)
+ [Amazon API Gateway 关于 HTTP 和 WebSocket API 的重要说明](#api-gateway-known-issues-http-and-websocket-apis)
+ [Amazon API Gateway 关于 REST 和 WebSocket API 的重要说明](#api-gateway-known-issues-rest-and-websocket-apis)
+ [Amazon API Gateway 关于 WebSocket API 的重要说明](#api-gateway-known-issues-websocket-apis)
+ [Amazon API Gateway 关于 REST API 的重要说明](#api-gateway-known-issues-rest-apis)
## Amazon API Gateway 关于 HTTP API 的重要说明
+ HTTP API 将传入的 `X-Forwarded-*` 标头转换为标准 `Forwarded` 标头，并将附加出口 IP、主机和协议。
+ 如果没有有效载荷且 Content-Length 为 0，API Gateway 会将 Content-type 标头添加到您的请求中。
## Amazon API Gateway 关于 HTTP 和 WebSocket API 的重要说明
+ 对于 HTTP 和 WebSocket API，签名版本 4A 不受 Amazon API Gateway 正式支持。
## Amazon API Gateway 关于 REST 和 WebSocket API 的重要说明
+ API Gateway 不支持跨 REST 和 WebSocket API 共享自定义域名。
+ 阶段名称只能包含字母数字字符、连字符和下划线。最大长度为 128 个字符。
+ 系统会保留 `/ping` 和 `/sping` 路径用于服务运行状况检查。将这些路径用于带有自定义域的 API 根级资源将无法产生预期的结果。
+ 目前，API Gateway 将日志事件限制为 1024 个字节。超过 1024 个字节的日志事件 (如请求和响应正文) 将被 API Gateway 截断，然后再提交到 CloudWatch 日志。
+ CloudWatch 指标当前将维度名称和值限制为 255 个有效的 XML 字符。（有关更多信息，请参阅 [CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)。） 维度值是用户定义名称的函数，包括 API 名称、标签（阶段）名称和资源名称。选择这些名称时，请注意不要超出 CloudWatch 指标限制。
+ 映射模板的最大大小为 300 KB。
## Amazon API Gateway 关于 WebSocket API 的重要说明
+ API Gateway 支持最大 128 KB 的消息负载，最大帧大小为 32 KB。如果消息超过 32 KB，则必须将其拆分为多个帧，每个 32 KB 或更小。如果接收到更大的消息，则连接会关闭并显示代码 1009。
## Amazon API Gateway 关于 REST API 的重要说明
+ 任何请求 URL 查询字符串都不支持纯文本竖线字符（`|`）和大括号字符（`{` 或 `}`），必须对这些字符进行 URL 编码。
+ 不支持分号字符 (`;`) 的任何请求中的 URL 查询字符串和结果数据被拆分。
+ REST API 在将 URL 编码的请求参数传递给后端集成之前对其进行解码。对于 UTF-8 请求参数，REST API 会对参数进行解码，然后将其作为 unicode 传递给后端集成。REST API 会先对百分比字符（`%`）进行 URL 编码，然后再传递给后端集成。
+ 使用 API Gateway 控制台测试 API 时，如果向后端提供自签名证书、证书链中缺少中间证书，或后端引发了任何其他无法识别的证书相关异常情况，那么您可能会收到“未知端点错误”响应。
+ 对于具有私有集成的 API [https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 或 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 实体，您应删除对 [https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) 的任意硬编码引用。否则，您会具有不固定的集成，并收到错误，说明 VPC 链接仍在使用，即使 `Resource` 或 `Method` 实体已删除。在私有集成通过阶段变量引用 `VpcLink` 时，此行为不适用。
+ 以下后端可能无法通过与 API Gateway 兼容的方式来支持 SSL 客户端身份验证：
+ [NGINX](https://nginx.org/en/)
+ [Heroku](https://www.heroku.com/)
+ API Gateway 支持大多数 [OpenAPI 2.0 规范](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)和 [OpenAPI 3.0 规范](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md)，但下列情况除外：
+ 路径段只能包含字母数字字符、下划线、连字符、句点、逗号、冒号和大括号。路径参数必须为单独的路径段。例如，“resource/\$1path\$1parameter\$1name\$1”为有效；而“resource\$1path\$1parameter\$1name\$1” 为无效。
+ 模型名称只能包含字母数字字符。
+ 对于输入参数，仅支持以下属性：`name`、`in`、`required`、`type`、`description`。其他属性将被忽略。
+ `securitySchemes` 类型（如果使用）必须为 `apiKey`。但是，支持通过 [Lambda 授权方](apigateway-use-lambda-authorizer.md)进行 OAuth 2 和 HTTP 基本身份验证；OpenAPI 配置通过[供应商扩展](api-gateway-swagger-extensions-authorizer.md)实现。
+ `deprecated` 字段不受支持且将在导出的 API 中删除。
+ API Gateway 模型是使用 [JSON 架构草案 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) 定义的，而不是 OpenAPI 使用的 JSON 架构。
+ 任何架构对象均不支持 `discriminator` 参数。
+ 不支持 `example` 标记。
+ 不支持 `nullable` 字段。
+ `exclusiveMinimum`API Gateway 不支持 。
+ [简单请求验证](api-gateway-method-request-validation.md)中不包括 `maxItems` 和 `minItems` 标签。要解决此问题，请在导入之后、执行验证之前更新模型。
+ 对于 OpenAPI 3.0，您不能在同一个架构中具有对定义使用 `$ref` 的 `oneOf`、`anyOf` 或 `allOf`。您可以直接输入架构，也可以定义单独的 API Gateway 模型资源。有关更多信息，请参阅 [创建更复杂的模型](models-mappings-models.md#api-gateway-request-validation-model-more-complex)。
+ `oneOf` 不支持 OpenAPI 2.0 或生成 SDK。
+ 不支持 `readOnly` 字段。
+ `$ref` 不能用于引用其他文件。
+ OpenAPI 文档根目录不支持 `"500": {"$ref": "#/responses/UnexpectedError"}` 表单的响应定义。要解决此问题，请使用内联架构替换参考。
+ 不支持 `Int32` 或 `Int64` 类型的数字。下面展示了一个示例：
```
"elementId": {
"description": "Working Element Id",
"format": "int32",
"type": "number"
}
```
+ 架构定义不支持十进制数字格式类型 (`"format": "decimal"`)。
+ 在方法响应中，架构定义必须为对象类型，不能是基元类型。例如，不支持 `"schema": { "type": "string"}`。但是，您可以使用以下对象类型解决此问题：
```
"schema": {
"$ref": "#/definitions/StringResponse"
}
"definitions": {
"StringResponse": {
"type": "string"
}
}
```
+ API Gateway 不使用在 OpenAPI 规范中定义的根级别安全性。因此，需要在操作级别上定义安全性以正确应用。
+ 不支持该 `default` 关键字。
+ 当使用 Lambda 集成或 HTTP 集成处理方法时，API Gateway 会施加以下限制：
+ 对于标头名称和查询参数，会以区分大小写的方式进行处理。
+ 下表列出了在发送到集成端点或由集成端点发回时，可能会被删除、重新映射或以其他方式修改的标头：在此表中：
+ `Remapped` 表示标头名称从 `` 更改为 `X-Amzn-Remapped-`。
`Remapped Overwritten` 表示标头名称从 `` 更改为 `X-Amzn-Remapped-`，并且值被覆盖。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/api-gateway-known-issues.html)
\$1 如果 `Authorization` 标头包含[签名版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) 签名，或者如果使用 `AWS_IAM` 授权，则会删除此标头。
+ 由 API Gateway 生成的 API 的 Android 开发工具包使用 `java.net.HttpURLConnection` 类。如果将 `WWW-Authenticate` 标头重新映射到 `X-Amzn-Remapped-WWW-Authenticate` 导致了 401 响应，那么该类将在运行 Android 4.4 及更早版本的设备上引起未处理的异常。
+ 与 API Gateway 生成的 API 的 Java、Android 和 iOS 开发工具包不同，API Gateway 生成的 API 的 JavaScript 开发工具包不支持针对 500 级错误进行重试。
+ 方法的测试调用使用默认内容类型 `application/json` 并忽略任何其他内容类型的规范。
+ 通过传递 `X-HTTP-Method-Override` 标头将请求发送到 API 时，API Gateway 覆盖方法。因此，要将标头传递到后端，该标头需要添加到集成请求中。
+ 如果某个请求的 `Accept` 标头包含多个媒体类型，API Gateway 将只接受第一个 `Accept` 媒体类型。如果无法控制 `Accept` 媒体类型的顺序并且二进制内容的媒体类型不是列表中的第一个，您可以添加 API 的 `Accept` 列表中的第一个 `binaryMediaTypes` 媒体类型，API Gateway 将您的内容以二进制形式返回。例如，要在浏览器中使用 `![]()
` 元素发送 JPEG 文件，该浏览器可能会在请求中发送 `Accept:image/webp,image/*,*/*;q=0.8`。将 `image/webp` 添加到 `binaryMediaTypes` 列表后，端点将收到二进制形式的 JPEG 文件。
+ 当前不支持自定义 `413 REQUEST_TOO_LARGE` 的默认网关响应。
+ API Gateway 对所有集成响应使用 `Content-Type` 标头。默认情况下，内容类型为 `application/json`。