Aktualisieren der verwendeten Azure Key Vault-API-Version

Azure Key Vault verwendet versionsierte APIs. Wenn Ihre Anwendungen, Skripts oder Infrastrukturvorlagen eine ältere API-Version aufrufen, verpassen Sie möglicherweise neuere Features, verwenden Sie das Verhalten, das in einer späteren Version geändert wurde, oder hängt von einer Version ab, die nicht mehr empfohlen wird. In diesem Artikel wird erläutert, wie Sie bestimmen, welche API-Version Sie verwenden und wie Sie zu einer aktuellen, unterstützten Version wechseln.

Important

Alle API-Versionen der Key Vault-Steuerungsebene vor 2026-02-01 werden am 27. Februar 2027 eingestellt. Nach diesem Datum sind Ihre Schlüsseltresore weiterhin vorhanden, aber Sie können sie nur mit der API-Version 2026-02-01 oder höherer der Kontrollebene verwalten. Bis zu diesem Datum gibt es keine Ausnahme oder Erweiterung. Diese Außerbetriebnahme wirkt sich nicht auf Datenebenen-APIs aus (die APIs, die für die Arbeit mit Schlüsseln, Geheimnissen und Zertifikaten verwendet werden). Weitere Informationen finden Sie unter Planen von Azure RBAC als Standardzugriffssteuerungsmodell in Key Vault.

Azure Key Vault verfügt über zwei unabhängige API-Oberflächen mit jeweils eigenen Versionen:

API-Oberfläche Was es verwaltet Versionsschema Beispiel-Endpunkt
Steuerungsebene (Verwaltung) Die Schlüsseltresorressource selbst: Erstellen, Aktualisieren, Löschen von Tresoren und Konfigurieren von Eigenschaften wie SKU, Netzwerkregeln und Zugriffssteuerung. Datumsbasiert ({YYYY}-{MM}-{DD}) https://management.azure.com
Datenebene Objekte innerhalb eines Tresors: Schlüssel, geheime Schlüssel und Zertifikate sowie kryptografische Vorgänge. Datumsbasiert ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

Die beiden Oberflächen weisen unterschiedliche Versionsverwaltungs- und Lebenszykluspraktiken auf. Das Aktualisieren des einen aktualisiert das andere nicht. Überprüfen Sie beides, wenn Ihre Workload beides verwendet.

Steuerebenen-API-Versionen können eingestellt werden, wie weiter oben in diesem Artikel beschrieben.

Api-Versionen der Vorschaudatenebene können veraltet sein. Verwenden Sie daher keine Vorschauen in der Produktion, es sei denn, Sie akzeptieren diesen Lebenszyklus. Unterstützte API-Versionen der Datenebene finden Sie in der Azure Key Vault REST-API-Referenz.

Dieser Artikel konzentriert sich auf das Identifizieren und Aktualisieren von API-Versionen. Das Aktualisieren einer API-Version für die Steuerungsebene erfordert nicht, dass Sie einen vorhandenen Schlüsseltresor von Zugriffsrichtlinien zu Azure RBAC migrieren. Wenn Sie die Zugriffssteuerung migrieren möchten, lesen Sie "Migrieren zu Azure RBAC aus Zugriffsrichtlinien". Informationen zum Azure RBAC-Standardverhalten, das für neue Schlüsselcontainer ab API-Version 2026-02-01 eingeführt wurde, finden Sie unter Planen von Azure RBAC als Standardmodell für die Zugriffssteuerung in Key Vault.

Warum zu einer aktuellen API-Version wechseln

  • Verwenden Sie unterstützte Funktionen. Neuere API-Versionen können Funktionen hinzufügen, Verhalten korrigieren oder neue Dienstfunktionen unterstützen.
  • Halten Sie Ihre Produktions-Workloads stabil. Verwenden Sie eine aktuelle stabile API-Version für Produktionsworkloads. Vorschau-API-Versionen dienen zur Evaluierung und zu frühen Tests, und Azure-Support SLAs werden sie möglicherweise nicht abdecken. Vorschauversionen können veraltet sein.
  • Halten Sie Tools und Bibliotheken kompatibel. Azure CLI, Azure PowerShell, SDKs, Vorlagen und das Portal können unterschiedliche API-Versionen verwenden. Durch das Aktualisieren der Version für einen Client werden die anderen nicht aktualisiert.

Aktuelle Steuerelementebenenversionen finden Sie unter Unterstützte Versionen der Steuerelementebenen-API. Unterstützte Versionen der Datenebene finden Sie in der Azure Key Vault REST-API-Referenz.

Ermitteln, welche API-Version Sie verwenden

Je nachdem, wie Sie Key Vault aufrufen, geben Sie die API-Version unterschiedlich an. Überprüfen Sie jede Oberfläche, die Ihre Workload verwendet.

Steuerungsebene (Verwaltung)

  • REST-API: Die Version ist der api-version Abfragezeichenfolgenparameter für Anforderungen an https://management.azure.com, z. B ?api-version=<control-plane-version>. .
  • ARM-, Bicep- und Terraform-Vorlagen: Die Version ist die apiVersion-Eigenschaft bei jeder Microsoft.KeyVault/vaults-Ressource. In Bicep ist dies Teil der Ressourcentypdeklaration, zum Beispiel resource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • Steuerungsebenenverwaltungs-SDKs: Die Paketversion kann bestimmen, welche API-Versionen ein SDK unterstützt, aber die Paketversion allein identifiziert nicht immer die API-Version, die von einer Anforderung verwendet wird. Überprüfen Sie die Versionshinweise und die API-Referenz des Pakets (z. B. für Azure.ResourceManager.KeyVault oder azure-mgmt-keyvault), und vergleichen Sie sie mit der Paketversion im Abhängigkeitsmanifest Ihres Projekts. Api-Verweise nach Sprache finden Sie unter Azure Key Vault Clientbibliotheken.
  • Azure CLI und Azure PowerShell: Die Version Ihres Azure CLI oder Az Moduls bestimmt die API-Version. Überprüfen Sie Ihre installierte Version mit az-Version oder Get-InstalledModule -Name Az.
  • Azure Portal: Das Portal wählt die Api-Version der Steuerungsebene für seine Anforderungen aus. Sie können diese Version nicht direkt festlegen. Das Portal kann eine andere API-Version als Ihre Vorlagen, Skripts oder SDKs verwenden. Verwenden Sie daher kein Portalverhalten, um die von Ihrer Automatisierung verwendete Version zu bestimmen.
  • Azure Cloud Shell: Cloud Shell verwendet aktuelle Azure CLI und Azure PowerShell Versionen. Wenn Sie Skripts in Cloud Shell ausführen, stellen Sie sicher, dass sie mit der aktuell unterstützten Steuerelementebenen-API-Version kompatibel sind.

Datenebene

  • REST-API: Die Version ist der api-version Abfrageparameter bei Anfragen an Ihren Tresor-Endpunkt, z. B. GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • Data plane SDKs: Die Paketversion kann bestimmen, welche API-Versionen ein SDK unterstützt, aber die Paketversion allein identifiziert nicht immer die API-Version, die von einer Anforderung verwendet wird. Überprüfen Sie die Versionshinweise und die API-Referenz des Pakets (z. B. für Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keysoder Azure.Security.KeyVault.Certificates) und vergleichen Sie sie mit der Paketversion im Abhängigkeitsmanifest Ihres Projekts. Api-Verweise nach Sprache finden Sie unter Azure Key Vault Clientbibliotheken.

Aktualisieren Der API-Version

API-Version der Control Plane aktualisieren

  1. Aktualisieren Sie die API-Version in Ihren Vorlagen und REST-Aufrufen. Legen Sie apiVersion (ARM, Bicep, Terraform) oder den api-version Abfragezeichenfolgenparameter (REST) auf eine aktuell unterstützte Steuerelementebenenversion in allen Microsoft.KeyVault/vaults Definitionen und Verwaltungsanforderungen fest.

  2. Aktualisieren Sie ihre Verwaltungs-SDKs für die Steuerungsebene. Überprüfen Sie die Paketversionshinweise und die API-Referenz für die Paketversion, die die ausgewählte Steuerelementebenen-API-Version unterstützt. Api-Verweise nach Sprache und Paketversionen, die die aktuelle Key Vault Steuerelementebenenversion unterstützen, finden Sie unter Azure Key Vault Clientbibliotheken und Control plane SDK-Versionen.

    Note

    Das Aktualisieren eines Steuerelementebenenverwaltungs-SDKs aktualisiert keine Datenebenen-SDKs. Aktualisieren Sie jedes SDK separat, wenn Ihre Anwendung beide API-Oberflächen verwendet.

  3. Aktualisieren sie Azure CLI und Azure PowerShell. Neuere Toolversionen rufen neuere API-Versionen auf.

    Aktualisieren Sie die Azure CLI auf die neueste Version. Weitere Informationen finden Sie unter Aktualisieren von Azure CLI.

  1. Überprüfen Sie Verhaltensänderungen, bevor Sie die Bereitstellung vornehmen. Lesen Sie vor der Bereitstellung das Änderungsprotokoll und die Spezifikation der API-Version. Die API-Version 2026-02-01 und höher ändert das Standardzugriffssteuerungsmodell nur für neue Schlüsseltresore. Weitere Informationen finden Sie unter Planen von Azure RBAC als Standardzugriffssteuerungsmodell in Key Vault.

Aktualisieren der Datenebenen-API-Version

  1. Aktualisieren Sie die API-Version in Ihren REST-Aufrufen. Legen Sie den api-version Abfragezeichenfolgenparameter auf eine aktuell unterstützte Datenebenenversion fest, die in der Azure Key Vault REST-API-Referenz aufgeführt ist.

  2. Aktualisieren Sie Ihre Datenebenen-SDKs. Aktualisieren Sie die Azure.Security.KeyVault.* Pakete (oder die Entsprechung für Ihre Sprache) auf eine aktuelle stabile Version. Überprüfen Sie die Versionshinweise und api-Referenz des Pakets, um zu ermitteln, welche Datenebenen-API-Versionen das Paket unterstützt. Api-Verweise und Paketlinks nach Sprache finden Sie unter Azure Key Vault Clientbibliotheken.

Stabile Data-Plane-API-Versionen sind von der aktuellen Außerbetriebnahme der Control Plane nicht betroffen. Wenn Sie eine Vorschaudatenebenen-API verwenden, überprüfen Sie die Dienstankündigungen und die API-Referenz für den Lebenszyklus.

Weitere Informationen zum Aufrufen der REST-API für die Datenebene finden Sie unter Authentifizierung, Anforderungen und Antworten sowie die Referenz zur Azure Key Vault REST-API.

Verwandte Inhalte

  • Zuletzt aktualisiert um