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.

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

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, czy dotyczy to Ciebie

Powiadomienie o usłudze niekoniecznie oznacza, że dane telemetryczne wykryły wycofaną wersję interfejsu API w każdej posiadanej subskrypcji lub usłudze Key Vault. Powiadomienia mogą docierać do szerszej grupy odbiorców niż zasoby wykryte w ostatnich danych telemetrycznych. Wykonaj poniższe kroki, aby ocenić swoje integracje.

Skonfiguruj rejestrowanie inspekcji/audytu wcześnie. Key Vault rozpoczyna zbieranie dzienników inspekcji po włączeniu ustawienia diagnostycznego i wejściu w życie. Żądania wysyłane wcześniej nie są uzupełniane wstecznie, więc daj czas na konfigurację i pozyskiwanie danych. Jeśli rejestrowanie jest już włączone, przed dodaniem innego ustawienia diagnostycznego sprawdź jego istniejące miejsce docelowe.

Wybierz lub utwórz obszar roboczy Log Analytics

Obszar roboczy można udostępnić, ale musisz skonfigurować kolekcję w każdym Key Vault, który chcesz monitorować. Utworzenie obszaru roboczego lub wyeksportowanie dziennika aktywności subskrypcji nie powoduje włączenia rejestrowania inspekcji/audytu usługi Key Vault. Uwzględnij wszystkie odpowiednie magazyny kluczy, nie tylko magazyny kluczy, które wymienia rekomendacja.

1. Użyj ponownie obszaru roboczego lub utwórz nowy. Jeśli zatwierdzony obszar roboczy Log Analytics już istnieje, zarejestruj jego nazwę, subskrypcję i identyfikator zasobu. W przeciwnym razie utwórz obszar roboczy. Aby uzyskać więcej informacji, zobacz Tworzenie obszaru roboczego usługi Log Analytics. Użyj jednego obszaru roboczego na subskrypcję lub wybierz centralny obszar roboczy dla wielu subskrypcji.

2. Potwierdź dostęp. Musisz mieć uprawnienia do konfigurowania ustawień diagnostycznych w źródłowych magazynach kluczy i w miejscu docelowym oraz dostęp do wykonywania zapytań obejmujący współtworzące magazyny kluczy. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do obszarów roboczych usługi Log Analytics.

Włączanie rejestrowania audytu w każdym Key Vault

Skonfiguruj ustawienie diagnostyczne dla każdego Key Vault, wykonując kroki portalu Azure w temacie Włączanie rejestrowania Key Vault. Zastosuj te ustawienia dla tego dochodzenia:

• Dzienniki: Wybierz grupę kategorii allLogs.
• Miejsce docelowe: wybierz pozycję Wyślij do obszaru roboczego Log Analytics, a następnie wybierz obszar roboczy wybrany w poprzedniej sekcji. Użyj tego samego obszaru roboczego dla każdego magazynu Key Vault, który współdzieli miejsce docelowe.
• Metryki: Funkcja AllMetrics nie jest wymagana do identyfikowania wersji interfejsu API ani wywołujących.

Zdarzenia inspekcji mogą obejmować zarówno operacje płaszczyzny sterowania, jak i płaszczyzny danych, ale wycofanie ma wpływ tylko na operacje płaszczyzny sterowania. Eksporty metryk i dziennika aktywności subskrypcji nie zastępują dziennika inspekcji.

W przypadku wielu magazynów kluczy lub subskrypcji należy użyć Azure Policy. Przypisz wbudowane zasady Włącz rejestrowanie według grupy kategorii dla magazynów kluczy (microsoft.keyvault/vaults) do usługi Log Analytics z grupą kategorii allLogs i identyfikatorem zasobu Twojego obszaru roboczego. Przypisz je w ramach wymaganych subskrypcji przy użyciu tego samego identyfikatora zasobu obszaru roboczego dla udostępnionego miejsca docelowego. Utwórz zadanie korygowania i tożsamość zarządzaną wymaganą przez tę zasadę. Przypisanie zasad nie konfiguruje istniejących magazynów kluczy. Po zakończeniu korygowania sprawdź, czy ustawienie diagnostyczne każdego Key Vault wskazuje na zamierzony obszar roboczy. Aby uzyskać więcej informacji, zobacz Tworzenie ustawień diagnostycznych na dużą skalę przy użyciu wbudowanych Azure Policy.

Upewnij się, że są odbierane rekordy

Otwórz stronę Dzienniki docelowego obszaru roboczego, aby uruchomić zapytania. Aby uzyskać więcej informacji, zobacz Log Analytics tutorial. W ramach tego badania użyj trybu KQL, ustaw zakres na obszar roboczy, a następnie wybierz pozycję Ostatnie 30 dni , aby dopasować je do przykładów. Nie ograniczaj zakresu do pojedynczego Key Vault podczas badania wszystkich współtworzących subskrypcji.

Odczekaj na początkowe pozyskanie danych. Po utworzeniu ustawienia diagnostycznego dane powinny zacząć przepływać do obszaru roboczego w ciągu 90 minut, a tabela jest tworzona dopiero po nadejściu pierwszych rekordów. Aby uzyskać więcej informacji, zobacz Oczekiwane opóźnienie po utworzeniu ustawienia diagnostycznego. Po skonfigurowaniu bezpiecznie uruchom reprezentatywne przepływy pracy zarządzania, a następnie uruchom ponownie zapytanie. Odświeżenie Key Vault w portalu Azure może pomóc w sprawdzeniu kolekcji, ale nie testuje każdej integracji produkcyjnej. Nie zmieniaj modelu kontroli dostępu usługi Key Vault tylko w celu testowania rejestrowania.

Aby sprawdzić kolekcję, najpierw uruchom to zapytanie bez filtru wersji interfejsu API:

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

Sprawdź _ResourceId i TimeGenerated, aby upewnić się, że rekordy pochodzą z docelowych magazynów kluczy po skonfigurowaniu. Aby sprawdzić magazyn kluczy, który nie znajduje się w ostatnich 50 wierszach, przefiltruj według _ResourceId przed order by.

Jeśli brakuje tabeli lub zapytanie nie zwraca żadnych rekordów, sprawdź ponownie obszar roboczy, zapisane ustawienie diagnostyczne, źródłowy magazyn kluczy, zakres zapytania, zakres czasu i uprawnienia. Brak tabeli lub pusty wynik nie dowodzi, że nie jest używana żadna wycofana wersja interfejsu API.

Znajdowanie żądań korzystających z wycofanej wersji interfejsu API

Po potwierdzeniu zbierania danych zastąp zapytanie jednym z następujących zapytań, a następnie wybierz pozycję Uruchom.

Aby znaleźć żądania używające określonej wycofywanej wersji, na przykład 2026-03-01-preview, filtruj dla tej wersji:

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

Aby znaleźć żądania korzystające z dowolnej wersji interfejsu API płaszczyzny sterowania starszej niż 2026-02-01, należy filtrować wersje sortowane przed :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

Wyniki identyfikują zarejestrowane żądania korzystające z wycofywanej wersji, w tym ich identyfikatory zasobów. Drugie zapytanie może również zwracać żądania płaszczyzny danych, które używają starszych wersji płaszczyzny danych 2015-06-01 lub 2016-10-01. Wycofanie nie wpływa na żądania płaszczyzny danych. Nazwy operacji płaszczyzny danych zaczynają się od Secret, Keylub Certificate.

Nie filtruj nazw operacji rozpoczynających się od Vault, ponieważ ten filtr może wykluczać zarejestrowane operacje zasobów podrzędnych. Użyj OperationName i identyfikatora URI żądania, aby zrozumieć, która operacja zarządzania wystąpiła. Użyj szczegółów w tych dziennikach, aby zidentyfikować obiekt wywołujący, a następnie zaktualizować jego wersję interfejsu API zgodnie z opisem w temacie Aktualizowanie wersji interfejsu API.

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)

• Interfejs API REST: wersja to api-version parametr ciągu zapytania dla żądań do https://management.azure.com, na przykład ?api-version=<control-plane-version>.
• Szablony usługi ARM i pliki Bicep: wersja jest właściwością apiVersion każdego Microsoft.KeyVault/vaults zasobu. W Bicep jest częścią deklaracji typu zasobu, na przykład resource kv 'Microsoft.KeyVault/vaults@2026-02-01'. Zasoby podrzędne, takie jak Microsoft.KeyVault/vaults/secrets, Microsoft.KeyVault/vaults/keys i Microsoft.KeyVault/vaults/accessPolicies, są również zasobami płaszczyzny sterowania, a każdy z nich deklaruje własną wersję interfejsu API. Aktualizowanie wersji magazynu nadrzędnego nie powoduje zaktualizowania zasobów podrzędnych.
• Terraform: W przypadku dostawcy AzAPI wersja jest częścią typu zasobu, na przykład Microsoft.KeyVault/vaults@2026-02-01. W przypadku dostawcy modułu AzureRM wersja dostawcy określa wersję interfejsu API, a zasoby nie mają ustawienia wersji interfejsu API. Zapoznaj się z informacjami o wersji dostawcy i dokumentacją zasobów dla wersji interfejsu API używanej przez Twoją wersję dostawcy.
• 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 Azure wybiera wersję interfejsu API płaszczyzny sterowania dla żą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

• Interfejs API REST: wersja to api-version parametr ciągu zapytania dla żądań 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), typ zasobu w wersji (Terraform AzAPI) lub api-version parametr ciągu zapytania (REST) na obecnie obsługiwaną wersję płaszczyzny sterowania. Zaktualizuj wszystkie Microsoft.KeyVault/vaults definicje, ich zasoby podrzędne i żądania zarządzania. Jeśli używasz dostawcy programu Terraform AzureRM, zaktualizuj dostawcę do wersji korzystającej z obsługiwanej wersji interfejsu API płaszczyzny sterowania.

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.

   • Azure CLI
   • Azure PowerShell

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

4. 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 Plan dotyczący kontroli dostępu opartej na rolach platformy Azure jako domyślnego modelu kontroli dostępu w usłudze 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

• Planowanie użycia kontroli dostępu opartej na rolach Azure jako domyślnego modelu kontroli dostępu w Key Vault
• Migrowanie z zasad dostępu do kontroli dostępu opartej na rolach platformy Azure
• Co nowego w Azure Key Vault
• Obsługiwane wersje interfejsu API płaszczyzny sterowania
• Uwierzytelnianie, żądania i odpowiedzi
• biblioteki klienckie Azure Key Vault
• Przewodnik dewelopera Azure Key Vault
• Dokumentacja referencyjna interfejsu API REST Azure Key Vault