本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定 API Gateway 中的邊緣最佳化的自訂網域名稱 當您針對邊緣最佳化的 API 建立自訂網域名稱，API Gateway 會設定 CloudFront 分佈和 DNS 記錄，以將 API 網域名稱映射至 CloudFront 分佈網域名稱。接著，透過對應的 CloudFront 分佈，將 API 的請求路由至 API Gateway。此對應適用於要透過對應 CloudFront 分佈路由至 API Gateway 的 API 請求 (繫結至自訂網域名稱)。 ## 考量事項 以下是邊緣最佳化的自訂網域名稱的考量事項： + 若要設定邊緣最佳化自訂網域名稱或更新其憑證，您必須有更新 CloudFront 分佈的許可。 更新 CloudFront 分佈需要下列權限： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] } ``` ------ + 您必須為美國東部 (維吉尼亞北部) – `us-east-1` 區域中的邊緣最佳化的自訂網域名稱請求或匯入憑證。 + API Gateway 所建立的 CloudFront 分佈是由隸屬於 API Gateway 的區域特定帳戶所擁有。在 CloudTrail 中追蹤可建立和更新這類 CloudFront 分佈的操作時，您必須使用此 API Gateway 帳戶 ID。如需詳細資訊，請參閱[CloudTrail 中的日誌自訂網域名稱建立](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail)。 + API Gateway 透過在 CloudFront 分佈上利用伺服器名稱指示 (SNI)，來支援邊緣最佳化自訂網域名稱。如需在 CloudFront 分佈上使用自訂網域名稱的詳細資訊 (包含必要憑證格式和憑證金鑰長度大小上限)，請參閱《Amazon CloudFront 開發人員指南》**中的[使用備用網域名稱和 HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html) + 邊緣最佳化的自訂網域名稱大約需要 40 分鐘才能準備就緒。 + 建立邊緣最佳化的自訂網域名稱之後，您必須建立 DNS 記錄，將自訂網域名稱映射至 CloudFront 分佈名稱。 ## 建立邊緣最佳化的自訂網域名稱 下列程序說明如何建立 API 的邊緣最佳化自訂網域名稱。 ------ #### [ AWS 管理主控台 ] 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 從主要導覽窗格中，選擇 **Custom Domain Names (自訂網域名稱)**。 1. 選擇**新增網域名稱**。 1. 在 **Domain name (網域名稱)** 中，輸入網域名稱。 1. 針對**路由模式**，選擇 **API\$1MAPPING\$1ONLY**。 1. 對於 **API 端點類型**，選擇**邊緣最佳化**。 1. 選擇最低版本的 TLS。 1. 選擇 ACM 憑證。 1. 選擇**新增網域名稱**。 ------ #### [ REST API ] 1. 呼叫 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)，並指定 AWS Certificate Manager中所存放憑證的自訂網域名稱和 ARN。 成功 API 呼叫會傳回 `201 Created` 回應，其中包含憑證 ARN，以及其承載中的相關聯 CloudFront 分佈名稱。 1. 請記下輸出中所顯示的 CloudFront 分佈網域名稱。在後續步驟中，您需要用該名稱來設定自訂網域之 DNS 中的 A 記錄別名目標。 如需此 REST API 呼叫的程式碼範例，請參閱 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)。 ------ 邊緣最佳化的自訂網域名稱大約需要 40 分鐘才能準備好，但主控台會立即以 `distribution-id.cloudfront.net` 的形式顯示關聯的 CloudFront 分佈網域名稱，以及憑證 ARN。同時，您可以建立基本路徑映射或路由規則，然後設定 DNS 記錄別名，以將自訂網域名稱對應至相關聯的 CloudFront 分佈網域名稱。 ## 使用自訂網域名稱作為其主機名稱來設定 API 的基本路徑對應 由於您將路由模式設定為 `API_MAPPING_ONLY`，因此您可以使用基本路徑映射，以將單一自訂網域名稱作為多個 API 的主機名稱使用。這可透過自訂網域名稱與相關聯基本路徑的組合，使 API 變成可存取。 例如，若您已在 API Gateway 中建立名為 `PetStore` 的 API 和名為 `Dogs` 的另一個 API，並設定 `api.example.com` 的自訂網域名稱，則可以將 `PetStore` API 的 URL 設定為 `https://api.example.com`。 這會建立 `PetStore` API 與空字串的基本路徑的關聯。如果您將 `PetStore` API 的 URL 設定為 `https://api.example.com/PetStore`，這會建立 `PetStore` API 與 `PetStore` 的基本路徑的關聯。您可以指派 `Dogs` API 的 `MyDogList` 的基本路徑。`https://api.example.com/MyDogList` URL 接著會是 `Dogs` API 的根 URL。 若要在多個層級上設定 API 映射，您只能使用區域性自訂網域名稱。不支援邊緣最佳化的自訂網域名稱。如需詳細資訊，請參閱[使用 API 映射將 API 階段連線至 REST APIs 的自訂網域名稱](rest-api-mappings.md)。 下列程序會設定 API 映射，以將自訂網域名稱的路徑映射至 API 階段。 ------ #### [ AWS 管理主控台 ] 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 從 API Gateway 主控台主要導覽窗格中，選擇 **Custom Domain Names (自訂網域名稱)**。 1. 選擇自訂網域名稱。 1. 選擇 **Configure API mappings (設定 API 映射)**。 1. 選擇 **Add new mapping (新增對應)**。 1. 指定對應的 **API**、**Stage (階段)** 及 **Path (路徑)** (選擇性)。 1. 選擇**儲存**。 ------ #### [ REST API ] 在特定自訂網域名稱上呼叫 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)，並在請求承載中指定 `basePath`、`restApiId` 和部署 `stage` 屬性。 成功 API 呼叫會傳回 `201 Created` 回應。 如需 REST API 呼叫的程式碼範例，請參閱 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)。 ------ 如要以更有彈性的方式將流量路由至 API，您可以將路由模式變更為 `ROUTING_RULE_ONLY` 或 `ROUTING_RULE_THEN_API_MAPPING`，並建立路由規則。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。 ## 為您的邊緣最佳化的自訂網域名稱建立 DNS 記錄 開始建立邊緣最佳化的自訂網域名稱後，請設定 DNS 記錄別名。 建議您使用 Route 53，為自訂網域名稱建立 A 記錄別名，並指定 CloudFront 分佈網域名稱做為別名目標。這表示 Route 53 可以路由自訂網域名稱，即使是 Zone Apex 也是一樣。如需詳細資訊，請參閱《Amazon Route 53 開發人員指南》**中的[在別名與非別名資源記錄集之間選擇](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html)。 有關 Amazon Route 53 的指示，請參閱*《Amazon Route 53 開發人員指南》*中的[使用您的網域名稱將流量路由到 Amazon API Gateway API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)。 ## CloudTrail 中的日誌自訂網域名稱建立 啟用 CloudTrail 來記錄您帳戶所進行的 API Gateway 呼叫時，API Gateway 會在建立或更新 API 的自訂網域名稱時記錄相關聯 CloudFront 分佈更新。這些日誌可於 `us-east-1` 中取得。因為這些 CloudFront 分佈是 API Gateway 所擁有，所以所有這些報告的 CloudFront 分佈都是透過下列其中一個區域特定 API Gateway 帳戶 ID 來識別，而不是 API 擁有者的帳戶 ID。 | **區域** | **帳戶 ID** | | --- | --- | | us-east-1 | 392220576650 | | us-east-2 | 718770453195 | | us-west-1 | 968246515281 | | us-west-2 | 109351309407 | | ca-central-1 | 796887884028 | | eu-west-1 | 631144002099 | | eu-west-2 | 544388816663 | | eu-west-3 | 061510835048 | | eu-central-1 | 474240146802 | | eu-central-2 | 166639821150 | | eu-north-1 | 394634713161 | | eu-south-1 | 753362059629 | | eu-south-2 | 359345898052 | | ap-northeast-1 | 969236854626 | | ap-northeast-2 | 020402002396 | | ap-northeast-3 | 360671645888 | | ap-southeast-1 | 195145609632 | | ap-southeast-2 | 798376113853 | | ap-southeast-3 | 652364314486 | | ap-southeast-4 | 849137399833 | | ap-south-1 | 507069717855 | | ap-south-2 | 644042651268 | | ap-east-1 | 174803364771 | | sa-east-1 | 287228555773 | | me-south-1 | 855739686837 | | me-central-1 | 614065512851 | ## 輪換匯入至 ACM 的憑證 ACM 會自動處理它所發出之憑證的續約。您不需要輪換自訂網域名稱的任何 ACM 發出憑證。CloudFront 會代表您處理這項操作。 不過，如果您將憑證匯入至 ACM，並將它用於自訂網域名稱，則您必須在憑證過期之前輪換憑證。這包含匯入網域名稱的新第三方憑證，並將現有憑證輪換為新的憑證。新匯入的憑證過期時，您需要重複進行此程序。或者，您可以請求 ACM 發出網域名稱的新憑證，並將現有憑證輪換為新的 ACM 發出憑證。之後，您可以讓 ACM 和 CloudFront 自動處理憑證輪換。若要建立或匯入新的 ACM 憑證，請遵循 [建立 SSL/TLS 憑證或將其匯入 ACM](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup) 中的步驟。 下列程序說明如何輪換網域名稱的憑證。 **注意** 輪換匯入 ACM 的憑證大約需要 40 分鐘。 ------ #### [ AWS 管理主控台 ] 1. 在 ACM 中請求或匯入憑證。 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 從 API Gateway 主控台主要導覽窗格中，選擇 **Custom Domain Names (自訂網域名稱)**。 1. 選擇邊緣最佳化的自訂網域名稱。 1. 針對**端點組態**，選擇**編輯**。 1. 針對 **ACM 憑證**，從下拉式清單選取憑證。 1. 選擇**儲存變更**，開始輪換自訂網域名稱的憑證。 ------ #### [ REST API ] 呼叫 [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) 動作，並指定所指定網域名稱之新 ACM 憑證的 ARN。 ------ #### [ AWS CLI ] 以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 會更新邊緣最佳化網域名稱的 ACM 憑證。 ``` aws apigateway update-domain-name \ --domain-name edge.example.com \ --patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'" ``` 以下 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 會更新區域網域名稱的 ACM 憑證。 ``` aws apigateway update-domain-name \ --domain-name regional.example.com \ --patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'" ``` ------ ## 當您使用基本路徑映射時，使用自訂網域名稱呼叫您的 API 呼叫具有自訂網域名稱的 API 與呼叫具有其預設網域名稱的 API 相同，但前提是使用正確的 URL。 下列範例會比較和對比所指定區域 (`udxjef`) 中兩個 API (`qf3duz` 和 `us-east-1`) 以及所指定自訂網域名稱 (`api.example.com`) 的一組預設 URL 和對應自訂 URL。 | API ID | 階段 | 預設 URL | 基本路徑 | 自訂 URL | | --- | --- | --- | --- | --- | | udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /petstore | https://api.example.com/petstore | | udxjef | tst | https://udxjef.execute-api.us-east-1.amazonaws.com/tst | /petdepot | https://api.example.com/petdepot | | qf3duz | dev | https://qf3duz.execute-api.us-east-1.amazonaws.com/dev | /bookstore | https://api.example.com/bookstore | | qf3duz | tst | https://qf3duz.execute-api.us-east-1.amazonaws.com/tst | /bookstand | https://api.example.com/bookstand | 如要以更有彈性的方式將流量路由至 API，您可以建立路由規則。如需詳細資訊，請參閱[在 API Gateway 中透過您的自訂網域名稱將流量傳送至 API](rest-api-routing-mode.md)。 API Gateway 使用[伺服器名稱指示 (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) 來支援 API 的自訂網域名稱。您可以使用支援 SNI 的瀏覽器或用戶端程式庫，以使用自訂網域名稱來呼叫 API。 API Gateway 會在 CloudFront 分佈上強制執行 SNI。如需 CloudFront 如何使用自訂網域名稱的資訊，請參閱 [Amazon CloudFront 自訂 SSL](https://aws.amazon.com/cloudfront/custom-ssl-domains/)。