瞭解路徑範本

在 API Gateway 中，可以根據路徑範本轉送傳入要求。 路徑範本包含三個主要元件：

• 完全比對
• 單一萬用字元比對
• 雙萬用字元比對

下列各節將說明這些元件，以及這些元件在 API Gateway 環境中的運作方式。

完全符合

如果範本路徑沒有任何單一或雙萬用字元區隔 (* 或 **)，系統會將其轉換為完全相符的路徑。舉例來說，閘道 API 設定的 OpenAPI 規格可能包含下列部分：

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

在本例中，閘道只會接受對 /shelves 的要求，不會接受其他路徑的要求。

注意： 經過網址編碼的正斜線 (%2F) 不會視為實際的正斜線，也就是說，%2Fshelves「不會」與規格中稍早說明的 OpenAPI 作業相符。

單一萬用字元比對

如果範本路徑包含變數、單一萬用字元片段 ({var})，或僅限 OpenAPI 2.0 的單一萬用字元片段 ({var=*})，閘道會允許符合下列條件的傳入要求：

• 要求不含額外的正斜線 (/)，表示變數只會比對單一路徑片段。
• 要求至少包含一個字元。
• 如果路徑結尾有尾端斜線，要求可能包含額外的尾端斜線。

注意： 變數擴展時，除了 [-_.~/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=*} 語法，且會拒絕該語法。

Double Wildcard Matching

如果範本路徑包含以雙萬用字元片段表示的變數 (例如 {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 閘道遵循 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 路徑範本，也不會轉送至指定的後端。

警告： 如果後端會將多個正斜線合併為單一斜線，藉此正規化網址路徑，則含有多個相鄰正斜線的要求可能會比對到非預期的閘道作業，導致後端資源的存取權過於寬鬆。