Nawiązywanie połączenia z usługą Azure AI Search przy użyciu kluczy

Artykuł
10/30/2024

Usługa Azure AI Search oferuje uwierzytelnianie oparte na kluczach dla połączeń z usługą wyszukiwania. Klucz interfejsu API to unikatowy ciąg składający się z 52 losowo wygenerowanych cyfr i liter. W kodzie źródłowym możesz określić ją jako zmienną środowiskową lub jako ustawienie aplikacji w projekcie, a następnie odwołać się do zmiennej w żądaniu. Żądanie skierowane do punktu końcowego usługi wyszukiwania jest akceptowane, jeśli żądanie i klucz interfejsu API są prawidłowe.

Uwierzytelnianie oparte na kluczach jest domyślne.

Możesz zastąpić go dostępem opartym na rolach, co eliminuje potrzebę zakodowanych na stałe kluczy w bazie kodu.

Typy kluczy interfejsu API

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

Typ	Poziom uprawnień	Maksymalnie	Jak utworzono
Administracja	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 administracyjne są używane do tworzenia, modyfikowania lub usuwania obiektów. Klucze administracyjne są również używane do pobierania definicji obiektów i informacji systemowych.

Klucze zapytań są zwykle dystrybuowane do aplikacji klienckich, które wystawiają zapytania.

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. Klucze administracyjne są używane do operacji create-read-update-delete i dla żądań wystawionych dla samej usługi wyszukiwania, takich jak indeksy LIST lub GET Service Statistics.

Oto przykład użycia klucza interfejsu API administratora w żądaniu tworzenia indeksu:

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Ustaw klucz zapytania w nagłówku żądania post lub na identyfikatorze URI get. Klucze zapytań są używane do operacji przeznaczonych index/docs dla kolekcji: Wyszukiwanie dokumentów, Autouzupełnianie, Sugerowanie lub GET Dokumentu.

Oto przykład użycia klucza interfejsu API zapytań w żądaniu wyszukiwania dokumentów (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

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.

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.

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
Administrator 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 administracyjne i klucze zapytań.

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 kluczy administracyjnych 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.

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.

Najlepsze rozwiązania

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.

Udostępnij za pośrednictwem