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

Usługa Azure AI Search obsługuje zarówno uwierzytelnianie oparte na tożsamościach, jak i oparte na kluczach na potrzeby 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 bezpośrednio określić klucz interfejsu API w nagłówku żądania. Alternatywnie możesz zapisać ją jako zmienną środowiskową lub ustawienie aplikacji w projekcie, a następnie odwołać się do zmiennej w żądaniu.

Ważne

Podczas tworzenia usługi wyszukiwania uwierzytelnianie oparte na kluczach jest domyślne, ale nie jest to najbezpieczniejsza opcja. Zalecamy zastąpienie go dostępem opartym na rolach.

Domyślnie włączone

Uwierzytelnianie oparte na kluczach jest ustawieniem domyślnym dla nowych usług wyszukiwania. Żądanie skierowane do punktu końcowego usługi wyszukiwania jest akceptowane, jeśli żądanie i klucz interfejsu API są prawidłowe, a usługa wyszukiwania jest skonfigurowana tak, aby zezwalała na klucze interfejsu API na żądanie.

W portalu Azure należy określić uwierzytelnianie na stronie Ustawienia>Klucze. Klucze interfejsu API lub Oba zapewniają obsługę kluczy.

Typy kluczy

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

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

¹ 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 witrynie Azure Portal.

Mapowanie typu klucz-rola

Ten artykuł dotyczy kluczy interfejsu API. Jeśli jednak chcesz przejść do dostępu opartego na rolach, warto zrozumieć, jak klucze są mapowane na wbudowane role w usłudze Azure AI Search:

• Klucz administracyjny odpowiada rolam Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania .
• Klucz zapytania odpowiada roli Czytelnik danych indeksu wyszukiwania .

Uprawnienia do wyświetlania kluczy 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 przy użyciu witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia platformy Azure lub interfejsu API REST.

Portal

1. Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.

2. Po lewej stronie wybierz Ustawienia>Klucze, aby wyświetlić klucze administratora i zapytania.

Program PowerShell

1. Az.Search Zainstaluj moduł:

   Install-Module Az.Search
   

2. Zwróć klucze administratora:

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

3. Zwracanie kluczy zapytania:

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

Interfejs wiersza polecenia platformy Azure

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>

Interfejs API REST

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=2025-05-01

Używanie kluczy 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 usługi wyszukiwania.

Możesz użyć klucza interfejsu API lub ról dla żądań płaszczyzny sterowania (usługi). W przypadku korzystania z klucza interfejsu API:

• 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, takich jak indeksy LIST lub GET Service Statistics.

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

Interfejs API REST

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

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

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-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=2025-09-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.

Python

Najlepszym rozwiązaniem jest ustawienie klucza interfejsu API jako zmiennej środowiskowej, ale dla uproszczenia w tym przykładzie pokazano go jako ciąg. W przykładzie użyto klucza API zapytania dla operacji wykonywania zapytania.

# Import libraries
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

Program 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' }

Użyj zmiennej, aby zawierać w pełni kwalifikowane zapytanie:

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

Wyślij żądanie do usługi wyszukiwania:

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Więcej przykładów skryptów dla innych 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.

Portal

Pamiętaj, że uwierzytelnianie klucza jest domyślnie włączone i obsługuje operacje płaszczyzny danych, takie jak indeksowanie i zapytania.

Jeśli jednak wyłączysz klucze interfejsu API i skonfigurujesz przypisania ról, zamiast tego witryna Azure Portal używa przypisań ról.

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.

Portal

1. Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Ustawienia>Klucze, aby zobaczyć klucze API.

3. 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.

   

Program PowerShell

Przykładowy skrypt przedstawiający użycie klucza interfejsu API można znaleźć w artykule Tworzenie lub usuwanie kluczy zapytań.

Interfejs wiersza polecenia platformy Azure

Przykładowy skrypt przedstawiający użycie klucza zapytania można znaleźć w artykule Tworzenie lub usuwanie kluczy zapytań.

Interfejs API REST

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=2025-05-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.

1. Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.

2. W okienku po lewej stronie wybierz Ustawienia>Klucze.

3. Skopiuj klucz pomocniczy.

4. W przypadku wszystkich aplikacji zaktualizuj ustawienia klucza interfejsu API, aby używać klucza pomocniczego.

5. Wygeneruj ponownie klucz podstawowy.

6. 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 witryny Azure Portal 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.

Zabezpieczanie kluczy

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.

1. Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami), a następnie wybierz kartę Przypisania ról .

3. 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.

4. 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

• W przypadku obciążeń produkcyjnych przejdź do pozycji Microsoft Entra ID i dostępu opartego na rolach. Alternatywnie, 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.

• 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ą. Uwidacznianie kluczy interfejsu API naraża dane i usługę wyszukiwania na ryzyko nieautoryzowanego użycia.

• Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

• Zawsze sprawdzaj kod, przykłady i materiały szkoleniowe przed opublikowaniem, aby upewnić się, że nie uwidaczniasz przypadkowo klucza interfejsu API.

Treści powiązane

• Zabezpieczenia w usłudze Azure AI Search
• Kontrola dostępu oparta na rolach platformy Azure w usłudze Azure AI Search
• Zarządzanie za pomocą programu PowerShell