Csatlakozás az Azure AI Search szolgáltatásba kulcshitelesítéssel

Cikk
03/12/2024

Az Azure AI Search kulcsalapú hitelesítést biztosít, amelyet a keresési szolgáltatással való kapcsolatokhoz használhat. Az API-kulcs egy egyedi sztring, amely 52 véletlenszerűen generált számból és betűből áll. A keresési szolgáltatás végpontjára irányuló kérés akkor fogadható el, ha a kérés és az API-kulcs is érvényes.

Feljegyzés

Rövid megjegyzés arról, hogy az Azure AI Search hogyan használja a "kulcs" terminológiát. A cikkben ismertetett "API-kulcs" a kérések hitelesítéséhez használt GUID-ra hivatkozik. Egy külön kifejezés, a "dokumentumkulcs" az indexelt tartalom egy egyedi sztringjét jelenti, amely a keresési indexben lévő dokumentumok egyedi azonosítására szolgál.

API-kulcsok típusai

A kérések hitelesítéséhez kétféle kulcs használható:

Típus	Engedélyszint	Maximum	Létrehozás
Rendszergazda	Teljes hozzáférés (írás-olvasás) az összes tartalomművelethez	2 ¹	A szolgáltatás létrehozásakor két rendszergazdai kulcs, más néven elsődleges és másodlagos kulcs jön létre a portálon, amelyek igény szerint egyedileg újragenerálhatók.
Lekérdezés	Írásvédett hozzáférés, keresési index dokumentumgyűjteményének hatóköre	50	A szolgáltatás egy lekérdezési kulcsot hoz létre. A keresési szolgáltatás rendszergazdája igény szerint további fájlokat is létrehozhat.

¹ A kettő lehetővé teszi, hogy egy kulccsal a második kulccsal továbbra is hozzáférhessen a szolgáltatáshoz.

Vizuálisan nincs különbség a rendszergazdai kulcs vagy a lekérdezési kulcs között. Mindkét kulcs 52 véletlenszerűen generált alfanumerikus karakterből álló sztring. Ha nem tudja nyomon követni, hogy milyen típusú kulcs van megadva az alkalmazásban, a portálon ellenőrizheti a kulcsértékeket.

API-kulcsok használata kapcsolatokon

Az API-kulcsok adatsíkra (tartalomra) irányuló kérelmekhez használhatók, például index vagy bármely más, a Search REST API-kban megjelenő kérés létrehozásához vagy eléréséhez. A szolgáltatás létrehozásakor az API-kulcs az adatsík-műveletek egyetlen hitelesítési mechanizmusa, de a kulcshitelesítést lecserélheti vagy kiegészítheti Azure-szerepkörökkel, ha a kódban nem használhat kemény kóddal ellátott kulcsokat.

Az API-kulcsok a keresési szolgáltatásnak küldött ügyfélkéréseken vannak megadva. Ha érvényes API-kulcsot ad át a kéréshez, az azt bizonyítja, hogy a kérés egy engedélyezett ügyféltől származik. Ha objektumokat hoz létre, módosít vagy töröl, rendszergazdai API-kulcsra lesz szüksége. Ellenkező esetben a lekérdezési kulcsok általában a lekérdezéseket kibocsátó ügyfélalkalmazások között vannak elosztva.

Az API-kulcsokat a REST API-hívások kérésfejlécében vagy az Azure SDK-kban az azure.search.documents ügyfélkódtárakat hívó kódban adhatja meg. Ha az Azure Portalt használja a feladatok végrehajtására, a szerepkör-hozzárendelés határozza meg a hozzáférés szintjét.

Ajánlott eljárások a kódolt kulcsok forrásfájlokban való használatához:

Csak akkor használjon API-kulcsokat, ha az adatfeltárás nem jelent kockázatot (például mintaadatok használatakor), és ha tűzfal mögött működik. Az API-kulcsok expozíciója kockázatot jelent mind az adatokra, mind a keresési szolgáltatás jogosulatlan használatára.
A közzététel előtt mindig ellenőrizze a kódot, a mintákat és a betanítási anyagokat, hogy meggyőződjön arról, hogy nem hagyott hátra érvényes API-kulcsokat.
Éles számítási feladatok esetén váltson a Microsoft Entra-azonosítóra és a szerepköralapú hozzáférésre. Vagy ha folytatni szeretné az API-kulcsok használatát, ügyeljen arra, hogy mindig figyelje , hogy ki férhet hozzá az API-kulcsokhoz , és rendszeresen újragenerálja az API-kulcsokat .

Az API-kulcsok használata az Azure Portalon:

A kulcshitelesítés be van építve. Alapértelmezés szerint a portál először az API-kulcsokat próbálja meg. Ha azonban letiltja az API-kulcsokat , és szerepkör-hozzárendeléseket állít be, a portál ehelyett szerepkör-hozzárendeléseket használ.

Az API-kulcsok használata a PowerShellben:

Api-kulcsok beállítása a kérelem fejlécében a következő szintaxissal:

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

A különböző műveletek API-kulcshasználatát bemutató példaszkript a rövid útmutatóban található : Azure AI Search-index létrehozása a PowerShellben REST API-k használatával.

AZ API-kulcsok használata REST-hívásokban:

Állítson be egy rendszergazdai kulcsot a kérelem fejlécében. Nem adhat át rendszergazdai kulcsokat az URI-n vagy a kérés törzsében.

Rendszergazda kulcsok a create-read-update-delete művelethez és a keresési szolgáltatásnak kiadott kérésekhez, például objektumok listázásához vagy szolgáltatásstatisztikák lekéréséhez használhatók.

A lekérdezési kulcsok a gyűjteményt célzó index/docs keresési, javaslati vagy keresési műveletekhez használhatók. POST esetén állítsa be api-key a kérelem fejlécében. Vagy tegye a kulcsot az URI-ra a GET-hez: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

Feljegyzés

Rossz biztonsági gyakorlatnak számít a bizalmas adatok, például api-key a kérelem URI-jának átadása. Ezért az Azure AI Search csak egy lekérdezési kulcsot fogad el a lekérdezési sztringben api-key . Általában azt javasoljuk, hogy adja át a api-key kérés fejlécét.

API-kulcsok megtekintésére vagy kezelésére vonatkozó engedélyek

Az API-kulcsok megtekintésére és kezelésére vonatkozó engedélyek szerepkör-hozzárendeléseken keresztül lesznek átadva. A következő szerepkörök tagjai megtekinthetik és újragenerálhatják a kulcsokat:

Tulajdonos
Közreműködő
Keresési szolgáltatás közreműködője
Rendszergazda istrator és társadminisztrátor (klasszikus)

A következő szerepkörök nem férnek hozzá az API-kulcsokhoz:

Olvasó
Keresési index adatszolgáltatója
Keresési index adatolvasója

Meglévő kulcsok keresése

Az API-kulcsokat az Azure Portalon, illetve a PowerShell, az Azure CLI vagy a REST API használatával tekintheti meg és kezelheti.

Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.
A Gépház területen válassza a Kulcsok lehetőségeta rendszergazdai és lekérdezési kulcsok megtekintéséhez.

Telepítse a modult Az.Search :
```
Install-Module Az.Search
```

Rendszergazdai kulcsok visszaküldése:

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

Lekérdezési kulcsok visszaadva:

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

A következő parancsokkal adja vissza a rendszergazdai és a lekérdezési API-kulcsokat:

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

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

Az API-kulcsok visszaadásához használja a lista Rendszergazda kulcsokat vagy a lekérdezési kulcsok listázását a Felügyeleti REST API-ban.

Az API-kulcsok visszaadásához vagy frissítéséhez érvényes szerepkör-hozzárendeléssel kell rendelkeznie. Az Azure AI-Search szolgáltatás REST API-kkal való kezelésével kapcsolatos útmutatásért tekintse meg a SZEREPKÖR-követelmények REST API-kkal való teljesítésével kapcsolatos útmutatást.

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

Lekérdezési kulcsok létrehozása

A lekérdezési kulcsok az indexen belüli dokumentumok írásvédett elérésére szolgálnak a dokumentumgyűjteményt célzó műveletekhez. A keresési, szűrési és javaslati lekérdezések mind olyan műveletek, amelyek lekérdezési kulcsot vesznek igénybe. Minden írásvédett művelethez, amely rendszeradatokat vagy objektumdefiníciókat ad vissza, például indexdefiníciót vagy indexelő állapotot, rendszergazdai kulcsot igényel.

Az ügyfélalkalmazások hozzáférésének és műveleteinek korlátozása elengedhetetlen a szolgáltatás keresési eszközeinek védelméhez. Mindig használjon lekérdezési kulcsot rendszergazdai kulcs helyett az ügyfélalkalmazásból származó lekérdezésekhez.

Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.
A Gépház alatt válassza a Kulcsok lehetőségetaz API-kulcsok megtekintéséhez.
A Lekérdezési kulcsok kezelése területen használja a szolgáltatáshoz már létrehozott lekérdezési kulcsot, vagy hozzon létre új lekérdezési kulcsokat. Az alapértelmezett lekérdezési kulcs nincs elnevezve, de más generált lekérdezési kulcsok is elnevezhetők a kezelhetőség érdekében.

Lekérdezési kulcsok létrehozása a Felügyeleti REST API-ban.

Az API-kulcsok létrehozásához vagy kezeléséhez érvényes szerepkör-hozzárendeléssel kell rendelkeznie. Az Azure AI-Search szolgáltatás REST API-kkal való kezelésével kapcsolatos útmutatásért tekintse meg a SZEREPKÖR-követelmények REST API-kkal való teljesítésével kapcsolatos útmutatást.

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

Rendszergazdai kulcsok újragenerálása

Minden szolgáltatáshoz két rendszergazdai kulcs jön létre, hogy az üzletmenet folytonossága érdekében a másodlagos kulcs használatával elforgathassa az elsődleges kulcsot.

A Gépház területen válassza a Kulcsok lehetőséget, majd másolja a másodlagos kulcsot.
Minden alkalmazás esetében frissítse az API-kulcs beállításait a másodlagos kulcs használatára.
Hozza létre újra az elsődleges kulcsot.
Frissítse az összes alkalmazást az új elsődleges kulcs használatára.

Ha véletlenül újragenerálja a két kulcsot egyszerre, a kulcsokat használó összes ügyfélkérés http 403 Forbidden paranccsal meghiúsul. A tartalom azonban nem törlődik, és nincs véglegesen kizárva.

A szolgáltatást továbbra is elérheti a portálon keresztül vagy programozott módon. A felügyeleti függvények nem szolgáltatás API-kulcson, hanem előfizetés-azonosítón keresztül működnek, így akkor is elérhetők, ha az API-kulcsok nem.

Miután új kulcsokat hoz létre a portálon vagy a felügyeleti rétegen keresztül, a rendszer visszaállítja a hozzáférést a tartalomhoz (indexek, indexelők, adatforrások, szinonimák leképezései), miután kérések esetén megadta ezeket a kulcsokat.

Biztonságos API-kulcsok

Szerepkör-hozzárendelések használatával korlátozhatja az API-kulcsokhoz való hozzáférést.

Vegye figyelembe, hogy nem használható ügyfél által felügyelt kulcstitkosítás az API-kulcsok titkosításához. Csak a keresési szolgáltatáson belüli bizalmas adatok (például indextartalmak vagy kapcsolati sztring adatforrás-objektumdefiníciók) titkosíthatók CMK-titkosítással.

Lépjen a keresési szolgáltatás lapjára az Azure Portalon.
A bal oldali navigációs panelen válassza a Hozzáférés-vezérlés (IAM) lehetőséget, majd a Szerepkör-hozzárendelések lapot.
A Szerepkörszűrőben válassza ki azokat a szerepköröket, amelyek jogosultak a kulcsok megtekintésére vagy kezelésére (Tulajdonos, Közreműködő, Keresési szolgáltatás közreműködője). Az ezekhez a szerepkörökhöz rendelt biztonsági tagok kulcsengedélyekkel rendelkeznek a keresési szolgáltatáshoz.
Elővigyázatosságból ellenőrizze a Klasszikus rendszergazdák lapot is annak megállapításához, hogy a rendszergazdák és a társadminisztrátorok rendelkeznek-e hozzáféréssel.