瞭解路徑範本

在 API Gateway 中，您可以根據路徑範本，將傳入要求進行路由。路徑範本有三個主要元件：

  • 完全比對
  • 單一萬用字元比對
  • 重複萬用字元比對

以下各節將說明這些元件，以及在 API Gateway 環境中如何運作。

完全符合

範本路徑不含任何單或雙萬用字元片段 (* 或 **) 會轉換為完全相符的路徑。舉例來說，閘道 API 設定的 OpenAPI 規格可能包含以下部分：

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

在這個範例中，閘道「只會」接受對 /shelves 的請求，不會接受其他路徑。

單一萬用字元比對

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

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

舉例來說，閘道 API 設定的 OpenAPI 規格可能包含以下部分：

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

在這個例子中，閘道會接受符合下列規則運算式的要求：

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

雙萬用字元比對

如果範本路徑包含由雙萬用字元片段 (例如 {var=**}) 表示的變數，閘道就會允許符合下列條件的傳入要求：

  • 要求可包含所有字元，包括正斜線 (/)。
  • 要求可包含 0 個或更多字元。
  • 如果路徑結尾有斜線，要求可能會包含額外的結尾斜線。

舉例來說，閘道 API 設定的 OpenAPI 規格可能包含以下部分：

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

在這個例子中，閘道會接受符合下列規則運算式的要求：

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

網址編碼正斜線

API Gateway 遵循 RFC 3986 標準，在比對路由或安全性決策的網址路徑時，不會將網址編碼正斜線 (%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 路徑範本時也不會在轉送至指定後端時。