設定 Azure API 管理執行個體的自訂網域名稱

適用於：所有 API 管理層級

當您在 Azure 雲端中建立 Azure API 管理服務執行個體時，Azure 會為其指派 azure-api.net 子網域 (例如 apim-service-name.azure-api.net)。 您也可以使用自己的自訂網域名稱來公開 API 管理端點，例如 contoso.com。 本文說明如何將現有的自訂 DNS 名稱對應至 Azure API 管理執行個體所公開的端點。

重要

API 管理只接受具有符合 主機標頭 值的要求：

• 閘道的預設網域名稱
• 閘道已設定的任何自訂網域名稱

注意

目前工作區閘道不支援自訂的網域名稱。

重要

API 管理服務基礎結構的變更（例如設定自定義網域、新增 CA 憑證、調整、虛擬網路設定、可用性區域變更和區域新增專案）可能需要 15 分鐘或更長的時間才能完成，視服務層級和部署大小而定。 預期具有較大縮放單位或多重區域配置的實例需要較長的時間。 系統會仔細執行 API 管理的輪流變更，以保留容量和可用性。

當服務正在更新時，無法進行其他服務基礎結構變更。 不過，您可以設定 API、產品、原則和用戶設定。 服務 不會 經歷閘道停機，API 管理 會繼續 服務 API 要求，而不會中斷（開發人員層除外）。

必要條件

• API 管理執行個體。 如需詳細資訊，請參閱 建立 Azure API 管理實例。

• 您或您的組織所擁有的自訂網域名稱。 本文未提供如何取得自訂網域名稱的指示。

• (選用) 含有公開和私密金鑰的有效憑證 (.PFX)。 主體或主體別名 (SAN) 必須符合網域名稱 (這可讓 API 管理執行個體安全地透過 TLS 公開 URL)。

  請參閱 網域憑證選項。

• 在 DNS 伺服器上代管的 DNS 記錄，以將自訂網域名稱對應至 API 管理執行個體的預設網域名稱。 本主題未提供如何代管 DNS 記錄的指示。

  如需必要記錄的詳細資訊，請參閱本文稍後的 DNS 設定。

自訂網域的端點

您可以對數個 API 管理端點指派自訂網域名稱。 目前有下列端點可用：

端點	預設
閘道	預設值是：<apim-service-name>.azure-api.net。 閘道是使用層中唯一可用於設定的端點。 新增自訂閘道網域之後，預設閘道端點設定仍可供使用。
開發人員平台（除消耗階層以外的所有階層）	預設值是：<apim-service-name>.developer.azure-api.net
管理 （僅限傳統層）	預設值是：<apim-service-name>.management.azure-api.net
自行托管閘道器配置 API （v2）	預設值是：<apim-service-name>.configuration.azure-api.net
SCM （僅限傳統層）	預設值是：<apim-service-name>.scm.azure-api.net

考量

• 您可以更新服務層級中支援的任何端點。 一般而言，客戶會更新 閘道 （此 URL 是用來呼叫透過 API 管理公開的 API）和 開發人員入口網站（開發人員入口網站 URL）。
• 在您設定自定義閘道功能變數名稱且無法刪除之後，預設 閘道 端點仍可供使用。 對於您以自定義功能變數名稱設定的其他 API 管理端點（例如 開發人員入口網站），預設端點已無法使用。
• 只有 API 管理實例擁有者可以在內部使用 管理和SCM 端點。 這些端點較不常指派自訂網域名稱。
• 進階和開發人員層支援設定閘道端點的多個主機名。
• 除了使用層以外，所有層都支援萬用字元網域名稱，例如 *.contoso.com。 對 api.contoso.com 的要求，特定子網域憑證 (例如，api.contoso.com) 的優先順序高於萬用字元憑證 (*.contoso.com)。
• 在為 開發人員入口網站設定自訂網域時，您可以為新的網域名稱啟用CORS。 這是為了讓開發人員入口網站的訪客能夠在 API 參考頁面中使用互動式控制台。

網域憑證選項

API 管理支援自訂 TLS 憑證或從 Azure Key Vault 匯入的憑證。 您也可以啟用免費的受控憑證。

警告

如果您需要憑證關聯，請使用自訂網域名稱和自訂或 Key Vault 憑證，而不是預設憑證或免費的受控憑證。 建議您不要對未管理的憑證採取硬式相依性。

自訂

如果您已經有協力廠商提供者的私人憑證，您可以將該憑證上傳至 API 管理執行個體。 憑證必須符合下列需求 (如果您啟用由 API 管理所管理的免費憑證，則該憑證已符合這些需求)：

• 匯出為 PFX 檔案 (以三重 DES 加密並選擇性地使用密碼保護)。
• 包含長度至少 2048 位元的私密金鑰
• 包含憑證鏈結中的所有中繼憑證和根憑證。

金鑰保管庫

我們建議使用 Azure Key Vault 來管理您的憑證 ，並將其設定為 autorenew。

如果您使用 Azure Key Vault 來管理自定義網域 TLS 憑證，請確定憑證會以憑證的形式插入 Key Vault 中，而不是秘密。

警告

在 API 管理中使用金鑰保存庫憑證時，請小心不要刪除用來存取金鑰保存庫的憑證、金鑰保存庫，或受控識別。

API 管理必須具備清單，並在含有憑證的 Azure Key Vault 上取得祕密權限，才能擷取 TLS/SSL 憑證。

• 使用 Azure 入口網站匯入憑證時，所有必要設定步驟都會自動完成。

• 當您使用命令列工具或管理 API 時，則必須透過兩個步驟手動授與這些權限：

  1. 在 API 管理實例的 [受控識別 ] 頁面上，啟用系統指派或使用者指派的 受控識別。 記下該頁面上的主體識別碼。
  2. 為受控識別指派權限來存取金鑰保存庫。 使用下一節中的步驟。

  設定金鑰保存庫存取權

  1. 在入口平台中，前往您的金鑰保存庫。
  2. 在左側功能表中，選取 [ 存取設定]。 請注意已配置的許可權模型。
  3. 根據許可權模型，為 API 管理受控身分識別設定 金鑰庫存取原則 或 Azure RBAC 存取。

  若要新增金鑰保存庫存取原則：

  1. 在左側功能表中，選取 [存取原則]。
  2. 在 [ 存取原則] 頁面上，選取 [+ 建立]。
  3. 在 [ 許可權] 索引標籤的 [ 秘密許可權] 底下，選取 [取得 和 列表]，然後選取 [ 下一步]。
  4. 在 [ 主體] 索引標籤上，選取 [ 主體]，搜尋受控識別的資源名稱，然後選取 [ 下一步]。 如果您使用系統指派的身分識別，則主體是您 API 管理執行個體的名稱。
  5. 再次選取 [下一步]。 在 [ 檢閱 + 建立] 索引標籤上，選取 [建立]。

  若要設定 Azure RBAC 存取：

  1. 在左側功能表中，選取 [存取控制 (IAM)]。
  2. 在 [存取控制 (IAM)] 頁面上，選取 [新增角色指派]。
  3. 在 [角色] 索引標籤上，選取 [Key Vault 憑證使用者]。
  4. 在 [成員] 索引標籤上，選取 [受控識別]>[+ 選取成員]。
  5. 在 [ 選取受控識別 ] 視窗中，選取系統指派的受控識別或與您 API 管理實例相關聯的使用者指派受控識別，然後按兩下 [ 選取]。
  6. 選擇 檢閱 + 指派。

如果憑證設定為 autorenew，且您的 API 管理層具有 SLA (亦即除了開發人員層以外的所有層均有)，則 API 管理會自動挑選最新版本，而不會造成服務停機。

如需詳細資訊，請參閱 在 Azure API 管理中使用受控識別。

管理

如果您不想購買和管理自己的憑證，API 管理可為您的網域提供免費的受控 TLS 憑證。 憑證會自動更新。

注意

免費的受控 TLS 憑證處於預覽狀態。 目前，它在 v2 服務層中無法使用。

限制

• 目前只能搭配 API 管理服務的閘道端點使用
• 不支援用於自我裝載閘道
• 下列 Azure 區域不支援：法國南部和南非西部
• 目前僅適用於 Azure 雲端
• 不支援根網域名稱 (例如，contoso.com)。 需要完整名稱，例如 api.contoso.com。
• 僅支援公用網域名稱
• 只能在更新現有的 API 管理執行個體時設定，而無法在建立執行個體時設定

設定自訂網域名稱 - 入口網站

根據您想要使用的 網域憑證 選擇步驟。

自訂

1. 在 Azure 入口網站中瀏覽至您的 API 管理實例。
2. 從左側導覽中，選取 [自訂網域]。
3. 選取 [+新增]，或選取您要更新的現有 端點 。
4. 在右側視窗中，選取自訂網域端點的 [類型]。
5. 在 [主機名稱] 欄位中，指定您想要使用的名稱。 例如： api.contoso.com 。
6. 在 [憑證] 下方，選取 [自訂]
7. 選取 [憑證檔案] 以選取並上傳憑證。
8. 上傳有效的 PFX 檔案並提供其 密碼，如果憑證受到密碼保護。
9. 設定閘道端點時，請視需要選取或取消選取 其他選項，包括 交涉客戶端憑證 或 預設 SSL 系結。
10. 選取 [新增]，或選取現有端點的 [更新]。
11. 選取 [儲存]。

金鑰保管庫

1. 在 Azure 入口網站中瀏覽至您的 API 管理實例。
2. 從左側導覽中，選取 [自訂網域]。
3. 選取 [+新增]，或選取您要更新的現有 端點 。
4. 在右側視窗中，選取自訂網域端點的 [類型]。
5. 在 [主機名稱] 欄位中，指定您想要使用的名稱。 例如： api.contoso.com 。
6. 在 [憑證] 下方，依序選取 [金鑰保存庫] 和 [選取]。
   1. 從下拉式清單中選取 [訂閱]。
   2. 從下拉式清單中選取 [金鑰保存庫]。
   3. 載入憑證之後，請從下拉式清單中選取 [憑證]。 按一下 [選取]。
   4. 在 [用戶端身分識別] 中，選取系統指派的身分識別或實例中啟用的使用者指派 受控識別 ，以存取密鑰保存庫。
7. 設定閘道端點時，請視需要選取或取消選取 其他選項，包括 交涉客戶端憑證 或 預設 SSL 系結。
8. 選取 [新增]，或選取現有端點的 [更新]。
9. 選取 [儲存]。

管理

1. 在 Azure 入口網站中瀏覽至您的 API 管理實例。
2. 從左側導覽中，選取 [自訂網域]。
3. 選取 [+新增]，或選取您要更新的現有 端點 。
4. 在右側視窗中，選取自訂網域端點的 [類型]。
5. 在 [主機名稱] 欄位中，指定您想要使用的名稱。 例如： api.contoso.com 。
6. 在 [憑證] 下方，選取 [受控] 以啟用由 API 管理所管理的免費憑證。 受控憑證目前僅供閘道端點使用，且為預覽狀態。
7. 複製下列值，並使用它們來 設定 DNS：
   • TXT 記錄
   • CNAME 記錄
8. 設定閘道端點時，請視需要選取或取消選取 其他選項，包括 交涉客戶端憑證 或 預設 SSL 系結。
9. 選取 [新增]，或選取現有端點的 [更新]。
10. 選取 [儲存]。

DNS 組態

• 設定自訂網域的 CNAME 記錄。
• 使用 API 管理的免費受控憑證時，亦請設定 TXT 記錄來建立網域的擁有權。

注意

免費憑證由 DigiCert 所發行。 對於某些網域，您必須建立一個含有指定值的 CAA 網域記錄，以明確允許 DigiCert 作為憑證簽發者：0 issue digicert.com。

CNAME 記錄

設定 CNAME 記錄，以從您的自訂網域名稱 (例如 api.contoso.com) 指向 API 管理服務主機名稱 (例如 <apim-service-name>.azure-api.net)。 為免 IP 位址變更，CNAME 記錄比 A 記錄更穩定。 如需詳細資訊，請參閱 Azure API 管理的 IP 位址 和 API 管理常見問題。

注意

使用 CNAME 記錄時，某些網域註冊機構只允許您對應子網域 (如 www.contoso.com)，而不是根名稱 (如 contoso.com)。 如需 CNAME 記錄的詳細資訊，請參閱註冊機構或 IETF 功能變數名稱 - 實作和規格所提供的檔。

警告

當您使用免費的受控憑證，並使用您的 DNS 提供者設定 CNAME 記錄時，請確定它會解析為預設的 APIM 服務主機名稱 (<apim-service-name>.azure-api.net)。 目前，如果 CNAME 記錄不會解析為預設的 APIM 主機名稱，APIM 就不會自動更新憑證。 例如，如果您使用免費受控憑證，並使用 Cloudflare 作為 DNS 提供者，請確定未在 CNAME 記錄上啟用 DNS Proxy。

TXT 記錄

啟用 API 管理的免費受控憑證時，亦請在 DNS 區域中設定 TXT 記錄，以建立網域名稱的擁有權。

• 記錄名稱是您的自訂網域名稱，前面加上 apimuid。 範例：apimuid.api.contoso.com。
• 此值是您 API 管理執行個體所提供的網域擁有權識別碼。

當您使用入口網站來設定自訂網域的免費受控憑證時，系統會自動顯示必要 TXT 記錄的名稱和值。

您也可以呼叫 取得網域擁有權標識碼 REST API 來取得網域擁有權識別碼 。

API 管理 Proxy 伺服器如何在 TLS 交握中使用 SSL 憑證進行回應

設定閘道端點的自訂網域時，您可以設定其他屬性，以根據用戶端要求來判斷 API 管理如何使用伺服器憑證進行回應。

具有伺服器名稱指示 (SNI) 標頭的用戶端呼叫

如果您已針對閘道端點設定一或多個自訂網域，則 API 管理可以透過下列其中一個項目回應 HTTPS 要求：

• 自訂網域 (例如：contoso.com)
• 預設網域 (例如：apim-service-name.azure-api.net)。

根據 SNI 標頭中的資訊，API 管理會以適當的伺服器憑證進行回應。

不具有 SNI 標頭的用戶端呼叫

如果您使用未傳送 SNI 標頭的用戶端，API 管理會根據下列邏輯建立回應：

• 如果服務只針對網關設定了一個自定義網域，則預設憑證是發給網關自定義網域的憑證。

• 如果服務已設定閘道的多個自定義網域（在 開發人員 和 進階層 中支援），您可以將 defaultSslBinding 屬性設定為 true （"defaultSslBinding":"true"） 來指定預設憑證。 在入口網站中，選取 [預設 SSL 繫結] 核取方塊。

  如果您未設定此屬性，則預設憑證就是發給預設閘道網域 (裝載於 *.azure-api.net) 的憑證。

有大型承載之 PUT/POST 要求的支援

在 HTTPS 中使用用戶端憑證時，API 管理 Proxy 伺服器可支援具有大型承載 (>40 KB) 的要求。 若要防止伺服器的要求凍結，您可以將 Gateway 主機名上的 negotiateClientCertificate 屬性設定為 true （"negotiateClientCertificate": "true"）。 在入口網站中，選取 [交涉用戶端憑證] 核取方塊。

如果將屬性設定為 true，系統就會在任何 HTTP 要求交換之前，於 SSL/TLS 連線時間要求用戶端憑證。 由於設定會在 閘道主機名 層級套用，因此所有連線要求都會要求客戶端憑證。 您可以解決這項限制，並針對網關設定最多 20 個自定義網域（僅限 進階層 支援）。

標準 v2 定價層中自訂網域名稱的限制

目前，在標準 v2 層中，API 管理需要可公開解析的 DNS 名稱，以允許流量流向網關端點。 如果您為閘道端點設定自訂網域名稱，該網域名稱必須能被公開解析，不能受限於私人 DNS 區域。

在限制閘道公用存取權並設定私人功能變數名稱的情況下，您可以設定應用程式閘道以接收私人功能變數名稱上的流量，並將其路由傳送至 API 管理實例的閘道端點。 如需範例架構，請參閱此 GitHub 存放庫。

疑難解答：來自 Azure Key Vault 的主機名憑證輪替失敗

由於設定變更或連線問題，您的 API 管理實例在憑證更新或輪替之後，可能無法從 Azure Key Vault 擷取主機名憑證。 發生這種情況時，您的 API 管理實例會繼續使用快取的憑證，直到它收到更新的憑證為止。 如果快取的憑證過期，將會封鎖閘道的運行時間流量。 使用過期快取憑證時，任何使用主機名憑證設定的應用程式網關等上游服務，也可以封鎖網關的運行時間流量。

若要減輕此問題，請確認密鑰保存庫存在，且憑證會儲存在密鑰保存庫中。 如果您的 API 管理實例部署在虛擬網路中，請確認 AzureKeyVault 服務標籤的輸出連線能力。 檢查用來存取金鑰保存庫的受控識別是否存在。 確認受控識別存取金鑰保存庫的許可權。 如需詳細的設定步驟，請參閱本文稍早 的設定自定義功能變數名稱 - Key Vault。 還原組態之後，主機名憑證會在 4 小時內在 API 管理中重新整理。

相關內容

升級和調整您的服務