# チュートリアル: プライベート API のカスタムドメイン名を作成して呼び出す
このチュートリアルでは、お客様独自のアカウントの VPC で呼び出し可能なプライベートカスタムドメイン名を作成します。これを行うには、お客様が API プロバイダーと API コンシューマーになります。このチュートリアルを完了するには、既存のプライベート API と VPC エンドポイントが必要です。パブリックカスタムドメイン名へのアクセスに使用している VPC エンドポイントがある場合、そのエンドポイントをこのチュートリアルやドメイン名アクセスの関連付けの作成に使用しないでください。
## ステップ 1: プライベートカスタムドメイン名を作成する
プライベートカスタムドメイン名を作成するには、ドメイン名、ACM 証明書、`execute-api` サービスのポリシーを指定して、どの VPC エンドポイントがそのドメイン名を呼び出せるかを制御します。
------
#### [ AWS マネジメントコンソール ]
**プライベートカスタムドメイン名を作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[カスタムドメイン名]** を選択します。
1. **[ドメイン名の追加]** を選択します。
1. [**ドメイン名**] には、ドメイン名を入力します。
ACM 証明書はこのドメイン名をカバーしている必要がありますが、ドメイン名は一意である必要はありません。
1. **[Private]** (プライベート) を選択します。
1. **[ルーティングモード]** では、**[API マッピングのみ]** を選択します。
1. **[ACM 証明書]** で、証明書を選択します。
1. **[ドメイン名の追加]** を選択します。
API Gateway は「`deny` all resource policy」でドメイン名をプロビジョニングします。これは `execute-api` サービス用のリソースポリシーです。VPC エンドポイントにプライベートカスタムドメイン名を呼び出すためのアクセスを許可するように、このリソースポリシーを更新する必要があります。
**リソースポリシーを更新するには**
1. **[リソースポリシー]** タブを選択し、**[リソースポリシーの編集]** を選択します。
1. コードエディタに次のリソースポリシーを入力します。VPC エンドポイント {{vpce-abcd1234efg}} をお客様独自の VPC エンドポイント ID に置き換えます。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "{{vpce-abcd1234}}"
}
}
}
]
}
```
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
AWS CLI を使用してプライベートカスタムドメイン名を作成する場合は、`execute-api` サービスに関するリソースポリシーで、VPC エンドポイントにプライベートカスタムドメイン名を呼び出すためのアクセスを許可しておき、`--policy file://policy.json` パラメータでそのポリシーを指定します。このポリシーは後で変更できます。
この例では、ファイルからパラメータを読み込むことで、次のリソースポリシーを `policy` としてアタッチします。このファイルを `policy.json` としてコピーして保存します。このポリシーでは、VPC エンドポイント {{`vpce-abcd1234efg`}} からプライベートカスタムドメイン名への受信トラフィックのみを許可します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "{{vpce-abcd1234}}"
}
}
}
]
}
```
次の [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html) コマンドは、プライベートカスタムドメイン名を作成します。
```
aws apigateway create-domain-name \
--domain-name 'private.example.com' \
--certificate-arn 'arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef' \
--security-policy 'TLS_1_2' \
--endpoint-configuration '{"types":["PRIVATE"]}' \
--policy file://policy.json
```
出力は次のようになります。
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
]
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"routingMode" : "API_MAPPING_ONLY",
"policy": "..."
}
```
------
## ステップ 2: プライベート API をプライベートカスタムドメイン名にマッピングするためのベースパスマッピングを作成する
プライベートカスタムドメイン名の作成後、プライベート API をそのドメイン名にマッピングします。ベースパスマッピングにより、プライベートカスタムドメイン名および関連するベースパスを組み合わせて API にアクセスできるようになります。複数のプライベート API のホスト名として単一のプライベートカスタムドメイン名を使用することをお勧めします。
お客様が独自の API を呼び出す予定がない場合でも、API プロバイダーはベースパスマッピングを作成する必要があります。また、プライベートカスタムドメイン名にマッピングしたプライベート API を呼び出すためのアクセスを VPC エンドポイントに許可する必要があります。
------
#### [ AWS マネジメントコンソール ]
**ベースパスマッピングを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[カスタムドメイン名]** を選択します。
1. プライベートカスタムドメイン名を選択します。
1. **[API マッピング]** タブで、**[マッピングの設定]** を選択します。
1. [**Add new mapping (新しいマッピングを追加)**] を選択します。
1. **API**、**Stage**、必要に応じて **Path** を入力します。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [create-base-path-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-base-path-mapping.html) コマンドは、プライベート API とプライベートカスタムドメイン名との間にマッピングを作成します。
```
aws apigateway create-base-path-mapping \
--domain-name-id abcd1234 \
--domain-name 'private.example.com' \
--rest-api-id a1b2c3 \
--stage prod \
--base-path v1
```
出力は次のようになります。
```
{
"basePath": "v1",
"restApiId": "a1b2c3",
"stage": "prod"
}
```
------
API へのトラフィックのルーティング方法をより柔軟にするために、ルーティングモードを `ROUTING_RULE_ONLY` または `ROUTING_RULE_THEN_API_MAPPING` に変更し、ルーティングルールを作成することができます。詳細については、「[API Gateway のカスタムドメイン名を使用して API にトラフィックを送信します。](rest-api-routing-mode.md)」を参照してください。
**注記**
このチュートリアルの完了後、他の AWS アカウント がお客様のプライベートカスタムドメイン名を呼び出せるようにする場合は、「[API プロバイダー: AWS RAM を使用してプライベートカスタムドメイン名を共有する](apigateway-private-custom-domains-provider-share.md)」の手順に従います。
## ステップ 3: カスタムドメイン名と VPC エンドポイントとの間にドメイン名アクセスの関連付けを作成する
次に、プライベートカスタムドメイン名と VPC エンドポイントの間にドメイン名アクセスの関連付けを作成します。VPC エンドポイントは、ドメイン名アクセスの関連付けを使用して、パブリックインターネットから隔離された状態でプライベートカスタムドメイン名を呼び出します。
------
#### [ AWS マネジメントコンソール ]
**ドメイン名アクセスの関連付けを作成するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[カスタムドメイン名]** を選択します。
1. プライベートカスタムドメイン名を選択します。
1. **[リソース共有]** タブの **[ドメイン名アクセスの関連付け]** で **[ドメイン名アクセスの関連付けを作成]** を選択します。
1. **[ドメイン名 ARN]** で、ドメイン名を選択します。
1. **[VPC エンドポイント ID]** で、ステップ 1 でアクセスを許可した VPC エンドポイント ID を選択します。
1. **[ドメイン名アクセスの関連付け]** を選択します。
コンソールの **[ドメイン名アクセスの関連付け]** ページでも、ドメイン名アクセスの関連付けを作成できます。
------
#### [ AWS CLI ]
次の `create-domain-name-access-association` コマンドは、プライベートカスタムドメイン名と VPC エンドポイントとの間にドメイン名アクセスの関連付けを作成します。
```
aws apigateway create-domain-name-access-association \
--domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \
--access-association-source vpce-abcd1234efg \
--access-association-source-type VPCE \
--region us-west-2
```
出力は次のようになります。
```
{
"domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg",
"accessAssociationSource": "vpce-abcd1234efg",
"accessAssociationSourceType": "VPCE",
"domainNameARN" : "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234"
}
```
------
ドメイン名アクセスの関連付けを作成してから使用可能になるまでに、約 15 分かかります。待っている間に、次の手順に進むことができます。
## ステップ 4: Route 53 ホストゾーンを作成する
プライベートカスタムドメイン名を VPC エンドポイントに関連付けるようにリソースポリシーを更新した後、Route 53 でプライベートホストゾーンを作成して、カスタムドメイン名を解決できるようにします。ホストゾーンは、インターネットにリソースを公開することなく、1 つ以上の VPC 内のドメインのトラフィックをルーティングする方法に関する情報を保持するコンテナです。詳細については、「[プライベートホストゾーンの使用](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
AWS マネジメントコンソール を使用するには、*Amazon Route 53 開発者ガイド*の「[プライベートホストゾーンの作成](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html)」を参照してください。
**[名前]** には、プライベートカスタムドメイン名の名前を使用します。**[VPC ID]** には、前の手順で使用した VPC エンドポイントを含む VPC を使用します。
------
#### [ AWS CLI ]
次の [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) コマンドは、プライベートホストゾーンを作成します。
```
aws route53 create-hosted-zone --name private.example.com \
--caller-reference 2014-04-01-18:47 \
--hosted-zone-config Comment="command-line version",PrivateZone=true \
--vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234
```
出力にはホストゾーン ID が含まれます。このホストゾーン ID は以降の手順で使用します。
------
## ステップ 5: Route 53 DNS レコードを作成する
ホストゾーンを作成した後、プライベートカスタムドメイン名を解決するためのレコードを作成します。前のステップで作成したホストゾーン ID を使用します。この例では、A レコードタイプを作成します。VPC エンドポイントに IPv6 を使用している場合は、AAAA レコードタイプを作成します。VPC エンドポイントにデュアルスタックを使用している場合は、AAAA レコードタイプと A レコードタイプの両方を作成します。
------
#### [ AWS マネジメントコンソール ]
AWS マネジメントコンソール を使用するには、「[ドメイン名を使用してトラフィックを Amazon API Gateway API にルーティングする](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)」を参照してください。
**[クイック作成]** を使用し、**[エイリアス]** をオンにします。エンドポイントには、VPC エンドポイント DNS 名を使用します。
------
#### [ AWS CLI ]
プライベートカスタムドメイン名を特定のホストゾーン ID のホスト名にマッピングするように DNS レコードを設定するには、プライベートドメイン名の DNS レコードを指定するための設定を含む JSON ファイルを作成します。
次の `setup-dns-record.json` は、プライベートカスタムドメイン名をプライベートホスト名にマッピングする DNS `A` レコードを作成する方法を示しています。VPC DNS ID の `DNSName` と、前のステップで作成したホストゾーン ID を指定します。
```
{
"Changes": [
{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "private.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"EvaluateTargetHealth": false
}
}
}
]
}
```
次の [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) コマンドは、プライベートカスタムドメイン名の DNS レコードを作成します。
```
aws route53 change-resource-record-sets \
--hosted-zone-id ZABCDEFG1234 \
--change-batch file://{{path/to/your/setup-dns-record.json}}
```
`hosted-zone-id` は、アカウントに設定した DNS レコードの Route 53 ホストゾーン ID に置き換えます。`change-batch` パラメータの値は JSON ファイルを指定します。
------
お客様独自のプライベートカスタムドメイン名を呼び出す予定がない場合は、そのプライベートカスタムドメイン名が機能していることを確認した後、これらのリソースを削除できます。
## ステップ 6: プライベートカスタムドメイン名を呼び出す
お客様独自の AWS アカウント でプライベートカスタムドメイン名を呼び出せるようになりました。VPC 内で次の curl コマンドを使用し、プライベートカスタムドメイン名にアクセスします。
```
curl https://private.example.com/v1
```
プライベート API を呼び出す他の方法の詳細については、「[カスタムドメイン名を使用してプライベート API を呼び出す](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke)」を参照してください。
## ステップ 7: クリーンアップ
不要なコストを防ぐために、VPC エンドポイントとプライベートカスタムドメイン名との間の関連付けを削除した後、プライベートカスタムドメイン名を削除します。
------
#### [ AWS マネジメントコンソール ]
**ドメイン名アクセスの関連付けを削除するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[ドメイン名アクセスの関連付け]** を選択します。
1. ドメイン名アクセスの関連付けを選択した後、**[削除]** を選択します。
1. 選択内容を確認した後、**[削除]** を選択します。
ドメイン名アクセスの関連付けを削除した後、プライベートカスタムドメイン名を削除できます。
**プライベートカスタムドメイン名を削除するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. メインナビゲーションペインで、**[カスタムドメイン名]** を選択します。
1. プライベートカスタムドメイン名を選択します。
1. **[削除]** を選択します。
1. 選択内容を確認した後、**[削除]** を選択します。
必要に応じて、VPC エンドポイントも削除できます。詳細については、「[インターフェイスエンドポイントを削除する](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html)」を参照してください。
------
#### [ AWS CLI ]
**次をクリーンアップするには：**
1. 次の `delete-access-association` コマンドは、ドメイン名アクセスの関連付けを削除します。
```
aws apigateway delete-domain-name-access-association \
--domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' \
--region us-west-2
```
1. 次の `delete-domain-name` コマンドは、プライベートカスタムドメイン名を削除します。このコマンドは、すべてのベースパスマッピングも削除します。
```
aws apigateway delete-domain-name \
--domain-name test.private.com \
--domain-name-id abcd1234
```
必要に応じて、VPC エンドポイントも削除できます。詳細については、「[インターフェイスエンドポイントを削除する](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html)」を参照してください。
------
## ベストプラクティス
プライベートカスタムドメイン名を作成する際は、以下のベストプラクティスに従うことをお勧めします。
+ ベースパスマッピングまたはルーティングルールを使用して、1 つのプライベートカスタムドメイン名から複数のプライベート API にトラフィックを送信します。
+ VPC エンドポイントがプライベートカスタムドメイン名へのアクセスを必要としなくなった場合は、関連付けを削除します。さらに、プライベートカスタムドメインの `policy` サービスの `execute-api` から VPC エンドポイントを削除します。
+ VPC エンドポイントごとに少なくとも 2 つのアベイラビリティーゾーンを設定します。
+ デフォルトのエンドポイントを無効にします。API コンシューマーがカスタムドメイン名からのみ API を呼び出すことができるように、デフォルトのエンドポイントを無効にすることをお勧めします。詳細については、「[REST API のデフォルトのエンドポイントを無効にする](rest-api-disable-default-endpoint.md)」を参照してください。
+ プライベートカスタムドメイン名を設定する際に、Route 53 プライベートホストゾーンと A タイプレコードをプロビジョニングすることをお勧めします。お客様独自のプライベートカスタムドメイン名を呼び出す予定がない場合は、後でこれらのリソースを削除できます。