REST API のカスタムドメイン名を設定する - Amazon API Gateway

REST API のカスタムドメイン名を設定する

カスタムドメイン名は、API ユーザーに提供できる、よりシンプルで直感的な URL です。

API のデプロイ後、お客様 (およびその顧客) は、以下の形式のデフォルトのベース URL を使用して API を呼び出すことができます。

https://api-id.execute-api.region.amazonaws.com/stage

api-id は API Gateway によって生成され、region (AWS リージョン) は API の作成時に、stage は API のデプロイ時に、ユーザーが指定します。

URL のホスト名の部分 (つまり api-id.execute-api.region.amazonaws.com) は API エンドポイントを参照します。デフォルトの API エンドポイントは再呼び出しが難しく、ユーザーフレンドリではありません。

カスタムドメイン名を使用すると、API のホスト名を設定し、代替パスを API にマッピングするための基本パス (myservice など) を選択できます。たとえば、API のよりわかりやすい ベース URL は以下のようになります。

https://api.example.com/myservice
注記

ただし、リージョン別カスタムドメインは REST API と HTTP API に関連付けることができます。API Gateway バージョン 2 API を使用して、REST API のリージョン別カスタムドメイン名を作成および管理することができます。

カスタムドメイン名はプライベート API ではサポートされていません。

REST API がサポートする最低限の TLS バージョンを選択できます。REST API には、TLS 1.2 または TLS 1.0 を選択できます。

ドメイン名を登録する

API のカスタムドメイン名を設定するには、登録されたインターネットドメイン名が必要です。ドメイン名は RFC 1035 仕様に準拠している必要があり、ラベルあたり最大 63オクテット、合計 255 オクテットを含めることができます。必要に応じて、Amazon Route 53 を使用するか、任意のサードパーティーのドメインレジストラを使用して、インターネットドメインを登録できます。API のカスタムドメイン名は、登録されたインターネットドメインのサブドメイン名またはルートドメイン名 (「Zone Apex」など) にすることができます。

カスタムドメイン名が API Gateway で作成されたら、API エンドポイントにマッピングするために DNS プロバイダーのリソースレコードを作成または更新する必要があります。このマッピングを行わないと、カスタムドメイン名宛ての API リクエストが API Gateway に届きません。

注記

カスタムドメイン名は、すべての AWS アカウントにおいてリージョン内で一意である必要があります。

リージョン間または AWS アカウント間でエッジ最適化カスタムドメイン名を移動するには、既存の CloudFront ディストリビューションを削除して新規に作成する必要があります。新しいカスタムドメイン名が使用できるようになるまで、約 30 分かかる場合があります。詳細については、「CloudFront ディストリビューションの更新」を参照してください。

エッジ最適化カスタムドメイン名

エッジ最適化 API をデプロイすると、API Gateway は Amazon CloudFront ディストリビューションと DNS レコードを設定し、API ドメイン名を CloudFront ディストリビューションドメイン名にマッピングします。API のリクエストは、マッピングされた CloudFront ディストリビューションを介して API Gateway にルーティングされます。

エッジ最適化 API のカスタムドメイン名を作成すると、API Gateway によって CloudFront ディストリビューションがセットアップされます。ただし、カスタムドメイン名を CloudFront ディストリビューションドメイン名にマッピングするには、DNS レコードを設定する必要があります。このマッピングは、カスタムドメイン名宛ての API リクエストに使用され、そのリクエストは、マッピング先の CloudFront ディストリビューションを介して API Gateway にルーティングされます。カスタムドメイン名の証明書を提供する必要もあります。

注記

API Gateway によって作成された CloudFront ディストリビューションは、API Gateway と提携しているリージョン固有のアカウントによって所有されています。CloudWatch Logs でこのような CloudFront ディストリビューションを作成および更新するためのオペレーションをトレースするときは、この API Gateway アカウント ID を使用する必要があります。詳細については、「CloudTrail におけるカスタムドメイン名の作成のログ記録」を参照してください。

エッジ最適化のカスタムドメイン名を設定したり、その証明書を更新したりするには、CloudFront ディストリビューションを更新するためのアクセス許可が必要です。

アクセス権限を付与するには、ユーザー、グループ、またはロールにアクセス許可を追加します。

CloudFront ディストリビューションを更新するには、以下のアクセス許可が必要です。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

API Gateway は、CloudFront ディストリビューションで Server Name Indication (SNI) を利用することで、エッジ最適化のカスタムドメイン名をサポートしています。証明書の必須の形式や証明書の最大キー長など、CloudFront ディストリビューションでのカスタムドメイン名の使用の詳細については、Amazon CloudFront デベロッパーガイドの「代替ドメイン名と HTTPS の使用」を参照してください。

API のホスト名としてカスタムドメイン名を設定する場合、API 所有者はカスタムドメイン名の SSL/TLS 証明書を提供する必要があります。

エッジ最適化のカスタムドメイン名の証明書を提供するには、AWS Certificate Manager (ACM) にリクエストして新しい証明書を ACM で生成するか、us-east-1 リージョン (米国東部 (バージニア北部)) でサードパーティー認証機関から発行された証明書を ACM にインポートできます。

リージョン別カスタムドメイン名

特定のリージョンの API のカスタムドメイン名を作成すると、API Gateway は API のリージョン別ドメイン名を作成します。カスタムドメイン名をリージョン別ドメイン名にマッピングするように、DNS レコードを設定する必要があります。カスタムドメイン名の証明書を提供する必要もあります。

ワイルドカードカスタムドメイン名

ワイルドカードカスタムドメイン名を使用すると、デフォルトのクォータを超えずにほぼ無数のドメイン名をサポートできます。たとえば、各お客様に個別のドメイン名を付けることができます customername.api.example.com

ワイルドカードカスタムドメイン名を制作するためには、ルートドメインの可能なすべてのサブドメインを表すカスタムドメインの最初のサブドメインとして、ワイルドカード (*) を指定します。

たとえば、ワイルドカードカスタムドメイン名として *.example.com を使用すると、a.example.comb.example.comc.example.com などのサブドメインが生成され、これらはすべて同じドメインにルーティングされます。

ワイルドカードカスタムドメイン名は、API Gateway の標準のカスタムドメイン名とは異なる設定をサポートします。たとえば、1 つの AWS アカウントで、*.example.coma.example.com を異なる動作に設定できます。

コンテキスト変数 $context.domainName$context.domainPrefix コンテキスト変数を使用して、クライアントが API を呼び出すために使用したドメイン名を判断できます。コンテキスト変数の詳細については、「API Gateway マッピングテンプレートとアクセスのログ記録の変数リファレンス」を参照してください。

ワイルドカードカスタムドメイン名を作成するには、DNS または E メール検証方法を使用して検証された証明書を ACM から発行してもらう必要があります。

注記

別の AWS アカウントで作成済みのカスタムドメイン名と競合するようなワイルドカードカスタムドメイン名を作成することはできません。たとえば、アカウント A で a.example.com が作成済みである場合、アカウント B はワイルドカードカスタムドメイン名として *.example.com を作成できません。

アカウント A とアカウント B の所有者が同じである場合は、AWS サポートセンターに連絡して例外をリクエストできます。

カスタムドメイン名の証明書

重要

カスタムドメイン名の証明書を指定します。アプリケーションで証明書ピンニング (SSL ピンニングとも呼ばれる) を使用して ACM 証明書を固定すると、AWS が証明書を更新した後にアプリケーションがドメインに接続できないことがあります。詳細については、「AWS Certificate Manager ユーザーガイド」の「証明書のピンニングの問題」を参照してください。

ACM がサポートされているリージョンでカスタムドメイン名の証明書を提供するには、ACM に証明書をリクエストする必要があります。ACM がサポートされていないリージョンで、リージョン別カスタムドメイン名の証明書を提供するには、そのリージョン内の API Gateway に証明書をインポートする必要があります。

SSL/TLS 証明書をインポートするには、カスタムドメイン名の PEM 形式の SSL/TLS 認証本文、そのプライベートキー、およびカスタムドメイン名の証明書チェーンを提供する必要があります。ACM に保存された各証明書は ARN によって識別されます。AWS で管理された証明書をドメイン名で使用するには、その ARN を単に参照します。

ACM を使用すると、API のカスタムドメイン名を簡単に設定して使用できます。特定のドメイン名の証明書を作成 (または証明書をインポート) し、ACM が提供する証明書の ARN を使用して API Gateway でドメイン名を設定します。次に、カスタムドメイン名のベースパスを、デプロイされた API のステージにマッピングします。ACM 発行の証明書により、プライベートキーなど証明書の機密の詳細が漏れる心配はありません。