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、網路規則和存取控制。 | 基於日期的,例如 2026-02-01。 預覽版本會加上 -preview 後綴,例如 2026-03-01-preview。 |
https://management.azure.com |
| 資料層 | 保險庫內的物件:金鑰、秘密與憑證,以及密碼學操作。 | 以日期為基礎的,如 2026-04-01,或數值的,如 7.6。 預覽版本會加上後綴,例如 2026-03-01-preview 或 7.6-preview.2。 |
https://<vault-name>.vault.azure.net |
這兩種表面的版本管理和生命週期做法不同。 更新其中一個,不會更新另一個。 如果您的工作負載同時使用兩者,請檢閱兩者。
由於兩個介面都使用基於日期的版本,僅靠版本字串無法識別是哪個介面。 例如,控制平面和資料平面都有一個 2026-03-01-preview 版本。
控制平面的 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 版本。 通知能觸及比近期遙測所偵測到的資源更廣泛的受眾。
使用 金鑰保存庫 稽核日誌,找出哪些金鑰庫與作業使用了即將退休的 API 版本。 然後找出你的程式碼、範本或工具設定該版本的位置,如在程式碼和工作流程中尋找 API 版本參考,並更新你的 API 版本。
收集 金鑰保存庫 稽核日誌
將你想調查的每個 Key Vault 的稽核日誌傳送到 Log Analytics 工作空間。 有關步驟,請參見啟用 金鑰保存庫 記錄。 若要同時配置多個金鑰保險庫,請參考使用內建 Azure 原則 建立大規模診斷設定。 請使用一個工作區供這些金鑰庫使用,這樣你可以將它們一併查詢。
提早設定記錄。 日誌只包含診斷設定生效後的請求,且較早的請求不會被回填。 建立診斷設定後,資料可能需要長達90分鐘才會出現。 更多資訊請參閱 建立診斷設定後的預期延遲。
稽核事件同時包含控制平面與資料平面操作,但此淘汰僅影響控制平面操作。
Azure 活動日誌不會記錄請求的 API 版本,因此請使用 金鑰保存庫 的稽核日誌來尋找使用退休版本的請求。
要確認紀錄是否已抵達,請在工作區執行以下查詢。 欲了解更多關於執行查詢的資訊,請參閱 Log Analytics 教學。
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50
請檢查 _ResourceId 並 TimeGenerated 確認紀錄是否來自預定的金鑰保險庫。 若要檢查不在最新 50 列中的 Key Vault,請在 order by 之前依 _ResourceId 篩選。
如果缺少資料表或查詢沒有回傳紀錄,請重新檢查工作區、已儲存的診斷設定、來源金鑰保險庫、查詢範圍、時間範圍以及你的權限。 如果你的診斷設定將日誌傳送到資源專屬的資料表,請如下一節末尾所述,改為查詢該 AZKVAuditLogs 資料表。
尋找使用即將退休 API 版本的請求
Important
日誌只包含金鑰保險庫在其診斷設定啟動期間收到的請求,且僅限於你查詢的時間範圍內。 如果你的查詢沒有回傳匹配的請求,並不代表你沒受影響。 例如,日誌不會顯示多年前建立金鑰庫的請求,即使建立這些金鑰庫的範本或腳本仍指定退休版本。 務必檢視你的應用程式程式碼、部署範本、自動化腳本及其他工作流程,尋找即將退休的 API 版本參考。
以下查詢僅透過在請求 URI 中的 Azure Resource Manager 端點過濾,回傳控制平面請求。 資料平面請求會直接送到你的保存庫端點,例如 https://<vault-name>.vault.azure.net。 這些查詢會使用 Azure 公有雲的端點。 對於其他雲端,請用你雲端的端點來替換 https://management.azure.com/ :
| 雲 | Azure Resource Manager 端點 |
|---|---|
| Azure 公用雲端 | https://management.azure.com/ |
| Azure Government | https://management.usgovcloudapi.net/ |
| Azure 由 21Vianet 營運 | https://management.chinacloudapi.cn/ |
其他雲端則使用自己的 Azure Resource Manager 端點。
查詢會在端點進行篩選,因為某些資料平面 API 版本使用與控制平面版本相同的日期格式。 例如,資料平面也有一個 2026-03-01-preview 版本。 關於 金鑰保存庫 記錄的操作名稱,請參閱操作名稱表。
若要列出以早於 2026-02-01 的 API 版本接收控制平面請求的金鑰保存庫,請執行以下查詢。 它會為每個金鑰庫和 API 版本回傳一列,包含請求次數、最近的請求以及所請求的操作。
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc
若要調查個別請求,請使用以下其中一個查詢。
要查找使用特定退休版本(例如 2026-03-01-preview)的請求,請按該版本篩選:
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc
要找到使用任何早 2026-02-01於 的控制平面 API 版本的請求,請篩選排序在 2026-02-01之前的版本:
AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc
本文中的查詢使用AzureDiagnostics該表格,當診斷設定的目標資料表是 Azure 診斷時,該表格會接收 金鑰保存庫 的稽核日誌。 如果目的資料表是 資源專用的,審計日誌會直接送到該 AZKVAuditLogs 資料表。 在這種情況下,請調整本文中的每個查詢,包括集合檢查:替換 AzureDiagnostics 為 AZKVAuditLogs、移除 ResourceProvider 和 Category 篩選條件,並替換 requestUri_s 為 RequestUri。 例如,受影響的金鑰保險庫查詢會變成:
AZKVAuditLogs
| where TimeGenerated >= ago(30d)
| where RequestUri startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc
不要篩選以 Vault 開頭的操作名稱,因為該篩選器可能會排除已記錄的子資源操作。 使用 OperationName 並請求 URI 來了解發生了哪個管理操作。 利用這些日誌中的細節來辨識呼叫者。 接著找出呼叫者設定 API 版本的位置(如下節所述),並依照 「更新你的 API 版本」的說明來更新。
在你的程式碼和工作流程中尋找 API 版本參考
你設定 API 版本的位置取決於你如何呼叫 金鑰保存庫。 檢查你工作負載使用的每種方法,即使你的日誌中沒有顯示該方法的請求。
控制平面(管理)
-
REST API:版本是
api-version請求時https://management.azure.com的查詢字串參數,例如?api-version=<control-plane-version>。 -
ARM 範本與 Bicep 檔案:版本是
apiVersion每個Microsoft.KeyVault/vaults資源的屬性。 在 Bicep 中,它就是資源類型宣告的一部分,例如resource kv 'Microsoft.KeyVault/vaults@2026-02-01'。 子資源如Microsoft.KeyVault/vaults/secrets、Microsoft.KeyVault/vaults/keys、Microsoft.KeyVault/vaults/accessPolicies也是控制平面資源,且各自宣告自己的 API 版本。 更新父保存庫的版本並不會更新其子資源。 -
Terraform:在 AzAPI 提供者中,版本是資源類型的一部分,例如
Microsoft.KeyVault/vaults@2026-02-01。 使用 AzureRM 提供者時,提供者版本決定 API 版本,資源沒有 API 版本設定。 請查看提供者發行說明和資源文件,以確認您的提供者版本使用的 API 版本。 -
控制平面管理 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 版本來處理請求。 你無法直接設定那個版本。 入口網站使用 API 版本
2026-02-01,因此入口網站操作不會使用即將淘汰的版本。 入口網站可以使用與範本、腳本或 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(ARM、Bicep)、版本化資源類型(Terraform AzAPI)或api-version查詢字串參數(REST)設定為目前支援的控制平面版本。 更新所有Microsoft.KeyVault/vaults定義、其子資源及管理請求。 如果你使用 Terraform AzureRM 提供者,請將該提供者更新到使用支援控制平面 API 版本的版本。更新你的控制平面管理 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 參考資料。