Amazon API Gateway 重要说明 - Amazon API Gateway
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 的重要提示

  • 签名版本 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 客户端身份验证：

  • 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。