Azure Key Vault 使用已設定版本的 API。 如果你的應用程式、腳本或基礎架構範本呼叫舊版 API，可能會錯過新功能、使用後續版本改變的行為，或依賴不再推薦的版本。 本文說明如何決定你使用的 API 版本，以及如何遷移到目前且支援的版本。
Important
所有 金鑰保存庫 控制平面在2026-02-01之前的 API 版本，將於 2027 年 2 月 27 日淘汰。 過了那個日期，你的金鑰庫仍然存在，但你只能用控制平面 API 版本 2026-02-01 或更新版本來管理它們。 此日期不設例外，也不予延長。 這次退休不會影響 資料平面 API（用於處理金鑰、秘密和憑證的 API）。 詳情請參閱 金鑰保存庫 中預設存取控制模型的 Azure RBAC 計畫。
Azure Key Vault 有兩個獨立的 API 表面，每個都有自己的版本：
| API 介面 | 它能做到什麼 | 版本架構 | 端點範例 |
|---|---|---|---|
| 控制平面 （管理） | 金鑰保險庫資源本身：建立、更新、刪除保險庫，並設定屬性如 SKU、網路規則和存取控制。 | 依日期（{YYYY}-{MM}-{DD}） |
https://management.azure.com |
| 資料平面 | 保險庫內的物件：金鑰、秘密與憑證，以及密碼學操作。 | 依日期（{YYYY}-{MM}-{DD}） |
https://<vault-name>.vault.azure.net |
這兩種表面的版本管理和生命週期做法不同。 更新其中一個，不會更新另一個。 如果您的工作負載同時使用兩者，請檢閱兩者。
控制平面的 API 版本可能會如本文前面所述遭到淘汰。
預覽資料平面的 API 版本可能會被棄用，所以除非你接受這個生命週期，否則不要在生產環境中使用預覽。 有關支援的資料平面 API 版本，請參閱 Azure Key Vault REST API 參考。
本文重點在於識別與更新 API 版本。 更新控制平面 API 版本不需要你將現有的金鑰庫從存取政策遷移到 Azure RBAC。 如果你想遷移存取控制，請參考從存取政策遷移到 Azure RBAC。 如需了解在 API 版本 2026-02-01 及更新版本中，針對新金鑰保存庫導入的 Azure RBAC 預設行為，請參閱 規劃 Azure RBAC 作為 金鑰保存庫 中的預設存取控制模型。
為什麼要換成目前的 API 版本
- 請使用支援的功能。 較新的 API 版本可以新增功能、修正行為，或支援新的服務功能。
- 保持生產工作負載穩定。 使用目前穩定的 API 版本來處理生產工作負載。 預覽版 API 版本主要用於評估和早期測試，而 Azure 支援 SLA 可能無法涵蓋這些。 預覽版本可能會被棄用。
- 保持工具和函式庫相容。 Azure CLI、Azure PowerShell、SDK、模板和 portal 可以使用不同的 API 版本。 更新一個客戶端的版本並不會更新其他客戶端。
關於目前控制平面版本，請參見 支援的控制平面 API 版本。 有關支援的資料平面版本，請參閱 Azure Key Vault REST API 參考資料。
確定你使用的 API 版本
你根據呼叫 金鑰保存庫 的方式，指定 API 版本的方式會有所不同。 檢查你工作負載使用的每個表面。
控制平面（管理）
-
REST API：版本是對
https://management.azure.com發出要求時使用的查詢字串參數api-version，例如?api-version=<control-plane-version>。 -
ARM、Bicep 和 Terraform 範本：版本位於每個
Microsoft.KeyVault/vaults資源的apiVersion屬性中。 在 Bicep 中，它就是資源類型宣告的一部分，例如resource kv 'Microsoft.KeyVault/vaults@2026-02-01'。 -
控制平面管理 SDK：套件版本可以決定 SDK 支援哪些 API 版本，但僅靠套件版本並不一定能標示請求所使用的 API 版本。 檢查套件發布說明和 API 參考（例如 for
Azure.ResourceManager.KeyVault或azure-mgmt-keyvault），並與你專案相依清單中的套件版本做比較。 關於語言的 API 參考，請參見 Azure Key Vault 客戶端函式庫。 -
Azure CLI 與 Azure PowerShell：你的 Azure CLI 或
Az模組版本決定 API 版本。 使用 az version 或 Get-InstalledModule -Name Az 檢查已安裝的版本。 - Azure 入口網站：入口網站會選擇控制平面的 API 版本來處理請求。 你無法直接設定那個版本。 入口網站可以使用與範本、腳本或 SDK 不同的 API 版本，所以不要用入口網站的行為來判斷自動化使用的版本。
- Azure Cloud Shell： Cloud Shell 使用當前 Azure CLI 同 Azure PowerShell 版本。 如果你在 Cloud Shell 執行腳本，請確保它們與目前支援的控制平面 API 版本相容。
資料平面
-
REST API：版本是對您的保存庫端點提出要求時的
api-version查詢字串參數，例如GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>。 -
資料平面 SDK：套件版本可以決定 SDK 支援哪些 API 版本，但僅靠套件版本並不一定能標示請求所使用的 API 版本。 檢查套件發佈說明和 API 參考（例如，為
Azure.Security.KeyVault.Secrets、Azure.Security.KeyVault.Keys、Azure.Security.KeyVault.Certificates或 ），並與你專案相依清單中的套件版本做比較。 關於語言的 API 參考，請參見 Azure Key Vault 客戶端函式庫。
更新你的 API 版本
更新控制平面的 API 版本
更新範本和 REST 呼叫中的 API 版本。 在所有
apiVersion定義和管理要求中，將Microsoft.KeyVault/vaults（ARM、Bicep、Terraform）或api-version查詢字串參數（REST）設為目前支援的控制平面版本。更新你的控制平面管理 SDK。 請查看支援你所選控制平面 API 版本的套件版本之發行說明與 API 參考文件。 關於依語言及支援目前 金鑰保存庫 控制平面版本的套件版本的 API 參考，請參閱 Azure Key Vault 用戶端函式庫與控制平面 SDK 版本。
Note
更新控制平面管理 SDK 並不會更新資料平面 SDK。 如果你的應用程式同時使用兩個 API 表面，請分別更新每個 SDK。
更新 Azure CLI 和 Azure PowerShell。 較新的工具版本會呼叫較新的 API 版本。
將 Azure CLI 更新為最新版本。 欲了解更多資訊，請參閱 如何更新 Azure CLI。
- 部署前檢視行為變更。 部署前請閱讀 API 版本的變更日誌和規範。 API 版本
2026-02-01及以上版本只會變更新金鑰保存庫的預設存取控制模型。 詳情請參閱 金鑰保存庫 中預設存取控制模型的 Azure RBAC 計畫。
更新資料平面的 API 版本
在 REST 呼叫中更新 API 版本。 將查詢字串參數設
api-version為目前支援的資料平面版本，該版本在 Azure Key Vault REST API 參考中列出。更新你的資料平面 SDK。 將
Azure.Security.KeyVault.*套件（或您所用語言的對應套件）升級至目前的穩定版本。 請查看套件發布說明和 API 參考，以判斷套件支援哪些資料平面的 API 版本。 關於依語言分類的 API 參考與套件連結，請參見 Azure Key Vault 用戶端函式庫。
資料平面穩定版 API 版本不受目前控制平面淘汰的影響。 如果您使用預覽版資料平面 API，請檢閱服務公告以及 API 參考文件中關於其生命週期的資訊。
欲了解更多關於呼叫資料平面 REST API 的資訊，請參閱 Authentication， requests， and responses 以及 Azure Key Vault REST API 參考資料。