Csatlakozás az Azure AI Search szolgáltatáshoz kulcsokkal
Az Azure AI Search kulcsalapú hitelesítést biztosít 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. 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.
Lecserélheti szerepköralapú hozzáférésre, ami szükségtelenné teszi a kódbázisban lévő merevlemez-kulcsok használatát.
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 1 | 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. |
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, 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.
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:
- Tulajdonos
- Közreműködő
- Keresési szolgáltatás közreműködője
- Rendszergazda é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 Beállítások területen válassza a Kulcsok lehetőséget a rendszergazdai és lekérdezési kulcsok megtekintéséhez.
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 Beállítások területen válassza a Kulcsok lehetőséget az 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.
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 Beállítások 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 .