Megosztás a következőn keresztül:

Csatlakozás az Azure AI Search szolgáltatáshoz kulcsokkal

Az Azure AI Search támogatja a kulcs nélküli és a kulcsalapú hitelesítést a keresési szolgáltatással való kapcsolatokhoz. Az API-kulcs egy egyedi sztring, amely 52 véletlenszerűen generált számból és betűből áll. A forráskódban környezeti változóként vagy alkalmazásbeállításként is megadható a projektben, majd hivatkozhat a változóra a kérelemben.

Fontos

Keresési szolgáltatás létrehozásakor a kulcsalapú hitelesítés az alapértelmezett, de nem ez a legbiztonságosabb lehetőség. Azt javasoljuk, hogy cserélje le szerepköralapú hozzáférésre.

Alapértelmezés szerint engedélyezve

Az új keresési szolgáltatásokban a kulcsalapú hitelesítés az alapértelmezett. 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, és a keresési szolgáltatás úgy van konfigurálva, hogy engedélyezze az API-kulcsokat egy kérésen. Az Azure Portalon a hitelesítés a Kulcsok lapon, a Beállítások területen van megadva. Az API-kulcsok vagy mindkettő támogatja a kulcsokat.

Képernyőkép az Azure Portal Kulcsok lapjáról.

API-kulcsok típusai

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

Típus Engedélyszint Legnagyobb érték Létrehozás
Rendszergazda Teljes hozzáférés (írás-olvasás) az összes tartalomművelethez 2 1 Az Azure Portalon két rendszergazdai kulcs, más néven elsődleges és másodlagos kulcs jön létre a szolgáltatás létrehozásakor, és igény szerint egyedileg újragenerálható.
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.

1 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, az Azure Portalon 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 vezérlősík-(szolgáltatás-) kérelmekhez API-kulcsot vagy Azure-szerepköröket is használhat. API-kulcs használata esetén:

  • A rendszergazdai kulcsok objektumok létrehozásához, módosításához vagy törléséhez használhatók. A rendszergazdai kulcsok a GET objektumdefiníciókhoz és a 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. A rendszergazdai kulcsok a létrehozási-olvasási-frissítési-törlési művelethez, valamint a keresési szolgáltatásnak adott kérésekhez, például a LIST Indexekhez vagy a GET szolgáltatásstatisztikákhoz használható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=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 }
         ]
   }

Á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=2024-07-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.

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:

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.

  1. Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.

  2. A Beállítások területen válassza a Kulcsok lehetőséget a rendszergazdai és lekérdezési kulcsok megtekintéséhez.

Képernyőkép az API-kulcsokat megjelenítő portállapról.

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.

  1. Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.

  2. A Beállítások területen válassza a Kulcsok lehetőséget az API-kulcsok megtekintéséhez.

  3. 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.

    Képernyőkép a lekérdezéskulcs kezelési beállításairól.

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.

  1. A Beállítások területen válassza a Kulcsok lehetőséget, majd másolja a másodlagos kulcsot.

  2. Minden alkalmazás esetében frissítse az API-kulcs beállításait a másodlagos kulcs használatára.

  3. Hozza létre újra az elsődleges kulcsot.

  4. 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ás továbbra is elérhető az Azure Portalon 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.

  1. Lépjen a keresési szolgáltatás lapjára az Azure Portalon.

  2. A bal oldali panelen válassza a Hozzáférés-vezérlés (IAM) lehetőséget, majd a Szerepkör-hozzárendelések lapot.

  3. 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.

  4. 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

  • É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 .

  • 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.

  • HA API-kulcsot használ, biztonságosan tárolja valahol máshol, például az Azure Key Vaultban. Ne foglalja bele közvetlenül az API-kulcsot a kódba, és soha ne tegye közzé nyilvánosan.

  • A közzététel előtt mindig ellenőrizze a kódot, a mintákat és a betanítási anyagokat, hogy véletlenül ne tegye elérhetővé az API-kulcsot.

Lásd még