本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 教學：建立和調用私有 API 的自訂網域名稱 在本教學課程中，您會建立一個可以在自己的帳戶中的 VPC 中調用的私有自訂網域名稱。為完成此操作，您既是 API 提供者，也是 API 取用者。您需要現有的私有 API 和 VPC 端點才能完成本教學課程。如果您有用於存取公有自訂網域名稱的 VPC 端點，請勿將其用於本教學課程或建立任何網域名稱存取關聯。 ## 步驟 1：建立私有自訂網域名稱 您可以透過指定網域名稱、ACM 憑證和 `execute-api` 服務的政策來建立私有自訂網域名稱，以控制哪些 VPC 端點可以調用該名稱。 ------ #### [ AWS 管理主控台 ] **建立私有自訂網域名稱** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 在主要導覽窗格中，選擇**自訂網域名稱**。 1. 選擇**新增網域名稱**。 1. 在 **Domain name (網域名稱)** 中，輸入網域名稱。 您的 ACM 憑證必須包含此網域名稱，但網域名稱不必是唯一的。 1. 選取**私有**。 1. 針對**路由模式**，選擇**僅 API 映射**。 1. 針對 **ACM 憑證**，選取憑證。 1. 選擇**新增網域名稱**。 API Gateway 會使用 `deny` 所有資源政策佈建網域名稱。這是 `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. 選擇**儲存變更**。 ------ #### [ 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。您也需要授予對 VPC 端點的存取權，如此才能調用映射至私有自訂網域名稱的任何私有 API。 ------ #### [ AWS 管理主控台 ] **建立基本路徑映射** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 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 中建立私有託管區域以解析自訂網域名稱。託管區域是一種容器，其中包含的資訊說明您可以如何在一或多個 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 ] 若要設定您的 DNS 記錄，將私有自訂網域名稱映射至指定託管區域 ID 的主機名稱，請先建立 JSON 檔案，其中包含用於設定私有網域名稱之 DNS 記錄的組態。 以下 `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. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 在主要導覽窗格中，選擇**網域名稱存取關聯**。 1. 選取您的網域名稱存取關聯，然後選擇**刪除**。 1. 確認您的選擇，然後選擇**刪除**。 刪除網域名稱存取關聯後，您可以刪除私有自訂網域名稱。 **刪除您的私有自訂網域名稱** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 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)。 ------ ## 最佳實務 我們建議您在建立私有自訂網域名稱時使用下列最佳實務： + 使用基本路徑映射或路由規則，將流量從一個私有自訂網域名稱傳送至多個私有 API。 + 當 VPC 端點不再需要存取私有自訂網域名稱時，請刪除關聯。此外，從私有自訂網域的 `execute-api` 服務的 `policy` 中移除 VPC 端點。 + 為每個 VPC 端點設定至少兩個可用區域。 + 停用預設端點。建議您停用預設端點，以允許您的 API 取用者只從自訂網域名稱呼叫您的 API。如需詳細資訊，請參閱[停用 REST API 的預設端點](rest-api-disable-default-endpoint.md)。 + 建議您在設定私有自訂網域名稱時，佈建 Route 53 私有託管區域和 A 型記錄。如果您不打算調用自己的私有自訂網域名稱，您可以稍後刪除這些資源。