適用於:所有 API 管理層級
當你在 Azure 雲端建立 Azure API 管理 服務實例時,Azure 會指派一個 azure-api.net 子網域(例如 apim-service-name.azure-api.net)。 您也可以使用自己的自訂網域名稱來公開 API 管理端點,例如 contoso.com。 本文說明如何將現有的自訂 DNS 名稱對應至 Azure API 管理執行個體所公開的端點。
Note
目前工作區閘道不支援自訂的網域名稱。
Important
API 管理服務基礎結構的變更(例如設定自定義網域、新增 CA 憑證、調整、虛擬網路設定、可用性區域變更和區域新增專案)可能需要 15 分鐘或更長的時間才能完成,視服務層級和部署大小而定。 對於擁有更多規模單元或多區域配置(多地點閘道器)的實例,預期時間會更長。 系統會仔細執行 API 管理的輪流變更,以保留容量和可用性。
當服務正在更新時,無法進行其他服務基礎結構變更。 不過,您可以設定 API、產品、原則和用戶設定。 服務 不會 經歷閘道停機,API 管理 會繼續 服務 API 要求,而不會中斷(開發人員層除外)。
Prerequisites
API 管理執行個體。 欲了解更多資訊,請參見 Create a Azure API 管理 instance。
您或您的組織所擁有的自訂網域名稱。 本文未提供如何取得自訂網域名稱的指示。
(選用) 含有公開和私密金鑰的有效憑證 (.PFX)。 主體或主體別名 (SAN) 必須符合網域名稱 (這可讓 API 管理執行個體安全地透過 TLS 公開 URL)。
請參閱 網域憑證選項。
在 DNS 伺服器上代管的 DNS 記錄,以將自訂網域名稱對應至 API 管理執行個體的預設網域名稱。 本主題未提供如何代管 DNS 記錄的指示。
如需必要記錄的詳細資訊,請參閱本文稍後的 DNS 設定。
自訂網域的端點
您可以對數個 API 管理端點指派自訂網域名稱。 目前有下列端點可用:
| Endpoint | Default |
|---|---|
| Gateway | 預設值是:<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 |
Considerations
- 您可以更新服務層級中支援的任何端點。 一般而言,客戶會更新 閘道 (此 URL 是用來呼叫透過 API 管理公開的 API)和 開發人員入口網站(開發人員入口網站 URL)。
- 在您設定自定義閘道功能變數名稱且無法刪除之後,預設 閘道 端點仍可供使用。 對於您以自定義功能變數名稱設定的其他 API 管理端點(例如 開發人員入口網站),預設端點已無法使用。
- 只有 API 管理實例擁有者可以在內部使用 管理和SCM 端點。 這些端點較不常指派自訂網域名稱。
- 進階和開發人員層支援設定閘道端點的多個主機名。
- 除了使用層以外,所有層都支援萬用字元網域名稱,例如
*.contoso.com。 對 api.contoso.com 的要求,特定子網域憑證 (例如,api.contoso.com) 的優先順序高於萬用字元憑證 (*.contoso.com)。 - 在為 開發者入口網站設定自訂網域時,你可以啟用新網域名稱的 CORS 。 這是為了讓開發人員入口網站的訪客能夠在 API 參考頁面中使用互動式控制台。
網域憑證選項
API Management 支援自訂的 TLS 憑證或從 Azure Key Vault 匯入的憑證。 您也可以啟用免費的受控憑證。
Warning
如果您需要憑證關聯,請使用自訂網域名稱和自訂或 金鑰保存庫 憑證,而不是預設憑證或免費的受控憑證。 建議您不要對未管理的憑證採取硬式相依性。
如果您已經有協力廠商提供者的私人憑證,您可以將該憑證上傳至 API 管理執行個體。 憑證必須符合下列需求 (如果您啟用由 API 管理所管理的免費憑證,則該憑證已符合這些需求):
- 匯出為 PFX 檔案 (以三重 DES 加密並選擇性地使用密碼保護)。
- 包含長度至少為 2048 位元的私密金鑰
- 包含憑證鏈結中的所有中繼憑證和根憑證。
設定自訂網域名稱 - 入口網站
根據您想要使用的 網域憑證 選擇步驟。
- 請在 Azure 入口網站 中導向你的 API Management 實例。
- 從左側導覽中,選取 [自訂網域]。
- 選取 [+新增],或選取您要更新的現有 端點 。
- 在右側視窗中,選取自訂網域端點的 [類型]。
- 在 [主機名稱] 欄位中,指定您想要使用的名稱。 例如:
api.contoso.com。 - 在 [憑證] 下方,選取 [自訂]
- 選取 [憑證檔案] 以選取並上傳憑證。
- 上傳有效的 PFX 檔案並提供其 密碼,如果憑證受到密碼保護。
- 設定閘道端點時,請視需要選取或取消選取 其他選項,包括 交涉客戶端憑證 或 預設 SSL 系結。
- 選取 [新增],或選取現有端點的 [更新]。
- 選取 [儲存]。
DNS 組態
設定你的 DNS 供應商,讓你的自訂網域名稱對應到 API 管理實例的預設網域名稱。
CNAME 記錄
設定 CNAME 記錄,以從您的自訂網域名稱 (例如 api.contoso.com) 指向 API 管理服務主機名稱 (例如 yourapim-service-name.azure-api.net)。 CNAME 紀錄比 A 記錄更穩定,以防 IP 位址變更。 欲了解更多資訊,請參閱 Azure API 管理<>
Note
使用 CNAME 記錄時,某些網域註冊機構只允許您對應子網域 (如 www.contoso.com),而不是根名稱 (如 contoso.com)。 如需 CNAME 記錄的詳細資訊,請參閱註冊機構或 IETF 功能變數名稱 - 實作和規格所提供的檔。
由 Azure Key Vault 支援的憑證的同步與故障排除
當你使用 Azure Key Vault 支援的憑證來設定自訂網域時,API Management 會提供控制與診斷功能,幫助你保持憑證同步並迅速解決存取問題。
例如,因為設定變更或連線問題,您的 API 管理實例可能無法在憑證更新或旋轉後,從 Azure Key Vault 取得主機名稱憑證。 發生這種情況時,您的 API 管理實例會繼續使用快取的憑證,直到它收到更新的憑證為止。 如果快取的憑證過期,則傳送至閘道的執行階段流量將會被封鎖。 當使用過期的快取憑證時,任何使用主機名稱憑證設定的上游服務 (例如應用程式閘道) 也可能會封鎖傳送至閘道的執行階段流量。
請使用以下控制與診斷工具,保持憑證同步,並預防或減少停機時間。
同步憑證
在指令列選擇 「同步憑證 」,當憑證的拇指紋變更時,手動開始憑證同步。 這個選項可以避免等待通常每 3-4 小時執行一次的自動同步作業。
查看同步日誌
在指令列選擇 「檢視同步日誌」 ,以開啟一個面板,顯示憑證同步失敗時的詳細根因資訊。 這些日誌能幫助你更快診斷並解決同步問題。
恢復對金鑰保險庫的存取權限
API Management 在偵測到你的 API Management 實例與自訂網域所用金鑰庫之間的存取問題時,會主動顯示警告。 這些存取問題常導致憑證同步失敗。
如果出現警告,請選擇 還原 ,根據你的金鑰庫授權模型自動修正存取權。 根據不同模型,API 管理會採取以下其中一種行動來恢復存取權限:
- 為 Azure 基於 RBAC 的金鑰保存庫指派 金鑰保存庫 Secrets User 角色。
- 授予 GET 權限以存取基於存取政策的金鑰庫。
來自 Azure Key Vault 的失敗憑證輪換的額外故障排除建議
確認用來存取金鑰保險庫的管理身份是否存在。
如果您的 API 管理實例部署在虛擬網路中,請確認 AzureKeyVault 服務標籤的輸出連線能力。
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 與高級版 v2 層級中,API 管理要求一個公開可解析的 DNS 名稱,才能允許流量流向閘道端點。 如果您為閘道端點設定自訂網域名稱,該網域名稱必須能被公開解析,不能受限於私人 DNS 區域。
在限制閘道公用存取權並設定私人功能變數名稱的情況下,您可以設定應用程式閘道以接收私人功能變數名稱上的流量,並將其路由傳送至 API 管理實例的閘道端點。 範例架構請參考此 GitHub repo。
相關內容
- 升級和調整您的服務
- 在 Azure API 管理 中使用受管理身份。