メニュー
Amazon API Gateway
開発者ガイド

API ホスト名としてのカスタムドメイン名の設定

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

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

この場合、URL のホスト名 (つまり、api-id.execute-api.region.amazonaws.com) は呼び出しにくく、ユーザーにとって使い勝手が悪くなっています。API ユーザー向けによりシンプルで直観的な URL を提供するには、API Gateway を使用して API のホスト名としてカスタムドメイン名 (例:api.haymuto.com) を設定し、基本パス (例:myservice) を選択して、以下の形式の API の代替 URL を提示できます。

Copy
https://api.haymuto.com/myservice

ベースパスは空の文字列とすることができます。この場合、API のルート URL はカスタムドメイン (例:https://api.haymuto.com) と同じです。また、カスタムドメイン名は API 1つのみサポートします。

作成する API ごとに、API Gateway は API 用の Amazon CloudFront ディストリビューションを設定します。デフォルトの API URL を持つリクエストは、対応する CloudFront ディストリビューションを介してルーティングされます。同様に、各カスタムドメイン名に、API Gateway は CloudFront ディストリビューションをセットアップします。カスタムドメイン名を持つ API リクエストは、カスタムドメイン名の CloudFront ディストリビューションを介してルーティングされます。

注記

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

ヒント

カスタムドメイン名を設定したり、その証明書を更新したりするには、CloudFront ディストリビューションを更新するためのアクセス許可が必要です。そのためには、次の IAM ポリシーステートメントをアカウントの IAM ユーザー、グループ、またはロールにアタッチします。

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

API Gateway は、CloudFront ディストリビューションで Server Name Indication (SNI) を利用することによりカスタムドメイン名をサポートします。証明書の必須の形式や証明書の最大キー長など、CloudFront ディストリビューションでのカスタムドメイン名の使用の詳細については、Amazon CloudFront 開発者ガイド の「Using Alternate Domain Names and HTTPS」を参照してください。

API のホスト名としてカスタムドメイン名を設定するには、API 所有者として、カスタムドメイン名の SSL/TLS 証明書を提供する必要があります。この証明書を提供するには、AWS Certificate Manager (ACM) をリクエストして新しい証明書を ACM に生成するか、サードパーティの認証機関によって発行されたカスタム証明書を ACM にインポートします。SSL/TLS 証明書をインポートするには、カスタムドメイン名の PEM 形式の SSL/TLS 認証本文、そのプライベートキー、およびカスタムドメイン名の証明書チェーンを提供する必要があります。ACM に保存された各証明書は ARN によって識別されます。ドメイン名に AWS に管理された証明書を使用するには、ARN を参照します。

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

注記

API Gateway は CloudFront によってサポートされない自己署名の SSL/TLS 証明書についてはサポートしていません。

API のカスタムドメイン名を設定するためには、登録されたインターネットのドメイン名が必要です。必要に応じ、Amazon Route 53 またはお好みのサードパーティーのドメインレジストラを使用して、インターネットのドメインを登録できます。API のカスタムドメイン名は、登録したインターネットドメインのサブドメイン名か、またはルートドメイン名 (例:zone apex) を使用できます。

API Gateway でカスタムドメイン名を作成したら、ドメイン名サービス (DNS) プロバイダーのリソースレコードを更新して、カスタムドメイン名をその CloudFront ディストリビューションドメイン名にマッピングする必要があります。マッピングにより、カスタムドメイン名に対する API リクエストが正しい CloudFront ディストリビューションを経由してルーティングされていることを確認します。

注記

API に関連付けるカスタムドメイン名は、リージョンおよびアカウントに固有です。リージョン間または AWS アカウント間のカスタムドメイン名の移動には、既存の CloudFront ディストリビューションの削除および新規作成が含まれます。新しいカスタムドメイン名が使用できるようになるまで、およそ 30 分かかる場合があります。詳細については、「CloudFront ディストリビューションの更新」を参照してください。

このセクションでは、ACM を使用してカスタムドメイン名の SSL/TLS 証明書を作成する方法、API のカスタムドメイン名を設定する方法、カスタムドメイン名で特定の API をベースパスと関連付ける方法、カスタムドメイン名のために ACM へインポートしていた期限切れとなる証明書を更新 (別名で更新) する方法について説明します。

AWS Certificate Manager で証明書の準備をする

API のカスタムドメイン名を設定する前に、AWS Certificate Manager で SSL/TLS 証明書を準備する必要があります。次のステップでそのやり方を説明します。詳細については、AWS Certificate Manager ユーザーガイド を参照してください。

注記

API Gateway で ACM 証明書を使用するには、米国東部(バージニア北部) (us-east-1) リージョンで証明書をリクエストまたはインポートする必要があります。

ACM 発行の、または、インポートされた指定のドメイン名の証明書を取得するには

  1. インターネットのドメインを登録します。例:myDomain.comAmazon Route 53、または認定されているサードパーティーのドメインレジストラを使用できます。そのようなレジストラの一覧については、ICANN のウェブサイトの認定レジストラディレクトリを参照してください。

  2. ドメイン名の SSL/TLS 証明書を ACM で作成またはインポートするには、次のいずれかを行います。

    ACM により提供されたドメイン名の証明書をリクエストするには

    1. AWS Certificate Manager コンソールにサインインします。

    2. [Request a certificate] を選択します。

    3. [Domain name] に API のカスタムドメイン名を入力します (例:api.example.com)。

    4. 必要に応じて、[Add another name to this certificate] を選択します。

    5. [Review and request] を選択します。

    6. [Confirm and request] を選択します。

    7. リクエストが有効であるためには、ACM が証明書を発行する前に、インターネットドメインの登録された所有者がリクエストに同意する必要があります。

    ACM にドメイン名の証明書をインポートするには

    1. 証明機関からカスタムドメイン名の PEM エンコード SSL/TLS 証明書を取得します。このような CA のリストの一部については、「Mozilla Included CA List」を参照してください。

      1. 証明書のプライベートキーを生成し、OpenSSL ウェブサイトの OpenSSL ツールキットを使用して出力をファイルに保存します。

        Copy
        openssl genrsa -out private-key-file 2048

        注記

        Amazon API Gateway は Amazon CloudFront を利用して、カスタムドメイン名の証明書をサポートします。そのため、カスタムドメイン名の SSL/TLS 証明書の要件と制約は CloudFront によって指定されます。たとえば、パブリックキーの最大サイズは 2048 で、プライベートキーのサイズは 1024、2048、または 4096 とすることができます。パブリックキーのサイズは、使用している認証機関によって決まります。デフォルトの長さと異なるサイズのキーを返すよう認証機関に依頼します。詳細については、「HTTPS 接続を使用したオブジェクトへのアクセス」および「署名付き URL と署名付き Cookie (信頼された署名者) の作成が可能な AWS アカウントの指定」を参照してください。

      2. OpenSSL を使用して、以前に作成されたプライベートキーで証明書署名リクエスト (CSR) を生成します。

        Copy
        openssl req -new -sha256 -key private-key-file -out CSR-file
      3. CSR を認証機関に送信し、結果として生じる証明書を保存します。

      4. 認証機関から証明書チェーンをダウンロードします。

      注記

      別の方法でプライベートキーを取得し、キーが暗号化されている場合は、次のコマンドを使用してキーを復号してから、カスタムドメイン名を設定するためにキーを API Gateway に送信できます。

      Copy
      openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
    2. 証明書を AWS Certificate Manager へアップロードする

      1. AWS Certificate Manager コンソールにサインインします。

      2. [Import a certificate] を選択します。

      3. [Certificate body] に、証明機関からの PEM 形式のサーバー証明書の本文を入力するか貼り付けます。このような証明書の省略された例を次に示します。

        Copy
        -----BEGIN CERTIFICATE----- EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB ... az8Cg1aicxLBQ7EaWIhhgEXAMPLE -----END CERTIFICATE-----
      4. [Certificate private key] に、PEM 形式の証明書のプライベートキーを入力するか貼り付けます。このようなキーの省略された例を次に示します。

        Copy
        -----BEGIN RSA PRIVATE KEY----- EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO ... 1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE -----END RSA PRIVATE KEY-----
      5. [Certificate chain] に、PEM 形式の中間証明書を (必要に応じてルート証明書も) 空白行なしに連続して入力するか貼り付けます。ルート証明書を含める場合は、証明書チェーンの先頭は中間証明書で、末尾がルート証明書である必要があります。証明機関によって提供された中間証明書を使用します。信頼パスのチェーン内に存在しない中間証明書は含めないでください。次の例で省略された例を示します。

        Copy
        -----BEGIN CERTIFICATE----- EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB ... 8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE -----END CERTIFICATE-----

        別の例を示します。

        Copy
        -----BEGIN CERTIFICATE----- Intermediate certificate 2 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Intermediate certificate 1 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- Optional: Root certificate -----END CERTIFICATE-----
      6. [Review and import] を選択します。

  3. 証明書が正常に作成またはインポートされた後、証明書の ARN をメモします。次回カスタムドメイン名を設定する際に必要になります。

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

次の手順では、API Gateway コンソールを使用して API のカスタムドメイン名をセットアップする方法を説明します。

API Gateway コンソールを使用してカスタムドメイン名を設定する

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

  2. メインのナビゲーションペインから [Custom Domain Names] を選択します。

  3. 次に、[Create Custom Domain Name] を選択します。

    1. [New Custom Domain Name] で、[Domain Name] にドメイン名 (api.example.com など) を入力します。

      注記

      カスタムドメイン名にはワイルドカード文字 (*) を使用しないでください。ワイルドカード文字は、API Gateway コンソール (または AWS CLI) では受け入れられ、CloudFront ディストリビューションにマッピングされますが、API Gateway ではサポートされていません。ただし、ワイルドカード証明書は使用できます。

    2. [ACM 証明書] リストから新しい証明書を選択します。

    3. [マッピング追加] を選び、[ベースパスマッピング] でベースパス ([パス]) を設定し、特定のステージ (ドロップダウンリストの [送信先] から選択) で API がデプロイするようにします。カスタムドメイン名が作成されたらマッピングするベースパスも設定できます。詳細については、「ホスト名としてカスタムドメイン名で API のベースパスマッピングを設定する」を参照してください。

    4. [Save] を選択します。

  4. カスタムドメイン名を作成したら、コンソールは関連する CloudFront ディストリビューションドメイン名を証明書 ARN と一緒に distribution-id.cloudfront.net の形式で表示します。出力に表示される CloudFront ディストリビューションドメイン名をメモしておきます。次のステップで、DNS でカスタムドメインの CNAME 値または A レコードのエイリアスターゲットを設定するために、これが必要になります。

    注記

    新しく作成したカスタムドメイン名は使用できるまでに約 40 分かかります。カスタムドメイン名が初期化されている間に、カスタムドメイン名を関連する CloudFront ディストリビューションドメイン名にマッピングするため、また、カスタムドメイン名のベースパスマッピングを設定するために、DNS レコードのエイリアスを設定できます。

  5. このステップでは、Amazon Route 53 を DNS プロバイダーの例として使用して、カスタムドメイン名を関連する CloudFront ディストリビューション名にマッピングするために、インターネットのドメインの A レコードのエイリアスを設定する方法を示します。この手順は、他の DNS プロバイダーに適用することができます。

    1. Amazon Route 53 コンソールにサインインします。

    2. カスタムドメインの A-IPv4 address レコードセットを作成します (例: api.haymuto.com)。A レコードは IP4 アドレスにカスタムドメイン名をマッピングします。

    3. [Alias] で [Yes] を選択し、[d3boq9ikothtgw.cloudfront.netAlias Target] に CloudFront ドメイン名 (例: ) を入力して、[Create] を選択します。ここで A レコードのエイリアスは指定された CloudFront ドメイン名にカスタムドメイン名をマッピングします。このドメイン自体は IP4 アドレスにマッピングされます。

       API Gateway で API のカスタムドメイン名の DNS レコードのエイリアスを設定する

    ヒント

    [Alias Hosted Zone ID] は、指定した [Alias Target] のホストゾーンを識別します。[Alias Target] に有効なドメイン名を入力すると、Amazon Route 53 コンソールによって自動的に値が入力されます。AWS CLI を使用する場合など、Amazon Route 53 コンソールを使用せずに A レコードのエイリアスを作成するには、必要なホストゾーン ID を指定する必要があります。すべての CloudFront ディストリビューションドメイン名において、ホストゾーン ID の値は常に Z2FDTNDATAQYW2 です (「AWS のリージョンとエンドポイント」の CloudFront の項で説明しています)。

    ほとんどの DNS プロバイダーでは、カスタムドメイン名は、CNAME リソースレコードセットとしてホストゾーンに追加されます。CNAME レコードの名前では、[Domain Name] に先ほど入力したカスタムドメイン名 (api.haymuto.com など) を指定します。CNAME レコードの値では、CloudFront ディストリビューションのドメイン名を指定します。ただし、カスタムドメインが Zone Apex である (つまり、api.haymuto.com ではなく example.com である) 場合、CNAME レコードは動作しません。一般的に、Zone Apex は組織のルートドメインとしても知られています。zone apex には、A レコードのエイリアスを使用する必要があります (DNS プロバイダーによってサポートされている場合)。

    Amazon Route 53 では、上記に示すように、カスタムドメイン名の A レコードのエイリアスを作成し、エイリアス先として CloudFront ディストリビューションドメイン名を指定することができます。その結果、カスタムドメイン名が Zone Apex であっても、Amazon Route 53 はカスタムドメイン名をルーティングすることができます。詳細については、Amazon Route 53 開発者ガイド の「エイリアスリソースレコードセットと非エイリアスリソースレコードセットの選択」を参照してください。

    A レコードエイリアスを使用するときも、ドメイン名のマッピングは Amazon Route 53 内でのみ起こるため、基盤となる CloudFront ディストリビューションのドメイン名で公開する必要はなくなります。これらの理由により、可能な限りは Amazon Route 53 A レコードエイリアスの使用をお勧めします。

API Gateway コンソールの使用に加えて、API にカスタムドメイン名を設定するために、API Gateway REST API、AWS CLI、または AWS SDK の 1 つを使用できます。例として、次の手順では REST API 呼び出しを使用したステップを簡単に示しています。

API Gateway REST API を使用してカスタムドメイン名を設定するには

  1. domainname:create を呼び出し、カスタムドメイン名と AWS Certificate Manager に保存してある 証明書の ARN を指定します。

    API 呼び出しが成功すると、証明書 ARN、および関連する CloudFront ディストリビューション名をペイロードに含む 201 Created レスポンスを返します。

  2. 出力に表示される CloudFront ディストリビューションドメイン名をメモしておきます。次のステップで、DNS でカスタムドメインの CNAME 値または A レコードのエイリアスターゲットを設定するために、これが必要になります。

  3. A レコードエイリアスを設定して CloudFront ディストリビューション名にカスタムドメイン名をマッピングするために、前の手順のステップ 6 を実行します。

この REST API 呼び出しのコード例については、domainname:create を参照してください。

CloudTrail におけるカスタムドメイン名の作成のロギング

アカウントで作成された API Gateway 呼び出しのログ作成のために CloudTrail が有効な場合に、API のカスタムドメイン名が作成または更新されたとき、API Gateway は関連する CloudFront ディストリビューションの更新のログを作成します。これらの CloudFront ディストリビューションは API Gateway が所有しているので、これらのレポートされた CloudFront ディストリビューションは、API 所有者のアカウント ID ではなく、以下のリージョン固有の API Gateway アカウント ID の1つにより識別されます。

カスタムドメイン名と関連付けられた CloudFront ディストリビューションのリージョン固有の API Gateway アカウント ID

サービス対象 アカウント ID
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
eu-west-1 631144002099
eu-west-2 544388816663
eu-central-1 474240146802
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-southeast-1 195145609632
ap-southeast-2 798376113853

ホスト名としてカスタムドメイン名で API のベースパスマッピングを設定する

複数の API のホスト名として、単一のカスタムドメイン名を使用できます。カスタムドメイン名でベースパスマッピングを設定することにより、これを実現できます。ベースパスマッピングにより、カスタムドメインの API は、カスタムドメイン名と関連するベースパスの組み合わせによりアクセス可能になります。

たとえば、PetStore という名前の API と PetShop という名前の別の API を作成し、カスタムドメイン名 api.haymuto.com を API Gateway で設定した場合、PetStore API の URL を、https://api.haymuto.com または https://api.haymuto.com/myPetStore として設定できます。PetStore API は、カスタムドメイン名 api.haymuto.com で、空の文字列または myStore というベースパスと関連付けられます。同様に、PetShop API にベースパス yourPetStore を割り当てることができます。URL https://api.haymuto.com/yourPetStore は、PetShop API のルート URL となります。

API にベースパスを設定する前に、「API Gateway API のカスタムドメイン名を設定する」のステップを完了してください。

API Gateway コンソールを使用して API マッピングのベースパスを設定するには

  1. アカウントの利用可能な [Custom Domain Names] の一覧からカスタムドメイン名を選択します。

  2. [Show Base Path Mappings] または [Edit] を選択します。

  3. [Add mapping] を選択します。

  4. (オプション) [パス] にベースパス名を入力し、[送信先] から API を選択した後、ステージを選択します。

    注記

    [Destination] の一覧はアカウントの下でデプロイされた API を示します。

  5. [Save] を選択して API のベースパスマッピングを終了します。

注記

マッピングをその作成後に削除するには、削除するマッピングの横にあるゴミ箱のアイコンを選択します。

加えて、ホスト名としてカスタムドメイン名で API のベースパスマッピングを設定するために、API Gateway REST API、AWS CLI、または AWS SDK の 1 つを使用できます。例として、次の手順では REST API 呼び出しを使用したステップを簡単に示しています。

API Gateway REST API を使用して API のベースパスマッピングを設定するには

  • 特定のカスタムドメイン名で basepathmapping:create を呼び出し、リクエストペイロードの basePathrestApiId、およびデプロイ stage のプロパティを指定します。

    API 呼び出しが成功すると、201 Created レスポンスを返します。

REST API 呼び出しのコード例については、basepathmapping:create を参照してください。

ACM にインポートされた証明書を更新

ACM は使用する証明書の更新を自動的に処理します。カスタムドメイン名に ACM 使用の証明書を更新する必要はありません。CloudFront は自動的に処理されます。

ただし、証明書を ACM にインポートし、カスタムドメイン名に使用すると、期限切れ前に証明書を更新する必要があります。これにはドメイン名に関する新しいサードパーティーの証明書のインポートも含まれ、既存の証明書は新規更新されます。期限切れの証明書を新しくインポートするときはそのプロセスを繰り返す必要があります。また、ACM にドメイン名に関する新しい証明書を発行するようリクエストもでき、既存のものを ACM 発行の新しい証明書に更新します。その後で、ACM と CloudFront により証明書の更新を自動的に処理するようにできます。新しい ACM 証明書を作成またはインポートするには、指定のドメイン名で「新しい ACM 証明書をリクエストまたはインポートする」のステップに従ってください。

ドメイン名の証明書を更新する場合は、API Gateway コンソール、API Gateway REST API、AWS CLI、AWS SDK のいずれかを使用できます。

API Gateway コンソールを使って ACM にインポートした、期限切れとなる証明書を更新するには

  1. ACM に証明書をリクエストするかインポートします。

  2. API Gateway コンソールに戻ります。

  3. API Gateway コンソールのナビゲーションペインから [Custom Domain Names] を選択します。

  4. 希望するカスタムドメイン名を、ペインの [カスタムドメイン名] から選択してください。

  5. [Edit] を選択します。

  6. ドロップダウンリストの [ACM 証明書] から希望する証明書を選択します。

  7. [保存] を選択し、カスタムドメイン名の証明書の更新を開始します。

    注記

    プロセスが終了するには約40分かかります。更新完了後、[ACM 証明書] の隣にある対面矢印アイコンを選択すると、オリジナルの証明書に戻せます。

カスタムドメイン名にインポートした証明書をプログラムを使って更新する方法として、API Gateway REST API を使用するステップを簡単に説明します。

API Gateway REST APIを使用してインポートした証明書を更新

  • domainname:update アクションを呼び出し、指定したドメイン名の新しい ACM 証明書の ARN を指定します。

カスタムドメイン名で API を呼び出す

カスタムドメイン名で API を呼び出すことは、正しい URL を使用する場合、デフォルトのドメイン名で API を呼び出すことと同じです。

次の例では、指定されたリージョン (us-east-1) で指定されたカスタムドメイン名 (apis.example.com) の 2 つの API (udxjef および qf3duz) のデフォルトの URL と対応するカスタム URL を比較し、違いを示します。

デフォルトおよびカスタムドメイン名を持つ API のルート URL

API ID ステージ デフォルト URL 基本パス カスタム URL
udxjef pro https://udxjef.execute-api.us-east-1.amazonaws.com/pro /petstore https://apis.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://apis.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://apis.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://apis.example.com/bookstand

API Gateway では、Server Name Indication (SNI) を使用した、カスタムドメイン名での API の呼び出しがサポートされています。SNI をサポートするブラウザまたはクライアントライブラリを使用して、カスタムドメイン名の API を呼び出すことができます。

API Gateway は CloudFront ディストリビューションで SNI を強制します。CloudFront でのカスタムドメイン名の使用の詳細については、「Amazon CloudFront Custom SSL」を参照してください。