パス テンプレートについて
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
が正規化されている場合、リクエストは書籍 IDbook_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/
に正規化されません。