Připojení k Azure AI Vyhledávač pomocí klíčů

Azure AI Vyhledávač podporuje ověřování založené na identitě i ověřování na základě klíčů (výchozí) pro připojení k vaší vyhledávací službě.

Požadavek na koncový bod vyhledávací služby se přijme, pokud je požadavek i klíč rozhraní API platné a pokud je vyhledávací služba nakonfigurovaná tak, aby umožňovala klíče rozhraní API na požadavku.

Důležité

Při vytváření vyhledávací služby je výchozí ověřování založené na klíčích, ale není to nejbezpečnější možnost. Doporučujeme, abyste ho nahradili přístupem na základě role.

Požadavky

Abyste mohli zobrazit nebo spravovat klíče, musíte být vlastníkem, přispěvatelem nebo přispěvatelem vyhledávací služby .

Ve výchozím nastavení povoleno

Na portálu Azure se ověřování zadává na stránce Settings>Keys. Možnosti nastavené na klíče rozhraní API (výchozí) nebo obě povolují klíče rozhraní API na požadavku.

Typy klíčů

Klíč rozhraní API je jedinečný řetězec složený z 52 náhodně generovaných čísel a písmen. Vizuálně neexistuje žádný rozdíl mezi klíčem správce nebo klíčem dotazu. Pokud ztratíte přehled o tom, jaký typ klíče je v aplikaci zadaný, můžete kontrolovat hodnoty klíčů na portálu Azure.

K ověřování požadavku se používají dva typy klíčů:

Typ	Úroveň oprávnění	Jak se to vyrobí	Maximálně
Správce	Úplný přístup (čtení i zápis) pro všechny operace roviny dat (obsah)	Při vytváření služby se vygenerují dva klíče správce, primární a sekundární a dají se zvlášť vygenerovat na vyžádání. Když budete mít dva klíče, umožní vám to při používání druhého klíče pro nepřetržitý přístup ke službě přenést jeden klíč.	2
Dotaz	Přístup jen pro čtení, omezený na kolekci dokumentů indexu vyhledávání	Jeden klíč pro dotazy je vygenerován službou. Správce vyhledávací služby může vytvořit další možnosti na vyžádání.	50

Vyhledání existujících klíčů

Klíče rozhraní API můžete zobrazit a spravovat pomocí portálu Azure, PowerShell, Azure CLI nebo REST API.

Přejděte do vyhledávací služby na portálu Azure.
V levém podokně vyberte Klíče nastavení> a zobrazte klíče správce a dotazování.

Spuštěním následujících příkazů vraťte klíče rozhraní API pro správu a dotazování. Nápovědu k rozhraní REST najdete v tématu Spravování služby Azure AI Vyhledávač pomocí rozhraní REST API.

Vrácení klíčů správce:

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

Návratové klíče dotazu:

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

Referenční informace:Klíče správce – Získání, klíče dotazů – Seznam podle vyhledávací služby

K programovému načtení klíčů rozhraní API použijte Azure SDK pro Python. Nainstalujte sadu SDK pro správu:

pip install azure-mgmt-search azure-identity

Spuštěním následujícího kódu vraťte klíče rozhraní API pro správu a dotazování:

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient

# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"

# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)

# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")

# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
    print(f"Query key '{key.name}': {key.key}")

Reference:SearchManagementClient | AdminKeys | QueryKeys

Spuštěním následujících příkazů vraťte klíče rozhraní API pro správu a dotazování. Nápovědu k PowerShellu najdete v tématu Spravování služby Azure AI Vyhledávač pomocí PowerShellu.

Az.Search Nainstalujte modul:
```
Install-Module Az.Search
```

Vrácení klíčů správce:

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

Návratové klíče dotazu:

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

Spuštěním následujících příkazů vraťte klíče rozhraní API pro správu a dotazování. Nápovědu k Azure CLI najdete v tématu Spravování služby Azure AI Vyhledávač pomocí Azure CLI.

Vrácení klíčů správce:

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

Návratové klíče dotazu:

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

Použití klíčů u připojení

Ověřování založené na klíči se používá jenom pro požadavky na rovinu dat (obsah), jako je například vytvoření nebo dotazování indexu a jakákoli jiná akce prováděná pomocí rozhraní REST API vyhledávací služby.

Ve zdrojovém kódu můžete přímo zadat klíč rozhraní API v hlavičce požadavku. Alternativně ho můžete uložit jako proměnnou prostředí nebo nastavení aplikace v projektu a pak na proměnnou v požadavku odkazovat.

Klíče správce se používají k vytváření, úpravám nebo odstraňování objektů.
Klíče správce se také používají k definici objektů GET a systémovým informacím, jako jsou indexy LIST nebo STATISTIKA SLUŽBY GET.
Klíče dotazů se obvykle distribuují do klientských aplikací, které vydávají dotazy.

Vzpomeňte si, že ověřování klíčů je ve výchozím nastavení povolené a podporuje operace roviny dat, jako je indexování a dotazy.

Pokud ale zakážete klíče rozhraní API a nastavíte přiřazení rolí, portál Azure použije přiřazení rolí.

V hlavičce požadavku nastavte klíč správce. Administrátorské klíče nemůžete v URI nebo těle žádosti předat.

Tady je příklad použití klíče rozhraní API pro správu při žádosti o vytvoření indexu:

@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 }
         ]
   }

Nastavte dotazovací klíč v hlavičce požadavku pro POST, anebo na identifikátor URI pro GET. Klíče dotazů se používají pro operace, které cílí na index/docs kolekci: Prohledat dokumenty, automatické dokončování, Navrhnout nebo ZÍSKAT dokument.

Tady je příklad použití klíče rozhraní API pro dotazy na požadavek GET (Search Documents):

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

Poznámka:

Považuje se za špatný bezpečnostní postup předávat citlivá data, jako je api-key, v identifikátoru URI požadavku. Z tohoto důvodu Azure AI Vyhledávač v řetězci dotazu přijímá pouze klíč dotazu jako api-key. Obecně platí, že doporučujeme předat vaše api-key jako hlavičku požadavku.

Osvědčeným postupem je nastavit klíč rozhraní API jako proměnnou prostředí, ale pro zjednodušení se v tomto příkladu zobrazuje jako řetězec. Příklad používá klíč rozhraní API dotazu pro operaci dotazu.

# Import libraries
from azure.search.documents import SearchClient
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']}")

Nastavte klíče rozhraní API v hlavičce požadavku pomocí následující syntaxe:

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

K zahrnutí plně kvalifikovaného dotazu použijte proměnnou:

$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'

Odešlete požadavek do vyhledávací služby:

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

Další příklady skriptů pro jiné operace najdete v Quickstart: Vytvoření indexu Azure AI Vyhledávač v PowerShellu pomocí rozhraní REST API.

Vytvoření klíčů dotazu

Klíče dotazů se používají pro přístup k dokumentům jen pro čtení v rámci indexu pro operace, které cílí na kolekci dokumentů. Vyhledávací, filtrované a navrhované dotazy jsou všechny operace, které přebírají klíč dotazu. Jakákoli operace jen pro čtení, která vrací systémové data nebo definice objektů, jako je například definice indexu nebo stav indexeru, vyžaduje klíč správce.

Omezení přístupu a operací v klientských aplikacích je nezbytné k ochraně vyhledávacích prostředků ve vaší službě. Vždy používejte klíč dotazu místo klíče správce pro jakýkoli dotaz pocházející z klientské aplikace.

Přejděte do vyhledávací služby na portálu Azure.
V levém podokně vyberte Klíče nastavení> a zobrazte klíče rozhraní API.
V části Spravovat klíče dotazu použijte klíč dotazu, který už je pro vaši službu vygenerovaný, nebo vytvořte nové klíče dotazu. Výchozí klíč dotazu není pojmenovaný, ale další vygenerované klíče dotazu můžou být pojmenované pro možnosti správy.

V rozhraní REST API pro správu použijte klíče pro vytváření dotazů.

Abyste mohli vytvářet nebo spravovat klíče rozhraní API, musíte mít platné přiřazení role. Pokyny ke splnění požadavků na role s využitím rozhraní REST API najdete v tématu Spravování služby Azure AI Vyhledávač pomocí rozhraní REST API.

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

Opětovné generování klíčů správce

Pro každou službu se vytvoří dva klíče správce, takže primární klíč můžete obměnět při použití sekundárního klíče pro zajištění kontinuity podnikových procesů.

Přejděte do vyhledávací služby na portálu Azure.
V levém podokně vyberte Nastavení>Klíče.
Zkopírujte sekundární klíč.
Pro všechny aplikace aktualizujte nastavení klíče rozhraní API tak, aby používalo sekundární klíč.
Znovu vygenerujte primární klíč.
Aktualizujte všechny aplikace tak, aby používaly nový primární klíč.

Pokud neúmyslně vygenerujete oba klíče současně, všechny požadavky klientů používající tyto klíče selžou s chybou HTTP 403 Zakázáno. Obsah se ale neodstraní a nebudete trvale uzamčení.

Ke službě se můžete stále dostat prostřednictvím portálu Azure nebo prostřednictvím kódu programu. Funkce správy fungují prostřednictvím ID předplatného, nikoli klíče rozhraní API služby, a proto jsou stále dostupné i v případě, že klíče rozhraní API nejsou.

Po vytvoření nových klíčů prostřednictvím portálu nebo vrstvy správy se po zadání těchto klíčů na žádostech obnoví přístup k obsahu (indexy, indexery, zdroje dat, mapy synonym).

Migrace z klíčů na role

Pokud chcete přejít na přístup na základě role, je užitečné pochopit, jak se klíče mapují na vestavěné role v Azure AI Vyhledávač:

Klíč správce odpovídá rolím Přispěvatel vyhledávací služby a Přispěvatel dat indexu vyhledávání .
Klíč dotazu odpovídá roli Čtenář dat indexu vyhledávání .

Zabezpečené klíče

Pomocí přiřazení rolí omezte přístup ke klíčům rozhraní API.

Šifrování klíčů spravovaných zákazníkem není možné použít k šifrování klíčů rozhraní API. Můžou být šifrována pouze citlivá data v samotné vyhledávací službě (například obsah indexu nebo řetězce připojení v definicích objektů zdroje dat).

Přejděte do vyhledávací služby na portálu Azure.
V levém podokně vyberte Řízení přístupu (IAM) a pak vyberte kartu Přiřazení rolí .
Ve filtru role vyberte role, které mají oprávnění k zobrazení nebo správě klíčů (vlastník, přispěvatel, přispěvatel vyhledávací služby). Výsledné objekty zabezpečení přiřazené těmto rolím mají pro vaši vyhledávací službu klíčová oprávnění.
V rámci preventivních opatření zkontrolujte také kartu Klasické správce a zjistěte, jestli mají správci a spolusprávci přístup.

Osvědčené postupy

V případě produkčních úloh přepněte na Microsoft Entra ID a přístup na základě rolí. Případně pokud chcete dál používat klíče rozhraní API, nezapomeňte vždy sledovat , kdo má přístup k vašim klíčům rozhraní API , a v pravidelných intervalech znovu vygenerovat klíče rozhraní API .
Klíče rozhraní API používejte jenom v případě, že zpřístupnění dat není rizikem (například při použití ukázkových dat) a pokud pracujete za bránou firewall. Vystavení klíčů rozhraní API vystavuje vaše data i vyhledávací službě riziku neoprávněného použití.
Pokud používáte klíč rozhraní API, uložte ho bezpečně někam jinam, například v Azure Key Vault. Nezahrnujte API klíč přímo do kódu a nikdy ho nezveřejňujte.
Před publikováním vždy zkontrolujte kód, ukázky a trénovací materiály, abyste měli jistotu, že nechtěně nezveřejníte klíč rozhraní API.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-07

Připojení k Azure AI Vyhledávač pomocí klíčů

Požadavky

Ve výchozím nastavení povoleno

Typy klíčů

Vyhledání existujících klíčů

Použití klíčů u připojení

Vytvoření klíčů dotazu

Opětovné generování klíčů správce

Migrace z klíčů na role

Zabezpečené klíče

Osvědčené postupy

Související obsah

Váš názor

Další materiály