REST API、HTTP API 和 WebSocket API 的重要提示 REST API 和 WebSocket API 的重要提示 WebSocket API 的重要提示 REST API 的重要提示

Amazon API Gateway 重要说明

下一节详细说明了可能影响您使用 API Gateway 的注意事项。

主题

Amazon API Gateway 关于 REST API、HTTP API 和 WebSocket API 的重要提示
Amazon API Gateway 关于 REST 和 WebSocket API 的重要说明
Amazon API Gateway 关于 WebSocket API 的重要说明
Amazon API Gateway 关于 REST API 的重要说明

Amazon API Gateway 关于 REST API、HTTP API 和 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 用户指南。）维度值是用户定义名称的函数，包括 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 传递给后端集成。
使用 API Gateway 控制台测试 API 时，如果向后端提供自签名证书、证书链中缺少中间证书，或后端引发了任何其他无法识别的证书相关异常情况，那么您可能会收到“未知端点错误”响应。
对于具有私有集成的 API Resource 或 Method 实体，您应删除对 VpcLink 的任意硬编码引用。否则，您会具有不固定的集成，并收到错误，说明 VPC 链接仍在使用，即使 Resource 或 Method 实体已删除。在私有集成通过阶段变量引用 VpcLink 时，此行为不适用。
以下后端可能无法通过与 API Gateway 兼容的方式来支持 SSL 客户端身份验证：
- NGINX
- Heroku
API Gateway 支持大多数 OpenAPI 2.0 规范和 OpenAPI 3.0 规范，但下列情况除外：
- 路径段只能包含字母数字字符、下划线、连字符、句点、逗号、冒号和大括号。路径参数必须为单独的路径段。例如，“resource/{path_parameter_name}”为有效；而“resource{path_parameter_name}” 为无效。
- 模型名称只能包含字母数字字符。
- 对于输入参数，仅支持以下属性：name、in、required、type、description。其他属性将被忽略。
- securitySchemes 类型（如果使用）必须为 apiKey。但是，支持通过 Lambda 授权方进行 OAuth 2 和 HTTP 基本身份验证；OpenAPI 配置通过供应商扩展实现。
- deprecated 字段不受支持且将在导出的 API 中删除。
- API Gateway 模型是使用 JSON 架构草案 4 定义的，而不是 OpenAPI 使用的 JSON 架构。
- 任何架构对象均不支持 discriminator 参数。
- 不支持 example 标记。
- exclusiveMinimumAPI Gateway 不支持。
- 简单请求验证中不包括 maxItems 和 minItems 标记。要解决此问题，请在导入之后、执行验证之前更新模型。
- 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 表示标头名称从 <string> 更改为 X-Amzn-Remapped-<string>。

Remapped Overwritten 表示标头名称从 <string> 更改为 X-Amzn-Remapped-<string>，并且值被覆盖。

标头名称	请求 (`http`/`http_proxy`/`lambda`)	响应 (`http`/`http_proxy`/`lambda`)
`Age`	传递	传递
`Accept`	传递	已删除/传递/传递
`Accept-Charset`	传递	传递
`Accept-Encoding`	传递	传递
`Authorization`	传递*	已重新映射
`Connection`	传递/传递/已删除	已重新映射
`Content-Encoding`	传递/已删除/传递	传递
`Content-Length`	传递（基于正文生成）	传递
`Content-MD5`	已删除	已重新映射
`Content-Type`	传递	传递
`Date`	传递	重新映射被覆盖
`Expect`	已删除	已删除
`Host`	已覆盖到集成端点	已删除
`Max-Forwards`	已删除	已重新映射
`Pragma`	传递	传递
`Proxy-Authenticate`	已删除	已删除
`Range`	传递	传递
`Referer`	传递	传递
`Server`	已删除	重新映射被覆盖
`TE`	已删除	已删除
`Transfer-Encoding`	已删除/已删除/例外	已删除
`Trailer`	已删除	已删除
`Upgrade`	已删除	已删除
`User-Agent`	传递	已重新映射
`Via`	已删除/已删除/传递	传递/已删除/已删除
`Warn`	传递	传递
`WWW-Authenticate`	已删除	已重新映射

* 如果 Authorization 标头包含签名版本 4 签名，或者如果使用 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 将您的内容以二进制形式返回。例如，要在浏览器中使用 <img> 元素发送 JPEG 文件，该浏览器可能会在请求中发送 Accept:image/webp,image/*,*/*;q=0.8。将 image/webp 添加到 binaryMediaTypes 列表后，端点将收到二进制形式的 JPEG 文件。
当前不支持自定义 413 REQUEST_TOO_LARGE 的默认网关响应。
API Gateway 对所有集成响应使用 Content-Type 标头。默认情况下，内容类型为 application/json。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

配额和重要提示

文档历史记录