HTTP API のルートの使用

ルートは、直接の受信 API リクエストをバックエンドリソースにルーティングします。ルートは、HTTP メソッドとリソースパスという 2 つの部分で構成されます (例: GET /pets)。ルートに特定の HTTP メソッドを定義できます。または、ANY メソッドを使用して、リソースに対して定義していないすべてのメソッドを一致させることができます。他のどのルートとも一致しないリクエストのキャッチオールとして機能する $default ルートを作成できます。

注記

API Gateway は、URL エンコードされたリクエストパラメータをデコードしてからバックエンド統合に渡します。

パス変数の操作

HTTP API ルートでパス変数を使用できます。

たとえば、GET /pets/{petID} ルートは、クライアントが GET に送信する https://api-id.execute-api.us-east-2.amazonaws.com/pets/6 リクエストをキャッチします。

greedy パス変数は、ルートのすべての子リソースをキャッチします。greedy パス変数を作成するには、変数名に + を追加します (例: {proxy+})。greedy パス変数は、リソースパスの末尾にある必要があります。

クエリ文字列パラメータの操作

デフォルトでは、API Gateway は HTTP API へのリクエストにクエリ文字列パラメータが含まれている場合、バックエンド統合にクエリ文字列パラメータを送信します。

たとえば、クライアントが https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog にリクエストを送信すると、クエリ文字列パラメータ ?id=4&type=dog が統合に送信されます。

$default ルートの操作

$default ルートは、API 内の他のルートと明示的に一致しないリクエストをキャッチします。

$default ルートがリクエストを受信すると、API Gateway は完全なリクエストパスを統合に送信します。たとえば、$default ルートのみを持つ API を作成し、ANY メソッドで https://petstore-demo-endpoint.execute-api.com HTTP エンドポイントと統合できます。https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout にリクエストを送信すると、API Gateway は https://petstore-demo-endpoint.execute-api.com/store/checkout にリクエストを送信します。

HTTP 統合の詳細については、「HTTP API の HTTP プロキシ統合の使用」を参照してください。

API リクエストのルーティング

クライアントが API リクエストを送信すると、API Gateway はまずリクエストをルーティングするステージを決定します。リクエストがステージと明示的に一致する場合、API Gateway はそのステージにリクエストを送信します。リクエストに完全に一致するステージがない場合、API Gateway はリクエストを $default ステージに送信します。$default ステージがない場合、API は {"message":"Not Found"} を返し、CloudWatch ログを生成しません。

ステージを選択した後、API Gateway はルートを選択します。API Gateway は、次の優先順位を使用して、最も具体的な一致を持つルートを選択します。

1. ルートとメソッドの完全一致。

2. greedy パス変数 ({proxy+})を持つルートとメソッドを一致させます。

3. $default ルート。

リクエストに一致するルートがない場合、API Gateway は {"message":"Not Found"} をクライアントに返します。

たとえば、$default ステージがある API と、次のルート例を考えてみます。

1. GET /pets/dog/1

2. GET /pets/dog/{id}

3. GET /pets/{proxy+}

4. ANY /{proxy+}

5. $default

   次の表は、API Gateway がリクエストをルート例にルーティングする方法をまとめたものです。

リクエスト	選択されたルート	説明
GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1	GET /pets/dog/1	リクエストはこの静的ルートに完全に一致します。
GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2	GET /pets/dog/{id}	リクエストはこのルートに完全に一致します。
GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1	GET /pets/{proxy+}	リクエストがルートに完全に一致していません。GET メソッドと greedy パス変数を持つルートは、このリクエストをキャッチします。
POST https://api-id.execute-api.region.amazonaws.com/test/5	ANY /{proxy+}	ANY メソッドは、ルートに対して定義していないすべてのメソッドに一致します。greedy パス変数を持つルートの優先順位は、$default ルートよりも高くなります。