Připojení do Služby Azure AI Search s využitím ověřování klíčů

Článek
04/22/2024

Azure AI Search nabízí ověřování založené na klíčích, které můžete použít u připojení k vaší vyhledávací službě. Klíč rozhraní API je jedinečný řetězec složený z 52 náhodně generovaných čísel a písmen. Požadavek na koncový bod vyhledávací služby se přijme, pokud je požadavek i klíč rozhraní API platné.

Ověřování na základě klíčů je výchozí. Pokud se přihlásíte k ověřování na základě role, můžete ho zakázat.

Poznámka:

Rychlá poznámka ke klíčové terminologii. Klíč rozhraní API je identifikátor GUID používaný k ověřování. Samostatný termín, klíč dokumentu je jedinečný řetězec v indexovaném obsahu, který jedinečně identifikuje dokumenty v indexu vyhledávání.

Typy klíčů rozhraní API

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

Typ	Úroveň oprávnění	Maximum	Jak se vytvořilo
správce	Úplný přístup (čtení i zápis) pro všechny operace s obsahem	2 ¹	Při vytváření služby se generují dva klíče správce, označované jako primární a sekundární klíče na portálu, a dají se zvlášť vygenerovat na vyžádání.
Dotaz	Přístup jen pro čtení, omezený na kolekci dokumentů indexu vyhledávání	50	Jeden klíč dotazu se vygeneruje se službou. Správce vyhledávací služby může vytvořit další možnosti na vyžádání.

¹ Dvě umožňuje převést jeden klíč při použití druhého klíče pro pokračování přístupu ke službě.

Vizuálně neexistuje žádný rozdíl mezi klíčem správce nebo klíčem dotazu. Oba klíče jsou řetězce složené z 52 náhodně vygenerovaných alfanumerálních znaků. Pokud ztratíte přehled o typu klíče zadaného v aplikaci, můžete zkontrolovat hodnoty klíčů na portálu.

Použití klíčů rozhraní API pro připojení

Klíče rozhraní API se používají pro požadavky roviny dat (obsahu), jako je například vytvoření indexu nebo přístup k indexu nebo jakýkoli jiný požadavek, který je reprezentovaný v rozhraních REST API služby Search. Při vytváření služby je klíč rozhraní API jediným mechanismem ověřování pro operace roviny dat, ale pokud v kódu nemůžete použít pevně zakódované klíče, můžete nahradit nebo doplnit ověřování pomocí klíčů Azure .

Správa klíče se používají k vytváření, úpravám nebo odstraňování objektů. klíče Správa slouží také k definici objektů GET a informacím o systému.

Klíče dotazů se obvykle distribuují do klientských aplikací, které vydávají dotazy.

Jak se klíče rozhraní API používají ve voláníCH REST:

V hlavičce požadavku nastavte klíč správce. Klíče správce nemůžete předat na identifikátor URI ani v textu požadavku. Správa klíče se používají k operaci create-read-update-delete a k žádostem vydaným pro samotnou vyhledávací službu, jako je napříkladINDEXY LIST nebo STATISTIKA SLUŽBY GET

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

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-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 klíč dotazu v hlavičce požadavku pro POST nebo 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=2023-11-01&api-key={{queryApiKey}}

Poznámka:

Považuje se za špatný postup zabezpečení při předávání citlivých dat, jako api-key je například identifikátor URI požadavku. Z tohoto důvodu Azure AI Search přijímá klíč dotazu pouze jako api-key klíč dotazu v řetězci dotazu. Obecně platí, že doporučujeme předat hlavičku api-key požadavku.

Jak se klíče rozhraní API používají v PowerShellu:

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

Příklad skriptu znázorňující použití klíče rozhraní API pro různé operace najdete v rychlém startu: Vytvoření indexu Azure AI Search v PowerShellu pomocí rozhraní REST API.

Oprávnění k zobrazení nebo správě klíčů rozhraní API

Oprávnění k zobrazení a správě klíčů rozhraní API se předávají prostřednictvím přiřazení rolí. Členové následujících rolí můžou zobrazit a znovu vygenerovat klíče:

Vlastník
Přispěvatel
Přispěvatel vyhledávací služby
Správa istrator a spolusprávce (classic)

Následující role nemají přístup ke klíčům rozhraní API:

Čtenář
Přispěvatel dat indexu vyhledávání
Čtečka dat indexu vyhledávání

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

Klíče rozhraní API můžete zobrazit a spravovat na webu Azure Portal nebo prostřednictvím PowerShellu, Azure CLI nebo rozhraní REST API.

Přihlaste se k webu Azure Portal a vyhledejte vyhledávací službu.
V části Nastavení vyberte Klíče, abyste zobrazili klíče správce a dotazování.

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>

K vrácení klíčů rozhraní API pro správu a dotazování použijte následující příkazy:

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

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

K vrácení klíčů rozhraní API pro správu použijte klíče seznamu Správa nebo vypsat klíče dotazu v rozhraní REST API pro správu.

Abyste mohli vracet nebo aktualizovat 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 Správa Search Azure AI s využitím rozhraní REST API.

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

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řihlaste se k webu Azure Portal a vyhledejte vyhledávací službu.
V části Nastavení vyberte Klíče 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 Správa Search Azure AI s využitím rozhraní REST API.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-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ů.

V části Nastavení vyberte Klíče a pak sekundární klíč zkopírujte.
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 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).

Zabezpečené klíče rozhraní API

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. Šifrovat můžou být pouze citlivá data v samotné vyhledávací službě (například obsah indexu nebo připojovací řetězec v definicích objektů zdroje dat).

Na webu Azure Portal přejděte na stránku vyhledávací služby.
V levém navigační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

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 představuje riziko pro data i neoprávněné použití vyhledávací služby.
Před publikováním vždy zkontrolujte kód, ukázky a trénovací materiály, abyste měli jistotu, že jste nezanechali platné klíče rozhraní API.
V případě produkčních úloh přepněte na ID Microsoft Entra a přístup na základě role. 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.