Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

Amazon API Gateway 重要提示

有关 REST 和 WebSocket API 的 Amazon API Gateway 重要提示

  • API Gateway 不支持通配符子域名(*.domain 形式)。但它支持通配符证书(用于通配符子域名的证书)。

  • API Gateway 不支持跨 REST 和 WebSocket API 共享自定义域名。

  • 阶段名称只能包含字母数字字符、连字符和下划线。最大长度为 128 个字符。

  • 系统会保留 /ping/sping 路径用于服务运行状况检查。将这些路径用于带有自定义域的 API 根级资源将无法产生预期的结果。

  • 目前,API Gateway 将日志事件限制为 1024 个字节。超过 1024 个字节的日志事件(如请求和响应正文)将被 API Gateway 截断,然后再提交到 CloudWatch 日志。

  • CloudWatch 指标当前将维度名称和值限制为 255 个有效的 XML 字符。(有关更多信息,请参阅 CloudWatch 用户指南。) 维度值是用户定义名称的函数,包括 API 名称、标签(阶段)名称和资源名称。选择这些名称时,请注意不要超出 CloudWatch 指标限制。

WebSocket API 的 Amazon API Gateway 重要提示

  • API Gateway 支持最大 128 KB 的消息负载,最大帧大小为 32 KB。如果消息超过 32 KB,则必须将其拆分为多个帧,每个 32 KB 或更小。如果接收到更大的消息,则连接会关闭并显示代码 1009。

REST API 的Amazon API Gateway 重要提示

  • 任何请求 URL 查询字符串都不支持纯文本竖线字符 (|),必须对该字符进行 URL 编码。

  • 不支持分号字符 (;) 的任何请求中的 URL 查询字符串和结果数据被拆分。

  • 使用 API Gateway 控制台测试 API 时,如果向后端提供自签名证书、证书链中缺少中间证书,或后端出现任何其他无法识别的证书相关异常情况,那么您可能会收到“未知终端节点错误”响应。

  • 对于具有私有集成的 API ResourceMethod 实体,您应删除对 VpcLink 的任意硬编码引用。否则,您会具有不固定的集成,并收到错误,说明 VPC 链接仍在使用,即使 ResourceMethod 实体已删除。在私有集成通过阶段变量引用 VpcLink 时,此行为不适用。

  • 以下后端可能无法通过与 API Gateway 兼容的方式来支持 SSL 客户端身份验证:

  • API Gateway 支持大多数 OpenAPI 2.0 规范OpenAPI 3.0 规范,但下列情况除外:

    • 路径段只能包含字母数字字符、连字符、句点、逗号和大括号。路径参数必须为单独的路径段。例如,“resource/{path_parameter_name}”为有效;而“resource{path_parameter_name}”" 为无效。

    • 模型名称只能包含字母数字字符。

    • securitySchemes 类型(如果使用)必须为 apiKey。但是,支持通过 Lambda 授权方进行 OAuth 2 和 HTTP 基本身份验证;OpenAPI 配置通过供应商扩展实现。

    • deprecated 字段不受支持且将在导出的 API 中删除。

    • API Gateway 模型是使用 JSON 架构草案 4 定义的,而不是 OpenAPI 使用的 JSON 架构。

    • 模型中不支持 additionalPropertiesanyOf字段。

    • 任何架构对象均不支持 discriminator 参数。

    • 不支持 example 标记。

    • API Gateway 不支持 exclusiveMinimum

    • 简单请求验证中不包括 maxItemsminItems 标记。要解决此问题,请在导入之后、执行验证之前更新模型。

    • API Gateway 不支持 oneOf

    • API Gateway 不支持 pattern

    • 不支持 readOnly 字段。

    • OpenAPI 文档根目录不支持 "500": {"$ref": "#/responses/UnexpectedError"} 表单的响应定义。要解决此问题,请使用内联架构替换参考。

    • 不支持 Int32Int64 类型的数字。下面展示了一个示例:

      "elementId": { "description": "Working Element Id", "format": "int32", "type": "number" }
    • 架构定义不支持十进制数字格式类型 ("format": "decimal")。

    • 在方法响应中,架构定义必须为对象类型,不能是基元类型。例如,不支持 "schema": { "type": "string"}。但是,您可以使用以下对象类型解决此问题:

      "schema": { "$ref": "#/definitions/StringResponse" } "definitions": { "StringResponse": { "type": "string" } }
  • 当使用 Lambda 集成或 HTTP 集成处理方法时,API Gateway 会施加以下限制:

    • 对于标头名称和查询参数,会以区分大小写的方式进行处理。

    • 当被发送到集成终端节点或由集成终端节点发回时,以下标头可能会被删除、重新映射或以其他方式修改:

      标头名称 请求 (http/http_proxy/lambda) 响应 (http/http_proxy/lambda)
      Age 传递 传递
      Accept 传递 已删除/传递/传递
      Accept-Charset 传递 传递
      Accept-Encoding 传递 传递
      Authorization 已删除 (400) 已重新映射
      Connection 传递/传递/已删除 已重新映射
      Content-Encoding 传递/已删除/传递 传递
      Content-Length 传递(基于正文生成) 传递
      Content-MD5 已删除 已重新映射
      Content-Type 传递 传递
      Date 传递 重新映射被覆盖
      Expect 已删除 已删除
      Host 5XX/5XX/被 Lambda 覆盖 已删除
      Max-Forwards 已删除 已重新映射
      Pragma 传递 传递
      Proxy-Authenticate 已删除 已删除
      Range 传递 传递
      Referer 传递 传递
      Server 已删除 重新映射被覆盖
      TE 已删除 已删除
      Transfer-Encoding 已删除/已删除/例外 已删除
      Trailer 已删除 已删除
      Upgrade 已删除 已删除
      User-Agent 传递 已重新映射
      Via 已删除/已删除/传递 传递/已删除/已删除
      Warn 传递 传递
      WWW-Authenticate 已删除 已重新映射
  • 由 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 并忽略任何其他内容类型的规范。