パス テンプレートについて

API Gateway 内では、パス テンプレートに基づいて受信リクエストをルーティングできます。パス テンプレートには次の 3 つの主要コンポーネントがあります。

  • 完全一致
  • 単一のワイルドカード マッチング
  • 2 個のワイルドカード マッチング

以下の各セクションでは、これらの各コンポーネントと、API Gateway のコンテキスト内での動作について説明します。

完全一致

単一または 2 個のワイルドカード セグメント（* または **）を含まないテンプレート化されたパスは、正確なパス一致に変換されます。たとえば、Gateway API 構成の OpenAPI 仕様に、次のようなセクションが含まれている場合があります。

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

この例では、ゲートウェイは /shelves へのリクエストのみを受け入れ、他のパスは受け入れません。

単一のワイルドカード マッチング

テンプレート化されたパスに変数、単一のワイルドカード セグメント（{var} や {var=*} など）、またはその両方が含まれている場合、ゲートウェイは以下の内容に従う受信リクエストを許可します。

  • リクエストには追加のスラッシュ（/）が含まれないため、変数は 1 つのパスセグメントにのみ一致する。
  • リクエストに 1 つ以上の文字が含まれています。
  • パスの末尾にスラッシュがある場合、リクエストの末尾にスラッシュが含まれることがある。

たとえば、Gateway API 構成の OpenAPI 仕様に、次のようなセクションが含まれている場合があります。

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

この例では、ゲートウェイは次の正規表現に一致するリクエストを受け入れます。

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

2 個のワイルドカード マッチング

テンプレート化されたパスに、2 個のワイルドカード セグメントで示される変数（{var=**} など）が含まれている場合、ゲートウェイは以下に従う受信リクエストを許可します。

  • リクエストにはスラッシュ（/）を含めてすべての文字を含めることができます。
  • リクエストには 0 文字以上を含めることができます。
  • パスの末尾にスラッシュがある場合、リクエストの末尾にスラッシュが含まれることがある。

たとえば、Gateway API 構成の OpenAPI 仕様に、次のようなセクションが含まれている場合があります。

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

この例では、ゲートウェイは次の正規表現に一致するリクエストを受け入れます。

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

URL エンコードされたスラッシュ

API Gateway は、RFC 3986 に準拠します。ルーティングまたはセキュリティに関する決定を行うための URL パスの照合時に、URL エンコードされたスラッシュ（%2F）は実際のスラッシュとして扱われません。URL エンコードされたスラッシュが想定される場合、バックエンドはこれらのリクエストを想定内容に応じて処理する必要があります。

たとえば、次の 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/// を含むリクエストは、URI パス テンプレートと照合する前や、指定したバックエンドへの転送時に、ゲートウェイによってリクエストパス /shelves/ に正規化されません。