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.

Important

Alla Key Vault API-versioner för kontrollplanet före 2026-02-01 upphör att gälla den 27 februari 2027. Efter detta datum finns dina nyckelvalv fortfarande kvar, men du kan endast hantera dem med kontrollplans-API-version 2026-02-01 eller senare. Det finns inget undantag eller tillägg till det här datumet. Den här tillbakadragningen påverkar inte API:er för dataplanet (DE API:er som används för att arbeta med nycklar, hemligheter och certifikat). Mer information finns i Planera för Azure RBAC som standardmodell för åtkomstkontroll i Key Vault.

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

API-gränssnitt Vad den hanterar Versionsschema Exempelslutpunkt
Kontrollplan (hantering) Själva nyckelvalvsresursen: skapa, uppdatera, ta bort valv och konfigurera egenskaper som SKU, nätverksregler och åtkomstkontroll. Datumbaserad ({YYYY}-{MM}-{DD}) https://management.azure.com
Dataplanet Objekt i ett valv: nycklar, hemligheter och certifikat samt kryptografiska åtgärder. Datumbaserad ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

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ö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-, Bicep- och Terraform-mallar: Versionen är egenskapen apiVersion 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'.
  • 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 anges med frågesträngsparametern api-version i begäranden till ditt valvs slutpunkt, 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, Terraform) eller frågesträngsparametern api-version (REST) till en kontrollplansversion som stöds för närvarande i alla Microsoft.KeyVault/vaults definitioner och hanteringsbegäranden.

  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.

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

  1. 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

  • Uppdaterades senast