REST API の API マッピングの使用

API マッピングを使用して、API ステージをカスタムドメイン名に接続します。ドメイン名を作成し、DNS レコードを設定したら、API マッピングを使用して、カスタムドメイン名を使用して API にトラフィックを送信します。

API マッピングは、API、ステージ、およびオプションでマッピングに使用するパスを指定します。たとえば、API の production ステージを https://api.example.com/orders にマッピングできます。

HTTP API と REST API ステージを同じカスタムドメイン名にマッピングできます。

API マッピングを作成する前に、API、ステージ、およびカスタムドメイン名が必要です。カスタムドメイン名の作成と設定の詳細については、「API Gateway でのリージョン別カスタムドメイン名の設定」を参照してください。

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

API マッピングは、例えば orders/v1/items と orders/v2/items のように、複数のレベルで設定できます。

注記

複数のレベルで API マッピングを設定するには、カスタムドメイン名をリージョン別とし、TLS 1.2 セキュリティポリシーを使用する必要があります。

複数のレベルを持つ API マッピングの場合、API Gateway は、一致するパスが最も長い API マッピングにリクエストをルーティングします。API Gateway は、API マッピング用に設定されたパスだけを考慮し、呼び出す API を選択します。API ルートは考慮しません。リクエストに一致するパスがない場合、API Gateway は空のパス (none) にマッピングした API にリクエストを送信します。

複数のレベルの API マッピングを使用するカスタムドメイン名の場合、API Gateway は、一致するプレフィックスが最も長い API マッピングにリクエストをルーティングします。

たとえば、次の API マッピングを持つカスタムドメイン名 https://api.example.com を考えてます。

1. API 1 にマッピングされている (none)。

2. API 2 にマッピングされている orders。

3. API 3 にマッピングされている orders/v1/items。

4. API 4 にマッピングされている orders/v2/items。

5. API 5 にマッピングされている orders/v2/items/categories。

リクエスト	選択した API	説明
https://api.example.com/orders	API 2	リクエストは、この API マッピングと完全に一致します。
https://api.example.com/orders/v1/items	API 3	リクエストは、この API マッピングと完全に一致します。
https://api.example.com/orders/v2/items	API 4	リクエストは、この API マッピングと完全に一致します。
https://api.example.com/orders/v1/items/123	API 3	API Gateway は、最も長い一致パスを持つ API マッピングを選択します。リクエストの最後にある 123 は、選択には影響しません。
https://api.example.com/orders/v2/items/categories/5	API 5	API Gateway は、最も長い一致パスを持つ API マッピングを選択します。
https://api.example.com/customers	API 1	API Gateway は、空のマッピングをキャッチオールとして使用します。
https://api.example.com/ordersandmore	API 2	API Gateway は、一致するプレフィックスが最も長い API マッピングを選択します。単一レベルのマッピングで設定されたカスタムドメイン名の場合 (https://api.example.com/orders とhttps://api.example.com/ のみなど)、API ゲートウェイは、ordersandmore と一致するパスがないため、API 1 を選択します。

制限事項

• API マッピングでは、カスタムドメイン名とマップされた API が同じ AWS アカウントにある必要があります。

• API マッピングに含めることができるのは、文字、数字、および $-_.+!*'()/ の文字だけです。

• API マッピングのパスの最大文字数は 300 文字です。

• ドメイン名ごとに、複数のレベルで 200 個の API マッピングを設定できます。

• TLS 1.2 セキュリティポリシーでは、HTTP API をリージョン別カスタムドメイン名にだけマッピングできます。

• WebSocket API を HTTP API または REST API と同じカスタムドメイン名にマッピングすることはできません。

API マッピングを作成する

API マッピングを作成するには、最初にカスタムドメイン名、API、およびステージを作成する必要があります。カスタムドメイン名の作成方法については、「API Gateway でのリージョン別カスタムドメイン名の設定」を参照してください。

例えば、すべてのリソースを作成する AWS Serverless Application Model テンプレートについては、GitHub で「Sessions With SAM」を参照してください。

AWS Management Console

API マッピングを作成するには

1. API Gateway コンソール (https://console.aws.amazon.com/apigateway) にサインインします。

2. [カスタムドメイン名] を選択します。

3. 既に作成したカスタムドメイン名を選択します。

4. [API マッピング] を選択します。

5. [Configure API mappings (API マッピングの設定)] を選択します。

6. [Add new mapping (新しいマッピングを追加)] を選択します。

7. API、Stage、必要に応じて Path を入力します。

8. [保存] を選択します。

AWS CLI

次の AWS CLI コマンドは、API マッピングを作成します。この例では、API Gateway が指定された API およびステージに api.example.com/v1/orders に対するリクエストを送信します。

注記

複数のレベルで API マッピングを作成するには、apigatewayv2 を使用する必要があります。

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1/orders \
    --api-id a1b2c3d4 \
    --stage test

AWS CloudFormation

次の AWS CloudFormation 例は、API マッピングを作成します。

注記

複数のレベルで API マッピングを作成するには、AWS::ApiGatewayV2 を使用する必要があります。

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'orders/v2/items'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage