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

Cikk
04/25/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.

A kulcsalapú hitelesítés az alapértelmezett. Letilthatja, ha a szerepköralapú hitelesítést választja.

Feljegyzés

Rövid megjegyzés a legfontosabb terminológiáról. Az API-kulcs a hitelesítéshez használt GUID. Egy külön kifejezés, a dokumentumkulcs egy egyedi sztring az indexelt tartalomban, amely egyedileg azonosítja a dokumentumokat egy keresési indexben.

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 létrehozásához vagy eléréséhez, vagy bármely más, a Search REST API-kban szereplő kéréshez. 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.

Rendszergazda kulcsok objektumok létrehozásához, módosításához vagy törléséhez használhatók. Rendszergazda kulcsok a GET objektumdefiníciókhoz és rendszerinformációkhoz is használhatók.

A lekérdezési kulcsok általában a lekérdezéseket kibocsátó ügyfélalkalmazások között vannak elosztva.

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 használhatók, például LIST indexek vagy GET szolgáltatásstatisztikák.

Íme egy példa a rendszergazdai API-kulcsok használatára egy index létrehozása iránti kérelemben:

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

Állítson be egy lekérdezéskulcsot a POST kérelemfejlécében vagy a GET URI-jában. A lekérdezési kulcsok a gyűjteményt célzó index/docs műveletekhez használhatók: Dokumentumok keresése, Automatikus kiegészítés, Javaslat vagy GET dokumentum.

Íme egy példa a lekérdezési API-kulcs használatára a keresési dokumentumok (GET) kéréseken:

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

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.

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.

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.

Az API-kulcsok titkosításához nem használható ügyfél által felügyelt kulcstitkosítás . 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.

Ajánlott eljárások

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 .