Připojení k Azure AI Search pomocí klíčů
Azure AI Search nabízí ověřování na základě klíčů pro 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. Ve zdrojovém kódu ho můžete zadat jako proměnnou prostředí nebo jako nastavení aplikace v projektu a pak na proměnnou v požadavku odkazovat. 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í.
Můžete ho nahradit přístupem na základě role, což eliminuje potřebu pevně zakódovaných klíčů v základu kódu.
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 1 | Dva klíče správce, označované jako primární a sekundární klíče na webu Azure Portal, se generují při vytvoření služby 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í. |
1 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 webu Azure Portal.
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 .
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 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. Klíče správce se používají k operaci create-read-update-delete a k žádostem vydaným pro samotnou vyhledávací službu, jako jsou například INDEXY SEZNAMU 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=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 }
]
}
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=2024-07-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.
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ávce 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í.
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.
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 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í.
K této službě se stále můžete dostat prostřednictvím webu Azure Portal 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.