API マッピングを使用して、API ステージを REST API のカスタムドメイン名に接続します。 - Amazon API Gateway
カスタムドメイン名への受信リクエストAPI リクエストのマッピング制限事項API マッピングを作成する

API マッピングを使用して、API ステージを REST API のカスタムドメイン名に接続します。

API マッピングを使用して、API ステージをカスタムドメイン名に接続します。これにより、API へのトラフィックがカスタムドメイン名を経由して送信されます。

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

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

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

カスタムドメイン名への受信リクエスト

カスタムドメイン名を API のステージにマッピングすると、API Gateway は受信ベースパスを削除します。これにより、マッピングされたベースパスが API への呼び出しから削除されます。例えば、ベースパスマッピングが https://api.example.com/orders/shop/5 から test ステージで、次のリクエスト https://api.example.com/orders/shop/5/hats を使用した場合、API Gateway は orders/shop/5/hats リソースではなく API の test ステージの /hats リソースを呼び出します。

API リクエストのマッピング

以下に、API Gateway が API マッピングを評価する方法について説明します。

API マッピングは、orders から API の beta ステージへの API マッピングや、shipping から API の alpha ステージへの API マッピングなど、単一レベルのマッピングを使用して作成できます。TLS 1.2 セキュリティポリシーを使用するリージョン別カスタムドメイン名の場合、API Gateway はマルチレベル API マッピングをサポートします。API マッピングは、orders/v1/items から API の alpha ステージ、および orders/v2/items からの API の beta ステージを作成できます。複数のレベルでマッピングを作成すると、API Gateway は一致するパスが最も長い API マッピングにリクエストを送信します。

空のパス (none) への API マッピングを作成できます。リクエストに一致するパスがない場合、API Gateway は空のパス (none) にリクエストを送信します。

この例では、カスタムドメイン名 https://api.example.com には次の API マッピングがあります。

API マッピング 選択した API

(none)

API 1

orders

API 2

orders/v1/items

API 3

orders/v2/items

API 4

orders/v1/items/categories

API 5

次の表は、API Gateway が以前の API マッピングをリクエストの例に適用する方法を示しています。

リクエスト 選択した 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 マッピングを設定できます。この制限には、/prod などの単一レベルの API マッピングは含まれません。

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

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

  • API マッピングを作成した後、DNS プロバイダーのリソースレコードを作成または更新して、API エンドポイントにマッピングする必要があります。

  • 複数レベルの API マッピングを作成する場合、API Gateway はすべてのヘッダー名を小文字に変換します。

API マッピングを作成する

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

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

AWS Management Console

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

  2. メインのナビゲーションペインから [Custom Domain Names (カスタムドメイン名)] を選択します。

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

  4. [ルーティングの詳細] タブで、[API マッピングを設定] を選択します。

  5. マッピングの [API]、[ステージ]、[パス] を入力します。

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

AWS CLI

次の create-api-mapping コマンドは、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