Adatok indexelése az Azure Data Lake Storage Gen2-ből
Ebből a cikkből megtudhatja, hogyan konfigurálhat olyan indexelőt, amely tartalmat importál az Azure Data Lake Storage (ADLS) Gen2-ből, és hogyan teszi kereshetővé az Azure AI Searchben. Az indexelő bemenetei a blobok, egyetlen tárolóban. A kimenet egy keresési index, amely az egyes mezőkben tárolt kereshető tartalmakat és metaadatokat tartalmazza.
Ez a cikk kiegészíti az indexelő létrehozását az ADLS Gen2-ből való indexelésre vonatkozó információkkal. A REST API-k segítségével egy háromrészes munkafolyamatot mutat be, amely az összes indexelőre jellemző: adatforrás létrehozása, index létrehozása, indexelő létrehozása. Az adatkinyerés az Indexelő létrehozása kérés elküldésekor történik.
A C# kódmintájáért lásd : Index Data Lake Gen2 a Microsoft Entra ID használatával a GitHubon.
Előfeltételek
ADLS Gen2 , hierarchikus névtér engedélyezve. Az ADLS Gen2 az Azure Storage-on keresztül érhető el. Tárfiók beállításakor engedélyezheti a hierarchikus névteret, a fájlokat könyvtárak és beágyazott alkönyvtárak hierarchiájába rendezheti. A hierarchikus névtér engedélyezésével engedélyezheti az ADLS Gen2-t.
Az ADLS Gen2 hozzáférési szintjei közé tartozik a gyakori elérésű, a ritka elérésű és az archiválás. A keresési indexelők csak a gyakori és a ritka elérésű felhasználók számára érhetők el.
Szöveget tartalmazó blobok. Ha bináris adatokkal rendelkezik, AI-bővítést is használhat képelemzéshez. A blobtartalmak nem léphetik túl a keresési szolgáltatási szint indexelőkorlátait .
Olvasási engedélyek az Azure Storage-ban. A "teljes hozzáférés" kapcsolati sztring tartalmaz egy kulcsot, amely hozzáférést biztosít a tartalomhoz, de ha inkább Azure-szerepköröket használ, győződjön meg arról, hogy a keresési szolgáltatás által felügyelt identitás rendelkezik Storage Blob Data Reader-engedélyekkel.
REST-ügyfél használatával a cikkben bemutatottakhoz hasonló REST-hívásokat hozhat létre.
Feljegyzés
Az ADLS Gen2 egy olyan hozzáférés-vezérlési modellt implementál, amely támogatja az Azure szerepköralapú hozzáférés-vezérlést (Azure RBAC) és a POSIX-szerű hozzáférés-vezérlési listákat (ACL-eket) a blob szintjén. Az Azure AI Search nem támogatja a dokumentumszintű engedélyeket. Minden felhasználó ugyanolyan szintű hozzáféréssel rendelkezik az indexben található összes kereshető és lekérdezhető tartalomhoz. Ha a dokumentumszintű engedélyek alkalmazáskövetelményt jelentenek, fontolja meg a biztonsági vágást potenciális megoldásként.
Támogatott dokumentumformátumok
Az ADLS Gen2 indexelő a következő dokumentumformátumokból tud szöveget kinyerni:
- CSV (lásd : CSV-blobok indexelése)
- EML
- EPUB
- GZ
- HTML
- JSON (lásd : JSON-blobok indexelése)
- KML (XML földrajzi ábrázolásokhoz)
- Microsoft Office-formátumok: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook-e-mailek), XML (2003 és 2006 WORD XML)
- Dokumentumformátumok megnyitása: ODT, ODS, ODP
- Egyszerű szöveges fájlok (lásd még : Egyszerű szöveg indexelése)
- RTF
- XML
- ZIP
Az indexelendő blobok meghatározása
Mielőtt beállítja az indexelést, tekintse át a forrásadatokat, és állapítsa meg, hogy a módosításokat elöl kell-e elvégezni. Az indexelők egyszerre egyetlen tárolóból is indexelhetik a tartalmat. Alapértelmezés szerint a tárolóban lévő összes blob feldolgozása történik. A szelektív feldolgozás több lehetőséggel is rendelkezik:
Helyezze a blobokat egy virtuális mappába. Az indexelő adatforrás-definíciója tartalmaz egy "lekérdezési" paramétert, amely képes virtuális mappát venni. Ha virtuális mappát ad meg, a rendszer csak a mappában lévő blobokat indexeli.
Blobok belefoglalása vagy kizárása fájltípus szerint. A támogatott dokumentumformátumok listája segít meghatározni, hogy mely blobokat kell kizárni. Előfordulhat például, hogy ki szeretné zárni azokat a kép- vagy hangfájlokat, amelyek nem nyújtanak kereshető szöveget. Ezt a képességet az indexelő konfigurációs beállításai vezérlik.
Tetszőleges blobok belefoglalása vagy kizárása. Ha valamilyen okból ki szeretne hagyni egy adott blobot, a Blob Storage-ban a következő metaadat-tulajdonságokat és értékeket adhat hozzá a blobokhoz. Amikor egy indexelő találkozik ezzel a tulajdonságmal, kihagyja a blobot vagy annak tartalmát az indexelési futtatás során.
Ha nem állít be befogadási vagy kizárási feltételeket, az indexelő hibaként jelent egy nem jogosult blobot, és továbblép. Ha elegendő hiba történik, a feldolgozás leállhat. Az indexelő konfigurációs beállításaiban megadhatja a hibatűrést.
Az indexelők általában blobonként egy keresési dokumentumot hoznak létre, ahol a szöveges tartalom és a metaadatok kereshető mezőkként vannak rögzítve egy indexben. Ha a blobok teljes fájlok, több keresési dokumentumba is elemezheti őket. Elemezheti például egy CSV-fájl sorait, hogy soronként egy keresési dokumentumot hozzon létre.
Blob metaadatainak indexelése
A blob metaadatai indexelhetők is, és ez akkor hasznos, ha úgy gondolja, hogy a standard vagy egyéni metaadat-tulajdonságok bármelyike hasznos lesz a szűrőkben és a lekérdezésekben.
A rendszer szó szerint kinyeri a felhasználó által megadott metaadat-tulajdonságokat. Az értékek fogadásához meg kell határoznia a típus keresési indexében Edm.String
lévő mezőt, amelynek neve megegyezik a blob metaadatkulcsával. Ha például egy blob rendelkezik értékekkel rendelkező metaadat-kulccsalSensitivity
, meg kell adnia egy, a keresési indexben elnevezett Sensitivity
mezőt, amely az értékkel High
lesz feltöltve.High
A standard blob metaadat-tulajdonságai az alábbiak szerint hasonló nevű és beírt mezőkbe nyerhetők ki. A blobindexelő automatikusan belső mezőleképezéseket hoz létre ezekhez a blob metaadat-tulajdonságokhoz, és az eredeti kötőjeles nevet ("metadata-storage-name") egy alászúrt egyenértékű névvé ("metadata_storage_name") konvertálja.
Továbbra is hozzá kell adnia az alábecsült mezőket az indexdefinícióhoz, de kihagyhatja a mezőleképezéseket, mert az indexelő automatikusan létrehozza a társításokat.
metadata_storage_name (
Edm.String
) – a blob fájlneve. Ha például blob /my-container/my-folder/subfolder/resume.pdf van, akkor ennek a mezőnek az értéke.resume.pdf
metadata_storage_path (
Edm.String
) - a blob teljes URI-ja, beleértve a tárfiókot is. Például:https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (
Edm.String
) – a blob feltöltéséhez használt kód által megadott tartalomtípus. Például:application/octet-stream
.metadata_storage_last_modified (
Edm.DateTimeOffset
) – a blob utolsó módosított időbélyege. Az Azure AI Search ezzel az időbélyegzővel azonosítja a módosított blobokat, hogy elkerülje a kezdeti indexelés utáni újraindexelést.metadata_storage_size (
Edm.Int64
) – a blob mérete bájtban.metadata_storage_content_md5 (
Edm.String
) – A blobtartalom MD5 kivonata, ha elérhető.metadata_storage_sas_token (
Edm.String
) – Ideiglenes SAS-jogkivonat, amelyet egyéni képességek használhatnak a blobhoz való hozzáféréshez. Ezt a jogkivonatot nem szabad későbbi használatra tárolni, mert előfordulhat, hogy lejár.
Végül az indexelt blobok dokumentumformátumára vonatkozó metaadat-tulajdonságok is megjeleníthetők az indexsémában. A tartalomspecifikus metaadatokról további információt a Tartalom metaadatainak tulajdonságai című témakörben talál.
Fontos kiemelni, hogy nem kell mezőket definiálnia a keresési indexben szereplő összes fenti tulajdonsághoz – csak rögzítse az alkalmazáshoz szükséges tulajdonságokat.
Az adatforrás meghatározása
Az adatforrás definíciója meghatározza az adatok indexeléséhez, hitelesítő adataihoz és szabályzataihoz az adatok változásainak azonosításához. Egy adatforrás független erőforrásként van definiálva, így több indexelő is használhatja.
Adatforrás létrehozása vagy frissítése a definíció beállításához:
{ "name" : "my-adlsgen2-datasource", "type" : "adlsgen2", "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" }, "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" } }
Állítsa be a
"adlsgen2"
"type" (típus) értéket (kötelező).Állítsa be
"credentials"
egy Azure Storage-kapcsolati sztring. A következő szakasz a támogatott formátumokat ismerteti.Állítsa be
"container"
a blobtárolót, és a "lekérdezés" használatával adja meg az almappákat.
Az adatforrás-definíciók tartalmazhatnak helyreállítható törlési szabályzatokat is, ha azt szeretné, hogy az indexelő töröljön egy keresési dokumentumot, amikor a forrásdokumentum törlésre van megjelölve.
Támogatott hitelesítő adatok és kapcsolati sztring
Az indexelők az alábbi kapcsolatokkal csatlakozhatnak egy blobtárolóhoz.
Teljes hozzáférésű tárfiók kapcsolati sztring |
---|
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" } |
A kapcsolati sztring az Azure Portal Tárfiók lapjáról a bal oldali navigációs panel Access-kulcsainak kiválasztásával szerezheti be. Ügyeljen arra, hogy a teljes kapcsolati sztring ne csak egy kulcsot válasszon. |
Felügyelt identitás kapcsolati sztring |
---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" } |
Ez a kapcsolati sztring nem igényel fiókkulcsot, de korábban konfigurálnia kell egy keresési szolgáltatást a felügyelt identitással való csatlakozáshoz. |
Tárfiók megosztott hozzáférésű jogosultságkódja** (SAS) kapcsolati sztring |
---|
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" } |
Az SAS-nek rendelkeznie kell a tárolókra és objektumokra (ebben az esetben blobokra) vonatkozó listával és olvasási engedélyekkel. |
Feljegyzés
Ha SAS-hitelesítő adatokat használ, a lejáratuk megakadályozása érdekében rendszeresen frissítenie kell az adatforrás hitelesítő adatait megújított aláírásokkal. Ha az SAS hitelesítő adatai lejárnak, az indexelő a következőhöz hasonló hibaüzenettel fog meghiúsulni: "A kapcsolati sztring megadott hitelesítő adatok érvénytelenek vagy lejártak".
Keresési mezők hozzáadása indexhez
Egy keresési indexben adjon hozzá mezőket az Azure-blobok tartalmának és metaadatainak elfogadásához.
Hozzon létre vagy frissítsen egy indexet a blobtartalmakat és metaadatokat tároló keresési mezők definiálásához:
{ "name" : "my-search-index", "fields": [ { "name": "ID", "type": "Edm.String", "key": true, "searchable": false }, { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false }, { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }, { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true }, { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true } ] }
Hozzon létre egy dokumentumkulcsmezőt ("key": true). Blobtartalmak esetén a legjobb jelöltek a metaadat-tulajdonságok.
metadata_storage_path
(alapértelmezett) az objektum vagy fájl teljes elérési útja. A kulcsmező ("Azonosító" ebben a példában) a metadata_storage_path értékeivel lesz feltöltve, mert ez az alapértelmezett érték.metadata_storage_name
, csak akkor használható, ha a nevek egyediek. Ha ezt a mezőt szeretné kulcsként használni, lépjen"key": true
erre a meződefinícióra.A blobokhoz hozzáadott egyéni metaadat-tulajdonság. Ehhez a beállításhoz a blobfeltöltési folyamatnak hozzá kell adnia ezt a metaadat-tulajdonságot az összes blobhoz. Mivel a kulcs egy kötelező tulajdonság, az érték nélküli blobok indexelése sikertelen lesz. Ha egyéni metaadat-tulajdonságot használ kulcsként, ne módosítsa a tulajdonságot. Az indexelők duplikált dokumentumokat adnak hozzá ugyanahhoz a blobhoz, ha a kulcstulajdonság megváltozik.
A metaadat-tulajdonságok gyakran tartalmaznak olyan karaktereket, például
/
és-
, amelyek érvénytelenek a dokumentumkulcsokhoz. Mivel az indexelő rendelkezik egy "base64EncodeKeys" tulajdonsággal (alapértelmezés szerint igaz), automatikusan kódolja a metaadat-tulajdonságot, konfiguráció vagy mezőleképezés nélkül.Adjon hozzá egy "content" mezőt az egyes fájlokból kinyert szöveg tárolásához a blob "content" tulajdonságán keresztül. Ezt a nevet nem kell használnia, de így kihasználhatja az implicit mezőleképezések előnyeit.
Adjon hozzá mezőket a szabványos metaadat-tulajdonságokhoz. Az indexelő elolvashatja az egyéni metaadat-tulajdonságokat, a szabványos metaadat-tulajdonságokat és a tartalomspecifikus metaadat-tulajdonságokat .
Az ADLS Gen2 indexelő konfigurálása és futtatása
Az index és az adatforrás létrehozása után készen áll az indexelő létrehozására. Az indexelő konfigurációja meghatározza a futási idő viselkedését vezérlő bemeneteket, paramétereket és tulajdonságokat. Megadhatja azt is, hogy a blob mely részeit indexelje.
Hozzon létre vagy frissítsen egy indexelőt úgy, hogy megad neki egy nevet, és hivatkozik az adatforrásra és a célindexre:
{ "name" : "my-adlsgen2-indexer", "dataSourceName" : "my-adlsgen2-datasource", "targetIndexName" : "my-search-index", "parameters": { "batchSize": null, "maxFailedItems": null, "maxFailedItemsPerBatch": null, "base64EncodeKeys": null, "configuration": { "indexedFileNameExtensions" : ".pdf,.docx", "excludedFileNameExtensions" : ".png,.jpeg", "dataToExtract": "contentAndMetadata", "parsingMode": "default" } }, "schedule" : { }, "fieldMappings" : [ ] }
Állítsa be a "batchSize" értéket, ha az alapértelmezett (10 dokumentum) a rendelkezésre álló erőforrások kihasználása vagy túlterhelése alatt áll. Az alapértelmezett kötegméretek adatforrás-specifikusak. A blobindexelés a kötegméretet 10 dokumentumra állítja a nagyobb átlagos dokumentumméret elismeréseként.
A "konfiguráció" alatt szabályozhatja, hogy mely blobokat indexelje a fájltípus alapján, vagy hagyja meg nem határozottul az összes blob lekéréséhez.
Ehhez
"indexedFileNameExtensions"
adja meg a fájlkiterjesztések vesszővel tagolt listáját (vezető ponttal). Ugyanezzel"excludedFileNameExtensions"
a módszerrel jelezheti, hogy mely bővítményeket kell kihagyni. Ha ugyanaz a bővítmény mindkét listában szerepel, akkor a rendszer kizárja az indexelésből.A "konfiguráció" területen állítsa be a "dataToExtract" értéket a blobok indexelt részeinek szabályozásához:
A "contentAndMetadata" azt határozza meg, hogy a blobból kinyert összes metaadat és szöveges tartalom indexelve legyen. Ez az alapértelmezett érték.
A "storageMetadata" azt határozza meg, hogy csak a standard blobtulajdonságok és a felhasználó által megadott metaadatok legyenek indexelve.
Az "allMetadata" azt határozza meg, hogy a standard blobtulajdonságok és a talált tartalomtípusok metaadatai ki lesznek nyerve a blob tartalmából, és indexelve lesznek.
A "konfiguráció" területen állítsa be a "parsingMode" értéket, ha a blobokat több keresési dokumentumra kell leképezni, vagy ha egyszerű szövegből, JSON-dokumentumokból vagy CSV-fájlokból állnak.
Mezőleképezéseket adhat meg, ha a mezőnév vagy a típus eltérést mutat, vagy ha egy forrásmező több verziójára van szüksége a keresési indexben.
A blobindexelés során gyakran kihagyhatja a mezőleképezéseket, mert az indexelő beépített támogatással rendelkezik a "tartalom" és a metaadat tulajdonságainak az index hasonló nevű és beírt mezőihez való leképezéséhez. A metaadat-tulajdonságok esetében az indexelő automatikusan lecseréli a kötőjeleket
-
aláhúzásjelekre a keresési indexben.További információt az egyéb tulajdonságokról az Indexelő létrehozása című témakörben talál. A paraméterleírások teljes listájáért tekintse meg a Blob konfigurációs paramétereit a REST API-ban.
Az indexelő automatikusan fut a létrehozásakor. Ezt úgy akadályozhatja meg, hogy a "letiltva" értéket igaz értékre állítja. Az indexelő végrehajtásának szabályozásához futtasson egy indexelőt igény szerint , vagy ütemezze.
Az indexelő állapotának ellenőrzése
Az indexelőzmények állapotának és végrehajtási előzményeinek figyeléséhez küldjön egy indexelőzmény-lekéréses kérést:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
Content-Type: application/json
api-key: [admin key]
A válasz tartalmazza az állapotot és a feldolgozott elemek számát. A következő példához hasonlóan kell kinéznie:
{
"status":"running",
"lastResult": {
"status":"success",
"errorMessage":null,
"startTime":"2024-02-21T00:23:24.957Z",
"endTime":"2024-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
"executionHistory":
[
{
"status":"success",
"errorMessage":null,
"startTime":"2024-02-21T00:23:24.957Z",
"endTime":"2024-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
... earlier history items
]
}
A végrehajtási előzmények legfeljebb 50 legutóbbi végrehajtást tartalmaznak, amelyek fordított időrendi sorrendben vannak rendezve, hogy a legújabb végrehajtás legyen az első.
Hibakezelés
Az indexelés során gyakran előforduló hibák közé tartoznak a nem támogatott tartalomtípusok, a hiányzó tartalom vagy a túlméretezett blobok.
Alapértelmezés szerint a blobindexelő leáll, amint nem támogatott tartalomtípussal (például hangfájllal) találkozik. A "excludedFileNameExtensions" paraméter használatával kihagyhat bizonyos tartalomtípusokat. Előfordulhat azonban, hogy azt szeretné, hogy az indexelés akkor is folytatódjon, ha hibák történnek, majd később hibakeresést végezzen az egyes dokumentumokban. Az indexelő hibáival kapcsolatos további információkért tekintse meg az Indexer hibaelhárítási útmutatóját , valamint az Indexelő hibáit és figyelmeztetéseit.
Öt indexelőtulajdonság vezérli az indexelő válaszát hibák esetén.
PUT /indexers/[indexer name]?api-version=2023-11-01
{
"parameters" : {
"maxFailedItems" : 10,
"maxFailedItemsPerBatch" : 10,
"configuration" : {
"failOnUnsupportedContentType" : false,
"failOnUnprocessableDocument" : false,
"indexStorageMetadataOnlyForOversizedDocuments": false
}
}
}
Paraméter | Érvényes értékek | Leírás |
---|---|---|
"maxFailedItems" | -1, null vagy 0, pozitív egész szám | Folytassa az indexelést, ha hibák történnek a feldolgozás bármely pontján, akár blobok elemzésekor, akár dokumentumok indexhez való hozzáadásakor. Állítsa be ezeket a tulajdonságokat az elfogadható hibák számára. A feldolgozás a hibák számától -1 függetlenül lehetővé teszi a feldolgozást. Ellenkező esetben az érték pozitív egész szám. |
"maxFailedItemsPerBatch" | -1, null vagy 0, pozitív egész szám | Ugyanaz, mint a fenti, de kötegelt indexeléshez használatos. |
"failOnUnsupportedContentType" | igaz vagy hamis | Ha az indexelő nem tudja meghatározni a tartalomtípust, adja meg, hogy folytatja-e a feladatot, vagy nem. |
"failOnUnprocessableDocument" | igaz vagy hamis | Ha az indexelő nem tud feldolgozni egy egyébként támogatott tartalomtípusú dokumentumot, adja meg, hogy folytatja-e a feladatot, vagy nem. |
"indexStorageMetadataOnlyForOversizedDocuments" | igaz vagy hamis | A túlméretezett blobokat alapértelmezés szerint hibaként kezeli a rendszer. Ha igaz értékre állítja ezt a paramétert, az indexelő akkor is megpróbálja indexelni a metaadatait, ha a tartalom nem indexelhető. A blob méretére vonatkozó korlátozásokért tekintse meg a szolgáltatás korlátait. |
Korlátozások
A blobindexelőkkel ellentétben az ADLS Gen2-indexelők nem használhatnak tárolószintű SAS-jogkivonatokat a tárfiókból származó tartalmak számbavételéhez és indexeléshez. Ennek az az oka, hogy az indexelő ellenőrzi, hogy a tárfiók hierarchikus névterei engedélyezve vannak-e a Fájlrendszer – Tulajdonságok lekérése API meghívásával. Azon tárfiókok esetében, ahol a hierarchikus névterek nincsenek engedélyezve, az ügyfeleknek inkább blobindexelőket kell használniuk a blobok teljesítménybeli számbavételének biztosítása érdekében.
Ha a tulajdonság
metadata_storage_path
indexkulcsmezőnek van megfeleltetve, a blobok nem garantáltan lesznek újraindexezve a címtár átnevezésekor. Ha újra szeretné indexelni az átnevezett könyvtárak részét képező blobokat, frissítse mindegyikLastModified
időbélyegét.
Következő lépések
Most már futtathatja az indexelőt, figyelheti az állapotot vagy ütemezheti az indexelő végrehajtását. Az alábbi cikkek azOkra az indexelőkre vonatkoznak, amelyek tartalmat kérnek le az Azure Storage-ból:
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: