Połączenie do usługi Azure AI Search przy użyciu uwierzytelniania klucza

Artykuł
03/11/2024

Usługa Azure AI Search oferuje uwierzytelnianie oparte na kluczach, których można używać w połączeniach z usługą wyszukiwania. Klucz interfejsu API to unikatowy ciąg składający się z 52 losowo wygenerowanych cyfr i liter. Żądanie skierowane do punktu końcowego usługi wyszukiwania jest akceptowane, jeśli żądanie i klucz interfejsu API są prawidłowe.

Uwaga

Krótka uwaga dotycząca sposobu użycia terminologii "kluczowej" w usłudze Azure AI Search. "Klucz interfejsu API", który został opisany w tym artykule, odnosi się do identyfikatora GUID używanego do uwierzytelniania żądania. Oddzielny termin "klucz dokumentu" odnosi się do unikatowego ciągu w indeksowanej zawartości używanej do unikatowego identyfikowania dokumentów w indeksie wyszukiwania.

Typy kluczy interfejsu API

Istnieją dwa rodzaje kluczy używanych do uwierzytelniania żądania:

Typ	Poziom uprawnień	Maksymalnie	Jak utworzono
Administrator	Pełny dostęp (odczyt i zapis) dla wszystkich operacji zawartości	2 ¹	Dwa klucze administratora, nazywane kluczami podstawowymi i pomocniczymi w portalu, są generowane podczas tworzenia usługi i mogą być indywidualnie generowane ponownie na żądanie.
Query	Dostęp tylko do odczytu w zakresie kolekcji dokumentów indeksu wyszukiwania	50	Jeden klucz zapytania jest generowany za pomocą usługi. Więcej można utworzyć na żądanie przez administratora usługi wyszukiwania.

¹ Posiadanie dwóch umożliwia przerzucanie jednego klucza podczas korzystania z drugiego klucza w celu dalszego dostępu do usługi.

Wizualnie nie ma rozróżnienia między kluczem administratora lub kluczem zapytania. Oba klucze to ciągi składające się z 52 losowo generowanych znaków alfanumerycznych. Jeśli utracisz śledzenie typu klucza określonego w aplikacji, możesz sprawdzić wartości kluczy w portalu.

Używanie kluczy interfejsu API w połączeniach

Klucze interfejsu API są używane na potrzeby żądań płaszczyzny danych (zawartości), takich jak tworzenie indeksu lub uzyskiwanie dostępu do indeksu lub dowolne inne żądanie reprezentowane w interfejsach API REST wyszukiwania. Podczas tworzenia usługi klucz interfejsu API jest jedynym mechanizmem uwierzytelniania dla operacji płaszczyzny danych, ale możesz zastąpić lub uzupełnić uwierzytelnianie klucza rolami platformy Azure, jeśli nie możesz używać kluczy zakodowanych w kodzie.

Klucze interfejsu API są określane na żądaniach klientów do usługi wyszukiwania. Przekazanie prawidłowego klucza interfejsu API w żądaniu jest uznawane za dowód, że żądanie pochodzi z autoryzowanego klienta. Jeśli tworzysz, modyfikujesz lub usuwasz obiekty, musisz mieć klucz interfejsu API administratora. W przeciwnym razie klucze zapytań są zwykle dystrybuowane do aplikacji klienckich, które wystawiają zapytania.

Klucze interfejsu API można określić w nagłówku żądania dla wywołań interfejsu API REST lub w kodzie, który wywołuje biblioteki klienta azure.search.documents w zestawach SDK platformy Azure. Jeśli używasz witryny Azure Portal do wykonywania zadań, przypisanie roli określa poziom dostępu.

Najlepsze rozwiązania dotyczące używania zakodowanych kluczy w plikach źródłowych obejmują:

Używaj kluczy interfejsu API tylko wtedy, gdy ujawnienie danych nie jest zagrożeniem (na przykład w przypadku korzystania z przykładowych danych) i jeśli pracujesz za zaporą. Ujawnienie kluczy interfejsu API jest zagrożeniem zarówno dla danych, jak i nieautoryzowanego użycia usługi wyszukiwania.
Zawsze sprawdzaj kod, przykłady i materiały szkoleniowe przed opublikowaniem, aby upewnić się, że nie pozostawisz prawidłowych kluczy interfejsu API.
W przypadku obciążeń produkcyjnych przejdź do pozycji Microsoft Entra ID i dostępu opartego na rolach. Jeśli chcesz nadal używać kluczy interfejsu API, pamiętaj, aby zawsze monitorować , kto ma dostęp do kluczy interfejsu API i ponownie wygenerować klucze interfejsu API w regularnych okresach.

Jak klucze interfejsu API są używane w witrynie Azure Portal:

Uwierzytelnianie klucza jest wbudowane. Domyślnie portal najpierw próbuje klucze interfejsu API. Jeśli jednak wyłączysz klucze interfejsu API i skonfigurujesz przypisania ról, portal używa przypisań ról.

Jak klucze interfejsu API są używane w programie PowerShell:

Ustaw klucze interfejsu API w nagłówku żądania przy użyciu następującej składni:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Przykładowy skrypt przedstawiający użycie klucza interfejsu API dla różnych operacji można znaleźć w artykule Szybki start: tworzenie indeksu usługi Azure AI Search w programie PowerShell przy użyciu interfejsów API REST.

Jak klucze interfejsu API są używane w wywołaniach REST:

Ustaw klucz administratora w nagłówku żądania. Nie można przekazać kluczy administratora w identyfikatorze URI ani w treści żądania.

Administracja klucze są używane do operacji create-read-update-delete i żądań wystawionych dla samej usługi wyszukiwania, takich jak wyświetlanie obiektów lub żądanie statystyk usługi.

Klucze zapytań są używane do operacji wyszukiwania, sugestii lub wyszukiwania przeznaczonych dla kolekcji index/docs . W polu POST ustaw api-key wartość w nagłówku żądania. Możesz też umieścić klucz w identyfikatorze URI dla polecenia GET: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

Uwaga

Jest to uważane za słabe rozwiązanie w zakresie zabezpieczeń do przekazywania poufnych danych, takich jak identyfikator api-key w identyfikatorze URI żądania. Z tego powodu usługa Azure AI Search akceptuje tylko klucz zapytania jako element api-key w ciągu zapytania. Ogólnie rzecz biorąc, zalecamy przekazanie elementu api-key jako nagłówka żądania.

Uprawnienia do wyświetlania kluczy interfejsu API lub zarządzania nimi

Uprawnienia do wyświetlania kluczy interfejsu API i zarządzania nimi są przekazywane za pośrednictwem przypisań ról. Członkowie następujących ról mogą wyświetlać i ponownie wygenerować klucze:

Właściciel
Współautor
Współautor usługi wyszukiwania
Administracja istrator i współadministrator (wersja klasyczna)

Następujące role nie mają dostępu do kluczy interfejsu API:

Czytelnik
Współautor danych indeksu wyszukiwania
Czytnik danych indeksu wyszukiwania

Znajdowanie istniejących kluczy

Klucze interfejsu API można wyświetlać i zarządzać nimi w witrynie Azure Portal lub za pomocą programu PowerShell, interfejsu wiersza polecenia platformy Azure lub interfejsu API REST.

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze Ustawienia wybierz pozycję Klucze, aby wyświetlić klucze administratora i zapytania.

Az.Search Zainstaluj moduł:
```
Install-Module Az.Search
```

Zwróć klucze administratora:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Zwracanie kluczy zapytania:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Użyj następujących poleceń, aby zwrócić odpowiednio klucze administratora i interfejsu API zapytań:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Aby zwrócić klucze interfejsu API, użyj klawiszy Administracja listy lub kluczy zapytań listy w interfejsie API REST zarządzania.

Aby zwrócić lub zaktualizować klucze interfejsu API, musisz mieć prawidłowe przypisanie roli. Aby uzyskać wskazówki dotyczące spełnienia wymagań dotyczących ról przy użyciu interfejsów API REST, zobacz Zarządzanie usługa wyszukiwania azure AI za pomocą interfejsów API REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Tworzenie kluczy zapytań

Klucze zapytań są używane do uzyskiwania dostępu tylko do odczytu do dokumentów w indeksie na potrzeby operacji przeznaczonych dla kolekcji dokumentów. Zapytania dotyczące wyszukiwania, filtrowania i sugestii to wszystkie operacje, które przyjmują klucz zapytania. Każda operacja tylko do odczytu zwracająca dane systemowe lub definicje obiektów, takie jak definicja indeksu lub stan indeksatora, wymaga klucza administratora.

Ograniczenie dostępu i operacji w aplikacjach klienckich jest niezbędne do ochrony zasobów wyszukiwania w usłudze. Zawsze używaj klucza zapytania, a nie klucza administratora dla dowolnego zapytania pochodzącego z aplikacji klienckiej.

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze Ustawienia wybierz pozycję Klucze, aby wyświetlić klucze interfejsu API.
W obszarze Zarządzanie kluczami zapytań użyj klucza zapytania, który został już wygenerowany dla usługi, lub utwórz nowe klucze zapytań. Domyślny klucz zapytania nie ma nazwy, ale inne wygenerowane klucze zapytań mogą być nazwane pod kątem możliwości zarządzania.

Użyj polecenia Create Query Keys in the Management REST API (Tworzenie kluczy zapytań w interfejsie API REST zarządzania).

Aby utworzyć klucze interfejsu API lub zarządzać nimi, musisz mieć prawidłowe przypisanie roli. Aby uzyskać wskazówki dotyczące spełnienia wymagań dotyczących ról przy użyciu interfejsów API REST, zobacz Zarządzanie usługa wyszukiwania azure AI za pomocą interfejsów API REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Ponowne generowanie kluczy administratora

Dla każdej usługi są tworzone dwa klucze administracyjne, dzięki czemu można obracać klucz podstawowy podczas korzystania z klucza pomocniczego na potrzeby ciągłości działania.

W obszarze Ustawienia wybierz pozycję Klucze, a następnie skopiuj klucz pomocniczy.
W przypadku wszystkich aplikacji zaktualizuj ustawienia klucza interfejsu API, aby używać klucza pomocniczego.
Wygeneruj ponownie klucz podstawowy.
Zaktualizuj wszystkie aplikacje, aby używały nowego klucza podstawowego.

Jeśli przypadkowo ponownie wygenerujesz oba klucze w tym samym czasie, wszystkie żądania klientów używające tych kluczy nie powiedzą się z powodu niedozwolonego protokołu HTTP 403. Jednak zawartość nie jest usuwana i nie jest trwale zablokowana.

Nadal możesz uzyskać dostęp do usługi za pośrednictwem portalu lub programowo. Funkcje zarządzania działają za pośrednictwem identyfikatora subskrypcji, a nie klucza interfejsu API usługi i dlatego są nadal dostępne, nawet jeśli klucze interfejsu API nie są.

Po utworzeniu nowych kluczy za pośrednictwem portalu lub warstwy zarządzania dostęp zostanie przywrócony do zawartości (indeksy, indeksatory, źródła danych, mapy synonimów) po podaniu tych kluczy na żądaniach.

Bezpieczne klucze interfejsu API

Użyj przypisań ról, aby ograniczyć dostęp do kluczy interfejsu API.

Pamiętaj, że szyfrowanie kluczy zarządzanych przez klienta nie jest możliwe do szyfrowania kluczy interfejsu API. Tylko poufne dane w samej usłudze wyszukiwania (na przykład zawartość indeksu lub parametry połączenia w definicjach obiektów źródła danych) mogą być szyfrowane za pomocą klucza CMK.

Przejdź do strony usługi wyszukiwania w witrynie Azure Portal.
W okienku nawigacji po lewej stronie wybierz pozycję Kontrola dostępu (zarządzanie dostępem i tożsamościami), a następnie wybierz kartę Przypisania ról.
W filtrze Rola wybierz role, które mają uprawnienia do wyświetlania kluczy (właściciel, współautor, współautor, współautor usługi wyszukiwania). Wynikowe podmioty zabezpieczeń przypisane do tych ról mają kluczowe uprawnienia do usługi wyszukiwania.
Jako środek ostrożności sprawdź również kartę Klasyczni administratorzy, aby określić, czy administratorzy i współadministratorzy mają dostęp.