--- title: "API Gatewayのカスタムドメイン設定：ACM証明書・Route 53・ベースパスマッピングをCLIで構築" url: "https://www.issoh.co.jp/tech/details/18483/" published: 2026-10-18 updated: 2026-10-18 categories: ["AWS"] publisher: "株式会社一創" --- # API Gatewayのカスタムドメイン設定：ACM証明書・Route 53・ベースパスマッピングをCLIで構築 Amazon API Gatewayのカスタムドメインは、`a1b2c3d4e5.execute-api.ap-northeast-1.amazonaws.com`のような自動生成のURLを、`api.example.com`のような自社のドメインで呼べるようにする機能です。設定はACMの証明書、API Gateway側のドメイン名、ステージへのマッピング、DNSレコードの4つで成り立ちます。本記事では東京リージョンのREST APIを例に、証明書の発行からRoute 53のAエイリアスまでをAWS CLIで組む手順、RegionalとEdge-optimizedの違い、2025年6月に追加されたルーティングルール、403や証明書エラーの切り分けを順にまとめました。API Gatewayの役割そのものは[APIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説](https://www.issoh.co.jp/tech/details/13210/)で扱っています。仕様と上限値は2026年10月時点の公式ドキュメントで確認した値です。 ## まとめ：東京リージョンの証明書とRegionalのドメイン名で組むのが基本 業務システムのAPIにカスタムドメインを付けるなら、エンドポイント種別はRegionalを選び、証明書はAPIと同じ東京リージョンのACMで発行します。API Gatewayでドメイン名を作ると`d-`で始まるターゲット名が払い出されるので、Route 53でそこへ向けたAエイリアスを作れば開通です。ステージとの対応付けは、単純な構成ならAPIマッピング、ヘッダーで版を切り替えたいならルーティングルールを使います。 つながらないときは、DNSレコード、証明書のリージョン、マッピングの順に疑ってください。公開後は既定の`execute-api`エンドポイントを無効にすると、WAFや監視をカスタムドメイン側に寄せられます。Edge-optimizedを選ぶ理由は、東京中心の利用者を想定する限りほとんどありません。 ## カスタムドメインの構成要素｜証明書・ドメイン名・マッピング・DNSの役割 4つの部品は作る順番が決まっています。証明書が無いとドメイン名を作れず、ドメイン名が無いとマッピングもDNSの向き先も決まりません。 ### 既定のexecute-apiのURLとカスタムドメインのURLの対応とベースパス [カスタムドメインの概要](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html)によると、既定のURLは`https://{api-id}.execute-api.{region}.amazonaws.com/{stage}`の形式です。カスタムドメインでは、このホスト名とステージの部分を、ドメイン名とベースパスの組に置き換えます。 | 呼び出すAPIとステージ | ベースパス | カスタムドメインのURL | | ---------------------- | ------- | ------------------ | | 注文API（a1b2c3d4e5）のprod | （なし） | api.example.com | | 注文API（a1b2c3d4e5）のprod | v1 | api.example.com/v1 | | 請求API（f6g7h8i9j0）のprod | billing | （同ドメイン）/billing | [APIマッピングの仕様](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html)では、API Gatewayは受け取ったパスからベースパスを取り除いてAPIを呼びます。`api.example.com/v1/orders`へのリクエストは、ステージ側では`/orders`リソースとして処理されます。API側のリソース名にv1を含める必要はありません。 ### RegionalとEdge-optimizedで変わる証明書のリージョンとDNSの向き先 カスタムドメインのエンドポイント種別は、APIの種別とは別に選びます。どちらを選ぶかで、証明書を置くリージョンとDNSの向き先が変わります。 | 項目 | Regional | Edge-optimized | | -------------- | ------------------- | ------------------- | | ACM証明書のリージョン | APIと同じ（東京なら東京） | us-east-1のみ | | DNSの向き先 | d-xxxx.execute-api… | xxxx.cloudfront.net | | エイリアスのホストゾーンID | Z1YSHQZHG15GKL（東京） | Z2FDTNDATAQYW2（共通） | | 使えるようになるまで | 待ち時間の記載なし | 約40分 | | マルチレベルのマッピング | 可（TLS 1.2） | 不可 | | HTTP APIの割り当て | 可 | 不可 | ホストゾーンIDは[API Gatewayのエンドポイント一覧](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)に載っている値です。[Edge-optimizedの設定手順](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-edge-optimized-custom-domain-name.html)では、証明書をバージニア北部に置くこと、準備に約40分かかること、CloudFrontを更新する権限が要ることが明記されています。[HTTP APIのカスタムドメイン](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-custom-domain-names.html)はRegionalのドメイン名を使い、TLS 1.2だけに対応します。 ## 東京リージョンのREST APIに独自ドメインを付けるCLI手順と確認方法 ここからは`api.example.com`を、東京リージョンのREST APIの`prod`ステージに`v1`のパスで割り当てる例です。Route 53にexample.comのホストゾーンがある前提で進めます。 ### ACMで東京リージョンの証明書をDNS検証で発行し検証レコードを登録 [証明書の準備](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-specify-certificate-for-custom-domain-name.html)では、Regionalのドメイン名にはAPIと同じリージョンの証明書を使い、その証明書がドメイン名をカバーしている必要があります。[request-certificateのリファレンス](https://docs.aws.amazon.com/cli/latest/reference/acm/request-certificate.html)に沿って、リージョンを明示して発行を依頼します。 ``` # 1) 東京リージョンで証明書を依頼する（鍵は既定のRSA_2048） aws acm request-certificate \ --domain-name api.example.com \ --validation-method DNS \ --region ap-northeast-1 # 2) DNS検証用のCNAMEレコード（Name・Type・Value）を確認する aws acm describe-certificate \ --certificate-arn arn:aws:acm:ap-northeast-1:123456789012:certificate/1111aaaa-22bb-33cc-44dd-555555eeeeee \ --region ap-northeast-1 \ --query "Certificate.DomainValidationOptions[0].ResourceRecord" ``` Route 53でDNSを管理しているなら、ACMコンソールの「Route 53でレコードを作成」から検証用のCNAMEを登録できます。状態が`ISSUED`になるまで次へ進めません。証明書の自動更新や有効期間の考え方は[AWS Certificate Managerとは？有効期間198日化とACME対応・料金と採用判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15898/)にまとめました。 ### create-domain-nameでRegionalドメイン名作成とターゲット名の記録 証明書が発行されたら、API Gateway側にドメイン名を作ります。[create-domain-nameのリファレンス](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html)では、`--endpoint-configuration`を省くと種別はEDGEになります。Regionalにするには明示が必要です。 ``` aws apigateway create-domain-name \ --domain-name api.example.com \ --regional-certificate-arn arn:aws:acm:ap-northeast-1:123456789012:certificate/1111aaaa-22bb-33cc-44dd-555555eeeeee \ --endpoint-configuration types=REGIONAL \ --security-policy TLS_1_2 \ --region ap-northeast-1 \ --query "[regionalDomainName,regionalHostedZoneId]" ``` 出力の1つ目が`d-`で始まるターゲット名、2つ目がAPI Gateway側のホストゾーンIDです。どちらも手順4で使います。[Regionalの設定手順](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-regional-api-custom-domain-create.html)によれば、このとき証明書を取り付けるためのサービスリンクロール`AWSServiceRoleForAPIGateway`がアカウントに自動で作られます。権限を絞った運用者ロールで実行して失敗した場合は、このロールの作成権限を疑ってください。 ### create-api-mappingでprodステージをv1のパスに割り当てる 次に、ドメイン名とAPIのステージを結び付けます。単一階層のパスなら`apigateway`の`create-base-path-mapping`でも作れますが、`v1/orders`のような複数階層を扱えるのは`apigatewayv2`だけなので、こちらにそろえておくと後で困りません。 ``` aws apigatewayv2 create-api-mapping \ --domain-name api.example.com \ --api-mapping-key v1 \ --api-id a1b2c3d4e5 \ --stage prod \ --region ap-northeast-1 ``` `--api-mapping-key`を省くと空のパスへの割り当てになり、`api.example.com`の直下でAPIを呼べます。1つのAPIしか載せない予定でも、`v1`を付けておけば後から`v2`を並べて段階的に移行できます。 ### Route 53にAエイリアスを作りcurlとopensslで疎通を確かめる 最後にDNSです。Route 53なら、手順2で控えた2つの値をエイリアスの向き先に入れた変更バッチを作ります。 ``` { "Changes": [{ "Action": "UPSERT", "ResourceRecordSet": { "Name": "api.example.com", "Type": "A", "AliasTarget": { "DNSName": "d-abcd1234ef.execute-api.ap-northeast-1.amazonaws.com", "HostedZoneId": "Z1YSHQZHG15GKL", "EvaluateTargetHealth": false } } }] } ``` ``` # --hosted-zone-id は自分のexample.comのゾーンID（Z1YSHQZHG15GKLではない） aws route53 change-resource-record-sets \ --hosted-zone-id Z0EXAMPLE123456 \ --change-batch file://alias-api.json # 名前解決と証明書、APIの応答を順に確かめる dig +short api.example.com openssl s_client -connect api.example.com:443 -servername api.example.com < /dev/null | openssl x509 -noout -subject -dates curl -i https://api.example.com/v1/orders ``` 取り違えやすいのはホストゾーンIDが2種類出てくる点です。`AliasTarget`の中にはAPI Gateway側のID、コマンドの`--hosted-zone-id`には自分のドメインのIDを入れます。[Route 53の手順](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)では、変更は通常60秒以内に全サーバーへ伝わり、API Gatewayへのエイリアス照会は無料です。Aレコードとエイリアス、CNAMEの違いは[Aレコードとは？IPv4アドレスへの対応付けとAAAA/CNAMEとの違い・書き方・digでの確認を実装者向けに解説](https://www.issoh.co.jp/tech/details/14679/)で確認できます。 ## ベースパスマッピングとルーティングルールの選び分け｜複数APIと版の管理 1つのドメインに複数のAPIや版を載せ始めると、振り分けの方式を選ぶ必要が出てきます。方式はドメイン名ごとのルーティングモードで決まります。 ### 最長一致で振り分けるマルチレベルのAPIマッピングと200件の上限 APIマッピングの仕様では、`orders/v1/items`のような複数階層のパスは、RegionalかつTLS 1.2のドメイン名でだけ使えます。リクエストは最も長く一致したパスのAPIへ送られ、空のパス`(none)`はどれにも一致しなかったリクエストの受け皿になります。 制約は数字で押さえておきます。パスは最大300文字、複数階層のマッピングは1ドメインあたり200件までで、単一階層の分は数えません。複数階層を使うとヘッダー名がすべて小文字に変換されるため、バックエンドがヘッダー名の大文字小文字で分岐していると挙動が変わります。WebSocket APIは、RESTやHTTP APIと同じドメイン名に割り当てられません。 ### 2025年6月追加のルーティングルールでヘッダーにより版を振り分ける [2025年6月の発表](https://aws.amazon.com/about-aws/whats-new/2025/06/amazon-api-gateway-routing-rules-rest-apis/)で、REST APIのカスタムドメインにルーティングルールが加わりました。[ルーティングルールの仕様](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-routing-rules.html)では、1つのルールにヘッダー条件を2つまでとベースパス条件を1つ置けて、優先度は1から1,000,000の小さい順に評価されます。行き先にできるのはREST APIのステージだけです。 ``` # 既定のAPI_MAPPING_ONLYから、ルール優先・マッピング併用のモードへ切り替える aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --routing-mode ROUTING_RULE_THEN_API_MAPPING # x-api-version: 2 のヘッダーが付いたリクエストだけを新しいAPIへ送る aws apigatewayv2 create-routing-rule \ --domain-name api.example.com \ --priority 50 \ --conditions '[{"MatchHeaders":{"AnyOf":[{"Header":"x-api-version","ValueGlob":"2"}]}}]' \ --actions '[{"InvokeApi":{"ApiId":"f6g7h8i9j0","Stage":"prod"}}]' ``` ルールに一致しなかったリクエストは、手順3で作ったAPIマッピングで処理されます。[ルーティングモードの説明](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-routing-mode.html)によると、既定は全ドメインでAPI\_MAPPING\_ONLYです。`apigateway`側のCLIでは同じモードを`BASE_PATH_MAPPING_ONLY`などの別名で指定します。`Authorization`や`x-amz-`で始まるヘッダーは条件に使えません。 ### APIマッピングで足りる構成とルーティングルールへ移るべき構成 AWSは[ルーティングモードの選び方](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-routing-mode.html)で、可能ならルーティングルールを使うよう勧めています。ただし同じドメインにHTTP APIのマッピングが1本でもあると、ルーティングルールは使えません。 判断は次のとおりです。パスで版を分けるだけならAPIマッピングで十分で、モードを変える必要はありません。URLを変えずにヘッダーで新旧のAPIを切り替えたい、一部の利用者だけを新しい版へ流したいという要件が出た時点でルーティングルールに移ります。HTTP APIを同居させる構成では、ドメイン名を分けてください。 ## カスタムドメインがつながらないときの切り分け｜DNS・証明書・403の順に確認 症状は、名前が引けない、TLSでつながらない、つながるが403が返る、の3段階に分かれます。手前の段階から順に確かめると早く絞れます。 ### 名前解決できない・証明書エラーになるときの確認順と典型的な原因 カスタムドメインの概要には、DNSプロバイダー側のレコードが無いとリクエストはAPI Gatewayに届かないと書かれています。`dig`で何も返らなければ、手順4のレコード作成漏れか、別のホストゾーンに作った可能性がある状態です。ドメインのネームサーバーがRoute 53を向いているかも確かめます。 名前は引けるのにTLSで失敗する場合は証明書を疑います。典型はEdge-optimizedなのに東京の証明書を選ぼうとした、Regionalなのにus-east-1の証明書を作った、証明書の名前に`api.example.com`が入っていない、の3つです。[カスタムドメインの概要](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html)によると、ドメイン名はリージョン内で全アカウントを通じて一意なので、他のアカウントが同じ名前を先に作っていると登録自体ができません。API GatewayはSNIでドメインを判別するため、SNIを送らない古いクライアントからは接続できない点にも注意してください。 ### 403 Forbiddenが返るときのマッピング漏れと既定エンドポイント無効化 TLSまで通って403が返るなら、振り分けの問題です。[ルーティングルールの評価例](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-routing-rules-examples.html)では、どのルールにもマッピングにも一致しないリクエストは403で拒否されます。[ゲートウェイレスポンスの一覧](https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html)にある`MISSING_AUTHENTICATION_TOKEN`も403で、存在しないリソースやメソッドを呼んだ場合も、その対象です。ベースパスが取り除かれることを忘れて、API側に`/v1/orders`のリソースを探させているケースがこれに当たります。 反対に、カスタムドメインは動くのに既定のURLで403が返るのは、既定エンドポイントを無効にした結果です。[既定エンドポイントの無効化](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-disable-default-endpoint.html)は全ステージに効き、ステージを再デプロイした時点で反映されます。 ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3d4e5 \ --patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True' aws apigateway create-deployment --rest-api-id a1b2c3d4e5 --stage-name prod ``` WAFの評価や監視をカスタムドメイン経由の通信だけに集めたいなら、移行が終わった段階でこの設定を入れます。既定のURLを直接呼んでいるバッチや外部連携が残っていると、その時点で止まるため、事前にアクセスログで呼び出し元を洗い出してください。 ## エンドポイント種別とTLSポリシーの採用判断｜Regionalを選ぶ条件 ここまでの仕様を踏まえて、どの構成を選ぶかを決めます。東京リージョンで業務APIを提供する前提では、選択肢はかなり絞れます。 ### 東京中心の業務APIはRegionalを選びEdge-optimizedを見送る理由 Edge-optimizedを見送る理由は4つあります。証明書をus-east-1に別に用意する必要があること、作成や証明書の差し替えのたびに約40分待つこと、複数階層のマッピングとHTTP APIの割り当てができないことです。さらに[API Gatewayのタイムアウト](https://www.issoh.co.jp/tech/details/18479/)で整理したとおり、統合タイムアウトを29秒より延ばす申請もEdge-optimizedのREST APIでは使えません。 海外の利用者が多く、エッジでの配信が本当に要る場合も、Regionalのドメイン名の前に自前のCloudFrontを置く構成をとります。キャッシュの方針やオリジンの保護を自分で決められるからです。組み方は[CloudFront×API Gateway×Lambdaの連携構成｜設定手順と403の原因・直アクセスの遮断方法](https://www.issoh.co.jp/tech/details/6799/)で解説しています。 ### TLS\_1\_2の既定で足りる場面と拡張セキュリティポリシーへ上げる条件 [セキュリティポリシーの解説](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-custom-domain-tls-version.html)では、`TLS_1_0`と`TLS_1_2`をレガシー、`SecurityPolicy_`で始まるものを拡張ポリシーと呼んでいます。`SecurityPolicy_TLS13_1_3_2025_09`のような拡張ポリシーはTLS 1.3だけを受け付けますが、エンドポイントアクセスモードの設定が必須で、相互TLSとHTTP APIの割り当てが使えなくなります。変更が反映されるまでの時間は約15分です。 結論として、新規のドメイン名は`TLS_1_2`で作り、`TLS_1_0`は選びません。業界の監査基準でTLS 1.3限定を求められた場合に限り拡張ポリシーへ上げます。取引先ごとにクライアント証明書で認証したい要件があるなら、相互TLSが使えるレガシーの`TLS_1_2`のままにします。利用者単位の認証をCognitoやLambdaオーソライザーで掛ける方法は[API Gatewayの認証：Cognito・JWT・Lambdaオーソライザー・IAM認可の使い分けと設定例](https://www.issoh.co.jp/tech/details/18493/)で比較しています。不正なリクエストの遮断は[API GatewayにAWS WAFを関連付ける手順](https://www.issoh.co.jp/tech/details/18481/)で別に手当てしてください。複数のAPIを1つのドメインに集約する設計や、既定のURLで公開しているAPIの移行を外部に相談したい場合は、[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)のページで支援内容を紹介しています。 ## API Gatewayのカスタムドメインについてよくある質問と回答 API Gatewayのカスタムドメインを設定する際によく出る質問に答えます。 ### カスタムドメインの証明書はどのリージョンで作ればよいですか？ Regionalのドメイン名ならAPIと同じリージョン、東京のAPIなら東京リージョンのACMで作ります。Edge-optimizedのドメイン名だけは、APIのリージョンに関係なくバージニア北部（us-east-1）の証明書が必要です。証明書には対象のドメイン名が含まれている必要があり、ワイルドカードの`*.example.com`を使う場合はACMが発行した証明書に限られます。 ### HTTP APIでもカスタムドメインは使えますか？ 使えます。HTTP APIはRegionalのドメイン名に割り当て、セキュリティポリシーはTLS 1.2だけです。REST APIと同じドメイン名にAPIマッピングで同居させることもできますが、その場合ルーティングルールは使えません。ヘッダーでの振り分けが要るなら、HTTP API用のドメイン名を分けてください。 ### example.comのようなルートドメインをAPI Gatewayに向けられますか？ 向けられます。ドメイン名にはサブドメインだけでなくゾーンの頂点も指定でき、Route 53のAエイリアスならゾーン頂点にも作成可能です。一般的なDNSの仕様ではゾーン頂点にCNAMEを置けないため、Route 53以外のDNSで頂点を向けたい場合は、そのサービスが同等のエイリアス機能を持っているかを先に確かめます。 ### Route 53以外のDNSサービスを使っている場合はどう設定しますか？ 他社のDNSでは、`api.example.com`から`d-`で始まるターゲット名へのCNAMEを作ります。Regionalの設定手順にも、他社DNSで指定するのはCNAMEとの記載です。ACMの検証用CNAMEも同じDNSに手で登録します。なお、プライベートAPI用のVPCエンドポイントでプライベートDNSを有効にしているVPCの中からは、CNAMEで作ったカスタムドメインを名前解決できません。 ### カスタムドメインの証明書は期限切れ前に更新作業が必要ですか？ ACMが発行した証明書なら自動で更新され、作業は要りません。外部の認証局から取り込んだ証明書は自動更新されないため、期限前に新しい証明書を取り込んで差し替えます。証明書の固定（ピン留め）をしているアプリは、ACMの自動更新の後に接続できなくなることがあるので、固定の対象を見直してください。 ## 関連記事 - [APIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説](https://www.issoh.co.jp/tech/details/13210/)：カスタムドメインの前提になるAPIゲートウェイの役割と導入判断。 - [Amazon Route 53とは：DNS・ドメイン登録・ルーティング設計とAWS CLI構築手順を実装者目線で解説](https://www.issoh.co.jp/tech/details/15471/)：ホストゾーンやエイリアスなどRoute 53の設計全般。 - [AWS Certificate Managerとは？有効期間198日化とACME対応・料金と採用判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15898/)：カスタムドメインで使う証明書の発行と更新の仕組み。 - [API Gatewayの料金を東京リージョンの実額で計算する：REST・HTTP・WebSocketの単価と付帯課金](https://www.issoh.co.jp/tech/details/18477/)：API Gateway本体と付帯サービスの費用。 - [mTLSとは？相互TLS認証の仕組みとクライアント証明書・導入判断を実装目線で解説](https://www.issoh.co.jp/tech/details/14378/)：Regionalのカスタムドメインで使える相互TLS認証の考え方。 --- 出典: [API Gatewayのカスタムドメイン設定：ACM証明書・Route 53・ベースパスマッピングをCLIで構築]()（株式会社一創）