Uppdatera den Azure Key Vault API-version som du använder

Azure Key Vault använder versions-API:er. Om dina program, skript eller infrastrukturmallar anropar en äldre API-version kan du missa nyare funktioner, använda beteende som ändrats i en senare version eller vara beroende av en version som inte längre rekommenderas. Den här artikeln beskriver hur du avgör vilken API-version du använder och hur du flyttar till en aktuell version som stöds.

Azure Key Vault har två oberoende API-ytor, var och en med sina egna versioner:

De två ytorna har olika metoder för versionshantering och livscykel. Uppdatering av den ena uppdaterar inte den andra. Granska båda om din arbetsbelastning använder båda.

API-versioner för kontrollplanet kan tas ur bruk, som beskrivits tidigare i den här artikeln.

Api-versioner för förhandsversioner av dataplanet kan vara inaktuella, så använd inte förhandsversioner i produktion om du inte accepterar den livscykeln. Information om API-versioner för dataplanet som stöds finns i Azure Key Vault REST API-referensen.

Den här artikeln fokuserar på att identifiera och uppdatera API-versioner. Om du uppdaterar en API-version för kontrollplanet behöver du inte migrera ett befintligt nyckelvalv från åtkomstprinciper till Azure RBAC. Om du vill migrera åtkomstkontroll kan du läsa Migrera till Azure RBAC från åtkomstprinciper. Standardbeteendet för Azure RBAC som introducerades för nya nyckelvalv i API-versionen 2026-02-01 och senare finns i Planera för Azure RBAC som standardmodell för åtkomstkontroll i Key Vault.

Varför flytta till en aktuell API-version

• Använd funktioner som stöds. Nyare API-versioner kan lägga till funktioner, korrekt beteende eller stödja nya tjänstfunktioner.
• Håll produktionsarbetsbelastningarna stabila. Använd en aktuell stabil API-version för produktionsarbetsbelastningar. Förhandsversioner av API:et är för utvärdering och tidig testning, och Azure support serviceavtal kanske inte täcker dem. Förhandsversioner kan fasas ut.
• Håll verktyg och bibliotek kompatibla. Azure CLI, Azure PowerShell, SDK:er, mallar och portalen kan använda olika API-versioner. Uppdatering av versionen för en klient uppdaterar inte de andra.

Aktuella versioner av kontrollplanet finns i API-versioner som stöds för kontrollplanet. Information om vilka dataplansversioner som stöds finns i referensen för Azure Key Vault REST API.

Avgör om du påverkas

Ett tjänstmeddelande innebär inte nödvändigtvis att telemetrin har identifierat en tillbakadragen API-version i varje prenumeration eller Key Vault som du äger. Meddelanden kan nå en bredare målgrupp än de resurser som identifierats i den senaste telemetrin. Använd följande steg för att utvärdera dina integreringar.

Konfigurera granskningsloggning tidigt. Key Vault börjar samla in granskningsloggar när diagnostikinställningen har aktiverats och börjar gälla. Begäranden som görs innan dess läggs inte till i efterhand, så ge tid för konfiguration och insamling. Om loggning redan är aktiverat kontrollerar du dess befintliga mål innan du lägger till en annan diagnostikinställning.

Välj eller skapa en Log Analytics arbetsyta

Du kan dela arbetsyta, men du måste konfigurera insamlingen för varje Key Vault som du vill övervaka. Att skapa en arbetsyta eller exportera en prenumerations aktivitetslogg aktiverar inte granskningsloggning för Key Vault. Inkludera alla relevanta nyckelvalv, inte bara de nyckelvalv som en rekommendation visar.

1. Återanvänd eller skapa en arbetsyta. Om det redan finns en godkänd Log Analytics arbetsyta registrerar du dess namn, prenumeration och resurs-ID. Annars skapar du en. Mer information finns i Skapa en Log Analytics-arbetsyta. Använd en arbetsyta per prenumeration eller välj en central arbetsyta för flera prenumerationer.

2. Bekräfta åtkomst. Du behöver behörighet att konfigurera diagnostikinställningar för källnyckelvalven och destinationen samt frågeåtkomst som omfattar de bidragande nyckelvalven. Mer information finns i Hantera åtkomst till Log Analytics-arbetsytor.

Aktivera granskningsloggning för varje Key Vault

Konfigurera en diagnostikinställning för varje Key Vault genom att följa Azure portalstegen i Aktivera Key Vault loggning. Använd de här inställningarna för den här undersökningen:

• Loggar: Välj kategorigruppen allLogs .
• Mål: Välj Skicka till Log Analytics arbetsyta och välj sedan den arbetsyta som du valde i föregående avsnitt. Använd samma arbetsyta för varje Key Vault som har samma mål.
• Mått: AllMetrics krävs inte för att identifiera API-versioner eller anropare.

Granskningshändelser kan omfatta både kontrollplans- och dataplansåtgärder, men den här tillbakadragningen påverkar endast kontrollplansåtgärder. Mått och exporter av prenumerationens aktivitetslogg ersätter inte granskningsloggen.

För många nyckelvalv eller prenumerationer använder du Azure Policy i stället. Tilldela den inbyggda principen Aktivera loggning efter kategorigrupp för Key Vault-valv (microsoft.keyvault/vaults) till Log Analytics med kategorigruppen allLogs och arbetsytans resurs-ID. Tilldela den till de prenumerationer som krävs med samma resurs-ID för arbetsytan för ett delat mål. Skapa en åtgärdsuppgift och den hanterade identitet som principen kräver. Enbart en principtilldelning konfigurerar inte befintliga nyckelvalv. När reparationen är klar kontrollerar du att diagnostikinställningen för varje Key Vault pekar på den avsedda arbetsytan. Mer information finns i Skapa diagnostikinställningar i stor skala med hjälp av inbyggda Azure Policy.

Bekräfta att poster anländer

Öppna målarbetsytans Loggar-sida för att köra frågor. Mer information finns i Log Analytics tutorial. I den här undersökningen använder du KQL-läge, anger omfånget till arbetsytan och väljer Senaste 30 dagarna för att matcha exemplen. Begränsa inte omfånget till ett enda Key Vault när du undersöker alla bidragande prenumerationer.

Ge tid för inledande inläsning. När du har skapat en diagnostikinställning bör data börja flöda till arbetsytan inom 90 minuter och en tabell skapas först efter att de första posterna har anlänt. Mer information finns i Förväntad svarstid när du har skapat en diagnostikinställning. Efter installationen kör du representativa hanteringsarbetsflöden på ett säkert sätt och kör sedan frågan igen. Om du uppdaterar nyckelvalvet i Azure-portalen kan du kontrollera samlingen, men det testar inte alla produktionsintegrationer. Ändra inte åtkomstkontrollmodellen för ett Key Vault bara för att testa loggning.

Kontrollera insamlingen genom att först köra den här frågan utan ett API-versionsfilter:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50

Kontrollera _ResourceId och TimeGenerated för att bekräfta att poster kommer från de avsedda nyckelvalven efter installationen. Om du vill kontrollera ett Key Vault som inte finns i de senaste 50 raderna filtrerar du på _ResourceId före order by.

Om en tabell saknas eller frågan inte returnerar några poster, kontrollera arbetsytan, den sparade diagnostikinställningen, käll-Key Vault på nytt, frågans omfång, tidsintervallet och dina behörigheter. En tabell som saknas eller ett tomt resultat bevisar inte att ingen API-version som håller på att fasas ut används.

Hitta begäranden som använder en API-version som håller på att fasas ut

När du har bekräftat insamlingen ersätter du frågan med någon av följande frågor och väljer sedan Kör.

Om du vill hitta begäranden som använder en specifik version som håller på att tas ur bruk, till exempel 2026-03-01-preview, filtrerar du på den versionen:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc

Om du vill hitta begäranden som använder valfri kontrollplans-API-version som är tidigare än 2026-02-01, filtrerar du på versioner som sorterar före 2026-02-01:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc

Resultaten identifierar registrerade begäranden som använder en version som håller på att avvecklas, inklusive deras resurs-ID:n. Den andra frågan kan också returnera dataplansbegäranden som använder äldre dataplansversioner 2015-06-01 eller 2016-10-01. Den här tillbakadragningen påverkar inte begäranden till dataplanet. Dataplanets åtgärdsnamn börjar med Secret, Key eller Certificate.

Filtrera inte på åtgärdsnamn som börjar med Vault, eftersom det filtret kan exkludera registrerade underordnade resursåtgärder. Använd OperationName och begärande-URI:n för att förstå vilken hanteringsåtgärd som inträffade. Använd informationen i dessa loggar för att identifiera anroparen och uppdatera sedan dess API-version enligt beskrivningen i Uppdatera din API-version.

Avgöra vilken API-version du använder

Du anger API-versionen på olika sätt beroende på hur du anropar Key Vault. Kontrollera varje yta som din arbetsbelastning använder.

Kontrollplan (hantering)

• REST API: Versionen är frågesträngsparametern api-version i begäranden till https://management.azure.com, till exempel ?api-version=<control-plane-version>.
• ARM-mallar och Bicep filer: Versionen är apiVersion egenskapen för varje Microsoft.KeyVault/vaults resurs. I Bicep är det en del av resurstypsdeklarationen, till exempel resource kv 'Microsoft.KeyVault/vaults@2026-02-01'. Underordnade resurser som Microsoft.KeyVault/vaults/secrets, Microsoft.KeyVault/vaults/keysoch Microsoft.KeyVault/vaults/accessPolicies styr även planresurser och var och en deklarerar sin egen API-version. Uppdateringen av det överordnade valvets version uppdaterar inte dess underordnade resurser.
• Terraform: Med AzAPI-providern är versionen en del av resurstypen, till exempel Microsoft.KeyVault/vaults@2026-02-01. Med AzureRM-providern avgör providerversionen API-versionen och resurserna har ingen inställning för API-version. Kontrollera versionsinformationen för providern och resursdokumentationen för den API-version som din providerversion använder.
• SDK:er för kontrollplanshantering: Paketversionen kan avgöra vilka API-versioner som en SDK stöder, men enbart paketversionen identifierar inte alltid den API-version som används av en begäran. Kontrollera viktig information om paketet och API-referensen (till exempel för Azure.ResourceManager.KeyVault eller azure-mgmt-keyvault) och jämför dem med paketversionen i projektets beroendemanifest. API-referenser efter språk finns i Azure Key Vault klientbibliotek.
• Azure CLI och Azure PowerShell: Versionen av din Azure CLI eller Az modul avgör API-versionen. Kontrollera den installerade versionen med az version eller Get-InstalledModule -Name Az.
• Azure portalen: Portalen väljer API-versionen för kontrollplanet för sina begäranden. Du kan inte ange den versionen direkt. Portalen kan använda en annan API-version än dina mallar, skript eller SDK:er, så använd inte portalbeteendet för att fastställa vilken version som används av din automatisering.
• Azure Cloud Shell: Cloud Shell använder aktuella Azure CLI och Azure PowerShell versioner. Om du kör skript i Cloud Shell kontrollerar du att de är kompatibla med den api-version av kontrollplanet som stöds för närvarande.

Dataplanet

• REST API: Versionen är frågesträngsparametern api-version på begäranden till valvslutpunkten, till exempel GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
• SDK:er för dataplan: Paketversionen kan avgöra vilka API-versioner som en SDK stöder, men enbart paketversionen identifierar inte alltid den API-version som används av en begäran. Kontrollera viktig information om paketet och API-referensen (till exempel för Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keyseller Azure.Security.KeyVault.Certificates) och jämför dem med paketversionen i projektets beroendemanifest. API-referenser efter språk finns i Azure Key Vault klientbibliotek.

Uppdatera din API-version

Uppdatera API-versionen för kontrollplanet

1. Uppdatera API-versionen i dina mallar och REST-anrop. Ange apiVersion (ARM, Bicep), den versionshanterade resurstypen (Terraform AzAPI) eller frågesträngsparametern api-version (REST) till en kontrollplansversion som stöds för närvarande. Uppdatera alla Microsoft.KeyVault/vaults definitioner, deras underordnade resurser och hanteringsbegäranden. Om du använder Terraform AzureRM-providern uppdaterar du providern till en version som använder en API-version för kontrollplan som stöds.

2. Uppdatera SDK:er för kontrollplanshantering. Kontrollera viktig information om paketet och API-referensen för den paketversion som stöder den api-version av kontrollplanet som du har valt. Api-referenser efter språk och paketversioner som stöder den aktuella Key Vault kontrollplansversionen finns i Azure Key Vault klientbibliotek och SDK-versioner för kontrollplan.

   Note

   Uppdatering av ett SDK för kontrollplanshantering uppdaterar inte SDK:er för dataplanet. Uppdatera varje SDK separat om ditt program använder båda API-ytorna.

3. Uppdatera Azure CLI och Azure PowerShell. Nyare verktygsversioner anropar nyare API-versioner.

   • Azure CLI
   • Azure PowerShell

   Uppdatera Azure CLI till den senaste versionen. Mer information finns i Så här uppdaterar du Azure CLI.

4. Granska beteendeändringar innan du distribuerar. Läs API-versionens ändringslogg och specifikation innan du distribuerar. API-version 2026-02-01 och senare innebär att standardmodellen för åtkomstkontroll endast ändras för nya nyckelvalv. Mer information finns i Planera för Azure RBAC som standardmodell för åtkomstkontroll i Key Vault.

Uppdatera api-versionen för dataplanet

1. Uppdatera API-versionen i dina REST-anrop. Ange frågesträngsparametern api-version till en dataplansversion som för närvarande stöds i Azure Key Vault REST API-referens.

2. Uppdatera dina SDK:er för dataplanet. Uppgradera Azure.Security.KeyVault.*-paketen (eller motsvarande för ditt språk) till den senaste stabila versionen. Kontrollera viktig information om paketet och API-referensen för att avgöra vilka API-versioner av dataplanet som paketet stöder. API-referenser och paketlänkar efter språk finns i Azure Key Vault klientbibliotek.

Stabila API-versioner för dataplanet påverkas inte av det aktuella kontrollplanets tillbakadragning. Om du använder ett API för förhandsversion av dataplanet granskar du tjänstmeddelandena och API-referensen för dess livscykel.

Mer information om hur du anropar REST API för dataplanet finns i Autentisering, begäranden och svar och Azure Key Vault REST API-referens.

Relaterat innehåll

• Planera för Azure RBAC som standardmodell för åtkomstkontroll i Key Vault
• Migrera till Azure RBAC från åtkomstprinciper
• Nyheter för Azure Key Vault
• API-versioner för kontrollplan som stöds
• Autentisering, begäranden och svar
• Azure Key Vault klientbibliotek
• Azure Key Vault utvecklarguide
• Azure Key Vault REST API-referens