了解路径模板

在 API Gateway 中，可以根据路径模板路由传入的请求。路径模板包含三个主要组件：

• 完全匹配
• 单通配符匹配
• 双通配符匹配

以下各部分介绍了其中每个组件及其在 API Gateway 环境中的工作原理。

完全匹配

不含任何单通配符或双通配符段（* 或 **）的模板化路径会转换为精确路径匹配。例如，网关 API 配置的 OpenAPI 规范可能包含如下部分：

...
paths:
  /shelves:
    get:
      summary: List shelves
...

在此示例中，网关仅接受对 /shelves 的请求，而不接受其他路径。

注意： 网址编码的正斜杠 (%2F) 不会被视为实际正斜杠，这意味着 %2Fshelves 不会匹配规范中前面描述的 OpenAPI 操作。

单通配符匹配

如果模板化路径包含变量和/或单个通配符段（{var} 或 {var=*}，仅限 OpenAPI 2.0），则网关将允许符合以下条件的传入请求：

• 请求不包含额外的正斜杠 (/)，这意味着变量将仅匹配一个路径段。
• 请求至少包含一个字符。
• 如果路径末尾有额外的尾部斜杠，请求可能包含该斜杠。

注意：对于变量扩展，除 [-_.~/0-9a-zA-Z] 之外的所有字符都采用百分比编码。

例如，网关 API 配置的 OpenAPI 规范可能包含如下部分：

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
...

在此示例中，网关将接受与以下正则表达式匹配的请求：

^/shelves/[^/]+/books/[^/]+/?$

注意： 如果您使用的是 OpenAPI 3.x 规范，则不支持 /shelves/{shelf=*}/books/{book=*} 语法，系统会拒绝该语法。

双通配符匹配

如果模板化路径包含由双通配符段表示的变量（例如 {var=**}），则网关将允许符合以下条件的传入请求：

• 请求可以包含所有字符，包括正斜杠 (/)。
• 请求可以包含 0 个或多个字符。
• 如果路径末尾有额外的尾部斜杠，请求可能包含该斜杠。

注意： 如果您使用的是 OpenAPI 3.x 规范，则不支持双通配符语法。对于 OpenAPI 2.0 规范，双通配符变量只能在所提供路径的最后一个段中使用。这意味着不允许使用 /shelves/{shelf=**}/books/{book=**}，因为未在路径的最后一段中声明 {shelf=**}。对于变量扩展，[-_.~/0-9a-zA-Z] 以外的所有字符均采用百分比编码。

例如，网关 API 配置的 OpenAPI 规范可能包含如下部分：

OpenAPI 2.0

...
paths:
  /shelves/{shelf=*}/books/{book=**}:
    get:
      summary: Retrieve a book
...

OpenAPI 3.x

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
      parameters:
      - name: shelf
        in: path
        schema:
          type: string
      - name: book
        in: path
        schema:
          type: string
        x-google-parameter:
          pattern: '**'
...

在此示例中，网关将接受 book 参数与任何字符（包括正斜杠）匹配的请求。这对应于以下正则表达式：

^/shelves/[^/]+/books/.*/?$

网址编码正斜线

API Gateway 遵循 RFC 3986，在匹配网址路径或安全决策时，不会将网址编码的正斜杠 (%2F) 视为实际斜杠。如果需要使用网址编码斜杠，您的后端应相应地处理这些请求。

警告：如果您的后端预期在匹配 API Gateway 路径模板时会将网址编码的正斜杠 (%2F) 视为实际斜杠，则包含网址编码正斜杠的请求可能会匹配操作并导致对后端资源的特权过高。

例如，请考虑以下 OpenAPI 规范：

securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
paths:
  /shelves/{shelf}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        summary: List shelves
        operationId: GetShelf
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    /shelves/{shelf}/books/{book}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        - in: path
          name: book
          type: string
          required: true
          description: Book ID
        summary: Retrieve a book
        operationId: GetBook
          responses:
            '200':
              description: A successful response
              schema:
                type: string
         security:
         - api_key: []

在此示例中，/shelves/{shelf}/books/{book} 操作需要 API 密钥，但 /shelves/{shelf} 操作不受限制。

如果用户向 /shelves/shelf_1%2Fbooks%2Fbook_2 发送请求，则执行以下操作：

• 网关会将请求作为书架 ID shelf_1%2Fbooks%2Fbook_2 的 GetShelf 操作处理。在这种情况下，API 密钥检查未强制执行。
• 如果在后端进行任何请求处理之前将 %2F 标准化，则请求可能会作为图书 ID book_2 的 GetBook 操作进行处理。换句话说，后端将 /shelves/shelf_1%2Fbooks%2Fbook_2 处理为 /shelves/shelf_1/books/book_2。

在此示例中，后端期望 GetBook 操作在网关执行 API 密钥检查。但是，由于网关以 GetShelf 操作的形式读取请求，因此未执行 API 密钥检查。

多个相邻正斜线的标准化

API Gateway 遵循 RFC 3986，指出具有多个相邻正斜杠的路径将被视为与具有单正斜杠的路径不同。

例如，包含 /shelves/// 的请求将不会由网关进行标准化到请求路径 /shelves/，无论是在匹配 URI 路径模板之前还是在转发到指定的后端时。

警告 ：如果您的后端通过将多个正斜杠合并到单个斜杠来标准化网址路径，则包含多个相邻正斜杠的请求可能会匹配意外的网关操作，并且可能会导致过度特权对您的后端资源的访问权限。

语法规则

API Gateway 对路径模板实施了多项语法验证规则：

• 变量命名惯例：变量名称必须以字母（小写或大写）或下划线 (_) 开头，并且只能包含字母、数字、下划线、点号 (.) 和连字符 (-)。
  • 有效值：{my_var}、{var-1}、{var.name}
  • 无效：{1var}、{my var}
• 不得混合使用参数和字面值：单个路径段不得同时包含参数和字面值字符。
  • 有效：/prefix/{var}
  • 无效：/prefix-{var}、/{var}suffix
• 允许使用的自定义方法后缀：混合使用形参和字面值的唯一例外情况是路径的最后一个段，其中允许使用以英文冒号 (:) 开头的自定义方法后缀。
  • 有效：/{var}:customMethod
  • 无效：/{var}:customMethod/suffix
• 每个段不得包含多个参数：单个路径段不得包含多个参数。
  • 有效：/{var1}/{var2}
  • 无效：/{var1}{var2}
• 无嵌套参数：参数不能相互嵌套。
  • 有效：/{var}
  • 无效：/{{var}}
• 双通配符：双通配符段只能位于最后一个路径段中。
  • 有效值：/prefix/{var=**}、/prefix/**
  • 无效：/{var=**}/suffix、/**/suffix

限制

限制	值
每个路径的形参数量	60
变量名称长度	100
路径长度（无论是否使用模板）	512