Aktualizowanie używanej wersji interfejsu API Azure Key Vault

Azure Key Vault korzysta z wersjonowanych interfejsów API. Jeśli aplikacje, skrypty lub szablony infrastruktury wywołają starszą wersję interfejsu API, możesz przegapić nowsze funkcje, użyć zachowania zmienionego w nowszej wersji lub zależeć od wersji, która nie jest już zalecana. W tym artykule wyjaśniono, jak określić używaną wersję interfejsu API i jak przejść do bieżącej, obsługiwanej wersji.

Important

Wszystkie wersje interfejsu API płaszczyzny sterowania usługi Key Vault sprzed 2026-02-01 zostaną wycofane 27 lutego 2027 r. Po tej dacie magazyny kluczy nadal istnieją, ale można nimi zarządzać tylko przy użyciu wersji 2026-02-01 interfejsu API płaszczyzny sterowania lub nowszej. Nie ma wyjątku ani rozszerzenia do tej daty. Wycofanie nie ma wpływu na interfejsy API płaszczyzny danych (interfejsy API używane do pracy z kluczami, wpisami tajnymi i certyfikatami). Aby uzyskać szczegółowe informacje, zobacz Plan dotyczący kontroli dostępu opartej na rolach platformy Azure jako domyślnego modelu kontroli dostępu w usłudze Key Vault.

Azure Key Vault ma dwie niezależne powierzchnie interfejsu API, z których każda ma własne wersje:

Powierzchnia interfejsu API Czym zarządza Schemat wersji Przykładowy punkt końcowy
Płaszczyzna sterowania (zarządzanie) Sam zasób magazynu kluczy: tworzenie, aktualizowanie i usuwanie magazynów oraz konfigurowanie właściwości, takich jak SKU, reguły sieciowe i kontrola dostępu. Na podstawie daty ({YYYY}-{MM}-{DD}) https://management.azure.com
Płaszczyzna danych Obiekty w sejfie: klucze, sekrety i certyfikaty oraz operacje kryptograficzne. Na podstawie daty ({YYYY}-{MM}-{DD}) https://<vault-name>.vault.azure.net

Obie powierzchnie mają różne praktyki dotyczące przechowywania wersji i cyklu życia. Zaktualizowanie jednego nie aktualizuje drugiego. Sprawdź oba te elementy, jeśli obciążenie używa obu tych elementów.

Wersje interfejsu API płaszczyzny sterowania można wycofać zgodnie z opisem we wcześniejszej sekcji tego artykułu.

Podglądowe wersje interfejsu API płaszczyzny danych mogą zostać wycofane, dlatego nie używaj wersji zapoznawczych w środowisku produkcyjnym, chyba że akceptujesz związany z tym cykl życia. Aby uzyskać informacje o obsługiwanych wersjach interfejsu API płaszczyzny danych, zobacz dokumentację interfejsu API REST Azure Key Vault.

Ten artykuł koncentruje się na identyfikowaniu i aktualizowaniu wersji interfejsu API. Aktualizacja wersji interfejsu API płaszczyzny sterowania nie wymaga przeprowadzania migracji istniejącego magazynu kluczy z zasad dostępu do kontroli dostępu opartej na rolach platformy Azure (Azure RBAC). Jeśli chcesz przeprowadzić migrację mechanizmu kontroli dostępu, zobacz Migrowanie z zasad dostępu do kontroli dostępu opartej na rolach platformy Azure (Azure RBAC). Informacje na temat domyślnego zachowania mechanizmu Azure RBAC wprowadzonego dla nowych magazynów kluczy w wersji interfejsu API 2026-02-01 i nowszych można znaleźć tutaj: Plan wdrożenia usługi Azure RBAC jako domyślnego modelu kontroli dostępu w usłudze Key Vault.

Dlaczego warto przejść do bieżącej wersji interfejsu API

  • Używaj obsługiwanych funkcji. Nowsze wersje interfejsu API mogą dodawać możliwości, poprawne zachowanie lub obsługiwać nowe funkcje usługi.
  • Zachowaj stabilność obciążeń produkcyjnych. Użyj bieżącej stabilnej wersji interfejsu API dla obciążeń produkcyjnych. Wersje interfejsu API w wersji zapoznawczej są przeznaczone do oceny i wczesnego testowania, a umowy SLA pomoc techniczna platformy Azure mogą ich nie obejmować. Wersje zapoznawcze mogą zostać oznaczone jako przestarzałe.
  • Zachowaj zgodność narzędzi i bibliotek. Azure CLI, Azure PowerShell, zestawy SDK, szablony i portal mogą używać różnych wersji interfejsu API. Aktualizacja wersji dla jednego klienta nie powoduje zaktualizowania innych.

Aby zapoznać się z bieżącymi wersjami płaszczyzny sterowania, zobacz Obsługiwane wersje interfejsu API płaszczyzny sterowania. Aby uzyskać informacje o obsługiwanych wersjach płaszczyzny danych, zobacz dokumentację interfejsu API REST Azure Key Vault.

Określanie używanej wersji interfejsu API

Wersja interfejsu API jest określana inaczej w zależności od sposobu wywoływania Key Vault. Sprawdź poszczególne powierzchnie używane przez obciążenie.

Płaszczyzna sterowania (zarządzanie)

  • REST API: wersja to parametr zapytania api-version w żądaniach do https://management.azure.com, na przykład ?api-version=<control-plane-version>.
  • Szablony ARM, Bicep i Terraform: Wersja to właściwość apiVersion w każdym zasobie Microsoft.KeyVault/vaults. W Bicep jest częścią deklaracji typu zasobu, na przykład resource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
  • Zestawy SDK zarządzania płaszczyzną sterowania: wersja pakietu może określić, które wersje interfejsu API obsługuje zestaw SDK, ale sama wersja pakietu nie zawsze identyfikuje wersję interfejsu API używaną przez żądanie. Sprawdź informacje o wersji pakietu i dokumentację interfejsu API (na przykład dla Azure.ResourceManager.KeyVault lub azure-mgmt-keyvault) i porównaj je z wersją pakietu w manifeście zależności projektu. Aby zapoznać się z dokumentacją interfejsu API według języka, zobacz Azure Key Vault biblioteki klienckie.
  • Azure CLI i Azure PowerShell: wersja Azure CLI lub Az modułu określa wersję interfejsu API. Sprawdź zainstalowaną wersję za pomocą polecenia az version lub Get-InstalledModule -Name Az.
  • Azure portal: Portal wybiera wersję interfejsu API płaszczyzny sterowania na potrzeby swoich żądań. Nie można ustawić tej wersji bezpośrednio. Portal może używać innej wersji interfejsu API niż szablony, skrypty lub zestawy SDK, dlatego nie należy używać zachowania portalu do określania wersji używanej przez automatyzację.
  • Azure Cloud Shell: Cloud Shell używa bieżących wersji Azure CLI i Azure PowerShell. Jeśli uruchamiasz skrypty w Cloud Shell, upewnij się, że są one zgodne z aktualnie obsługiwaną wersją interfejsu API płaszczyzny sterowania.

Płaszczyzna danych

  • REST API: Wersja to parametr api-version w ciągu zapytania w żądaniach wysyłanych do punktu końcowego magazynu, na przykład GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • Zestawy SDK płaszczyzny danych: wersja pakietu może określić, które wersje interfejsu API obsługuje zestaw SDK, ale sama wersja pakietu nie zawsze identyfikuje wersję interfejsu API używaną przez żądanie. Sprawdź informacje o wersji pakietu i dokumentację interfejsu API (na przykład dla Azure.Security.KeyVault.SecretsAzure.Security.KeyVault.Keys, lub Azure.Security.KeyVault.Certificates) i porównaj je z wersją pakietu w manifeście zależności projektu. Aby zapoznać się z dokumentacją interfejsu API według języka, zobacz Azure Key Vault biblioteki klienckie.

Aktualizowanie wersji interfejsu API

Zaktualizuj wersję interfejsu API płaszczyzny sterowania

  1. Zaktualizuj wersję interfejsu API w szablonach i wywołaniach REST. Ustaw apiVersion (ARM, Bicep, Terraform) lub parametr ciągu zapytania api-version (REST) na aktualnie obsługiwaną wersję płaszczyzny sterowania we wszystkich definicjach Microsoft.KeyVault/vaults i żądaniach zarządzania.

  2. Zaktualizuj zestawy SDK zarządzania płaszczyzną sterowania. Zapoznaj się z informacjami o wersji pakietu i dokumentacją interfejsu API dla wersji pakietu obsługującej wybraną wersję interfejsu API płaszczyzny sterowania. Aby zapoznać się z dokumentacją interfejsu API według języka i wersji pakietu, które obsługują bieżącą wersję płaszczyzny sterowania Key Vault, zobacz Azure Key Vault biblioteki klienta i wersje zestawu SDK płaszczyzny sterowania.

    Note

    Aktualizowanie zestawu SDK zarządzania płaszczyzną sterowania nie aktualizuje zestawów SDK płaszczyzny danych. Zaktualizuj każdy zestaw SDK oddzielnie, jeśli aplikacja używa obu powierzchni interfejsu API.

  3. Zaktualizuj Azure CLI i Azure PowerShell. Nowsze wersje narzędzi wywołują nowsze wersje interfejsu API.

    Zaktualizuj interfejs wiersza polecenia platformy Azure do najnowszej wersji. Aby uzyskać więcej informacji, zobacz Jak zaktualizować Azure CLI.

  1. Przed wdrożeniem przejrzyj zmiany zachowania. Przed wdrożeniem przeczytaj dziennik zmian i specyfikację wersji interfejsu API. Wersja interfejsu API 2026-02-01 i nowsze zmieniają domyślny model kontroli dostępu tylko dla nowych magazynów kluczy. Aby uzyskać szczegółowe informacje, zobacz Planowanie kontroli dostępu na podstawie ról Azure jako domyślny model kontroli dostępu w Key Vault.

Zaktualizuj wersję interfejsu API płaszczyzny danych

  1. Zaktualizuj wersję interfejsu API w wywołaniach REST. api-version Ustaw parametr ciągu zapytania na aktualnie obsługiwaną wersję płaszczyzny danych wymienioną w dokumentacji interfejsu API REST Azure Key Vault.

  2. Zaktualizuj SDK płaszczyzny danych. Uaktualnij pakiety Azure.Security.KeyVault.* (lub ich odpowiedniki w Twoim języku) do aktualnej stabilnej wersji. Sprawdź informacje o wersji pakietu i dokumentację interfejsu API, aby określić, które wersje interfejsu API płaszczyzny danych obsługuje pakiet. Aby zapoznać się z dokumentacją interfejsu API i linkami pakietów według języka, zobacz Azure Key Vault biblioteki klienckie.

Stabilne wersje interfejsu API płaszczyzny danych nie są objęte obecnym wycofaniem płaszczyzny sterowania. Jeśli używasz interfejsu API płaszczyzny danych w wersji zapoznawczej, zapoznaj się z komunikatami dotyczącymi usługi oraz dokumentacją referencyjną interfejsu API, aby poznać jego cykl życia.

Aby uzyskać więcej informacji na temat wywoływania interfejsu API REST płaszczyzny danych, zobacz Uwierzytelnianie, żądania i odpowiedzi oraz dokumentację referencyjną interfejsu API REST usługi Azure Key Vault.

Treści powiązane

  • Last updated on