在 API Gateway 中設定邊緣最佳化的自訂網域名稱 - Amazon API Gateway
考量事項建立邊緣最佳化自訂網域名稱為邊緣最佳化的自訂網域名稱建立 DNS 記錄記錄自定義域名創建 CloudTrail使用自訂網域名稱作為其主機名稱來設定 API 的基本路徑對應輪換匯入至 ACM 的憑證呼叫具有自訂網域名稱的 API

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 API Gateway 中設定邊緣最佳化的自訂網域名稱

當您為邊緣最佳化 API 建立自訂網域名稱時，API Gateway 會設定 CloudFront 分發和 DNS 記錄，以將 API 網域名稱對應至 CloudFront 發佈網域名稱。接著，API 的要求會透過對應的 CloudFront 分發路由至 API Gateway。此對應適用於綁定自訂網域名稱的 API 請求，以透過對應的 CloudFront 散佈路由至 API Gateway。

考量事項

以下是邊緣最佳化自訂網域名稱的考量事項。

  • 若要設定邊緣最佳化的自訂網域名稱或更新其憑證，您必須擁有更新 CloudFront 發佈的權限。

    更新 CloudFront 發行版需要下列權限：

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

  • 您必須在美國東部 (維吉尼亞北部) — us-east-1 區域為邊緣最佳化自訂網域名稱申請或匯入憑證。

  • API Gateway 建立的 CloudFront 散佈是由與 API Gateway 關聯的區域特定帳戶所擁有。追蹤作業以在中建立和更新此類 CloudFront 散發時 CloudTrail，您必須使用此 API Gateway 帳戶 ID。如需詳細資訊，請參閱 記錄自定義域名創建 CloudTrail。

  • API Gateway 透過在散發上利用伺服器名稱指示 (SNI)，來支援邊緣最佳化的自訂網域名稱。 CloudFront 如需有關在 CloudFront 分發上使用自訂網域名稱的詳細資訊，包括所需的憑證格式和憑證金鑰長度的大小上限，請參閱 Amazon CloudFront 開發人員指南中的使用替代網域名稱和 HTTPS

  • 邊緣最佳化的自訂網域名稱大約需要 40 分鐘才能準備就緒。

  • 建立邊緣最佳化自訂網域名稱之後，您必須建立 DNS 記錄，將自訂網域名稱對應至 CloudFront 通訊群組名稱。

建立邊緣最佳化自訂網域名稱

下列程序說明如何為 API 建立邊緣最佳化的自訂網域名稱。

AWS Management Console

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 從主要導覽窗格中，選擇 Custom Domain Names (自訂網域名稱)。

  3. 選擇 Create (建立)。

  4. 在 Domain name (網域名稱) 中，輸入網域名稱。

  5. 對於最低 TLS 版本，請選取一個版本。

  6. 在「端點設定」下，針對 API 端點類型，選擇「邊緣最佳化」。

  7. 針對 ACM 憑證，請選擇 ACM 憑證。

  8. 選擇 Create domain name (建立網域名稱)。

REST API

  1. 呼叫 domainname:create，並指定 AWS Certificate Manager中所存放憑證的自訂網域名稱和 ARN。

    成功的 API 呼叫會傳回回201 Created應，其中包含憑證 ARN 以及其承載中相關聯的 CloudFront 散發名稱。

  2. 請注意輸出中顯示的 CloudFront 分發網域名稱。在後續步驟中，您需要它來設定自訂網域之 DNS 中的 CNAME 值或 A 記錄別名目標。

如需此 REST API 呼叫的程式碼範例，請參閱 domainname:create。

邊緣最佳化的自訂網域名稱大約需要 40 分鐘才能準備就緒，但主控台會立即以的形式顯示相關聯的 CloudFront 散發網域名稱distribution-id.cloudfront.net，以及憑證 ARN。同時，您可以繼續執行下一個步驟，並設定 DNS 記錄別名，以將自訂網域名稱對應至相關聯的 CloudFront散發網域名稱。

為邊緣最佳化的自訂網域名稱建立 DNS 記錄

在您起始建立邊緣最佳化自訂網域名稱之後，請設定 DNS 記錄別名。

我們建議您使用 Route 53 為自訂網域名稱建立 A 記錄別名，並將 CloudFront發佈網域名稱指定為別名目標。這表示 Route 53 可以路由自訂網域名稱，即使是 Zone Apex 也是一樣。如需詳細資訊，請參閱《Amazon Route 53 開發人員指南》中的在別名與非別名資源記錄集之間選擇。

您可以改為將自訂網域新增至託管區域，做為 CNAME 資源記錄集。CNAME 記錄名稱指定您先前在 Domain Name (網域名稱) 中輸入的自訂網域名稱 (例如，api.example.com)。CNAME 記錄值會指定 CloudFront 散發的網域名稱。

不過，如果您的自訂網域是 Zone Apex (即 example.com，而不是 api.example.com)，則無法使用 CNAME 記錄。Zone Apex 通常也稱為您組織的根網域。針對 Zone Apex，您需要使用 A 記錄別名，但前提是 DNS 提供者予以支援。

有關 Amazon Route 53 的指示，請參閱《Amazon Route 53 開發人員指南》中的使用您的網域名稱將流量路由到 Amazon API Gateway API。

記錄自定義域名創建 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

使用自訂網域名稱作為其主機名稱來設定 API 的基本路徑對應

您可以使用基本路徑對應來使用單一自訂網域名稱做為多個 API 的主機名稱。這可透過自訂網域名稱和關聯的基本路徑的組合來存取 API。

例如，如果在 API Gateway 中，您建立了一個名為的 API PetStore 和另一個名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 對應，以將自訂網域名稱的路徑對應至 API 階段。

AWS Management Console

  1. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  2. 從 API Gateway 主控台主要導覽窗格中，選擇 Custom Domain Names (自訂網域名稱)。

  3. 選擇自訂網域名稱。

  4. 選擇 Configure API mappings (設定 API 對應)。

  5. 選擇 Add new mapping (新增對應)。

  6. 指定對應的 API、Stage (階段) 及 Path (路徑) (選擇性)。

  7. 選擇 Save (儲存)。

REST API

在特定自訂網域名稱上呼叫 basepathmapping:create，並在請求承載中指定 basePath、restApiId 和部署 stage 屬性。

成功 API 呼叫會傳回 201 Created 回應。

如需 REST API 呼叫的程式碼範例，請參閱 basepathmapping:create。

輪換匯入至 ACM 的憑證

ACM 會自動處理它所發出之憑證的續約。您不需要為自訂網域名稱輪換任何 ACM 頒發的憑證。 CloudFront 代表您處理它。

不過，如果您將憑證匯入至 ACM，並將它用於自訂網域名稱，則您必須在憑證過期之前輪換憑證。這包含匯入網域名稱的新第三方憑證，並將現有憑證輪換為新的憑證。新匯入的憑證過期時，您需要重複進行此程序。或者，您可以請求 ACM 發出網域名稱的新憑證，並將現有憑證輪換為新的 ACM 發出憑證。之後，您可以離開 ACM 並 CloudFront 自動為您處理憑證輪換。若要建立或匯入新的 ACM 憑證，請遵循中若要建立或匯入 SSL/TLS 憑證至 ACM的步驟。

下列程序說明如何輪替網域名稱的憑證。

注意

輪換匯入 ACM 的憑證大約需要 40 分鐘。

AWS Management Console

  1. 在 ACM 中請求或匯入憑證。

  2. 在以下網址登入 API Gateway 主控台：https://console.aws.amazon.com/apigateway。

  3. 從 API Gateway 主控台主要導覽窗格中，選擇 Custom Domain Names (自訂網域名稱)。

  4. 選擇自訂網域名稱。

  5. 選擇 Edit (編輯)。

  6. 從 ACM Certificate (ACM 憑證) 下拉式清單中，選擇所要的憑證。

  7. 選擇 Save (儲存)，開始輪換自訂網域名稱的憑證。

  8. 輪換完成之後，您可以選擇 ACM Certificate (ACM 憑證) 旁邊的雙向箭頭圖示來復原為原始憑證。

REST API

呼叫 domainname:update 動作，並指定所指定網域名稱之新 ACM 憑證的 ARN。

呼叫具有自訂網域名稱的 API

呼叫具有自訂網域名稱的 API 與呼叫具有其預設網域名稱的 API 相同，但前提是使用正確的 URL。

下列範例會比較和對比所指定區域 (udxjef) 中兩個 API (qf3duz 和 us-east-1) 以及所指定自訂網域名稱 (api.example.com) 的一組預設 URL 和對應自訂 URL。

具有預設和自訂網域名稱之 API 的根 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 Gateway 使用伺服器名稱指示 (SNI) 來支援 API 的自訂網域名稱。您可以使用支援 SNI 的瀏覽器或用戶端程式庫，以使用自訂網域名稱來呼叫 API。

API Gateway 會 CloudFront 在發行版上強制執行 SNI。如需如何 CloudFront 使用自訂網域名稱的相關資訊，請參閱 Amazon CloudFront 自訂 SSL。