Adatok indexelése az Azure Data Lake Storage Gen2-ből

A Azure Data Lake Storage Gen2 indexelő Azure Data Lake Storage Gen2 (ADLS Gen2) tartalmat importál egy Azure AI Keresés indexbe. Az indexelő bemenetei az Ön blobjai, egyetlen tárolóban találhatók. 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 forró, a hűvös és az archívum. Csak a "hot" és "cool" tartalom érhető el keresési indexelők számára.

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

  A forrásindexelést és az AI-bővítést külön feldolgozási fázisként kell kezelni. Egy képesség vagy külső szolgáltatás bemeneti korlátja alacsonyabb lehet, mint az indexelő által kinyerhető tartalom mennyisége. Tekintse meg a készségkészlet minden egyes képességére vonatkozó referenciacikket .

• 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ásrendelkezik Storage Blob Data Reader-engedélyekkel .

• REST-ügyfél használatával a cikkben bemutatottakhoz hasonló REST-hívásokat hozhat létre.

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. Ez a korlátozás azért létezik, mert 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, használjon blobindexelőket a blobok teljesítménybeli számbavételének biztosításához.

• 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 mindegyik LastModified időbélyegét.

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)
• Markdown
• 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
• PDF
• Egyszerű szöveges fájlok (lásd még : Egyszerű szöveg indexelése)
• Rich Text Formátum (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.

  Tulajdonság megnevezése	Tulajdonságérték	Explanation
  AzureSearch_Skip	"true"	Utasítja a blobindexelőt, hogy hagyja ki teljesen a blobot. Sem a metaadatok, sem a tartalom kinyerése nem történik meg. Ez akkor hasznos, ha egy adott blob ismétlődően meghiúsul, és megszakítja az indexelési folyamatot.
  "AzureSearch_SkipContent"	"true"	Kihagyja a tartalmat, és csak a metaadatokat nyeri ki. Ez a beállítás egyenértékű a "dataToExtract" : "allMetadata"konfigurációs beállításokban leírt beállítással, de egy adott blobra vonatkozik.

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, akkor potenciálisan több keresési dokumentumba is elemezhetők. Elemezheti például egy CSV-fájl sorait, hogy soronként egy keresési dokumentumot hozzon létre.

Blob metaadatainak indexelése

Indexelheti a blob metaadatait, ami akkor hasznos, ha úgy gondolja, hogy a standard vagy egyéni metaadat-tulajdonságok bármelyike hasznos 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 adnia egy olyan típusú mezőt a keresési indexben Edm.String , amelynek neve megegyezik a blob metaadatkulcsával. Ha például egy blobnak van egy Sensitivity nevű metaadatkulcsa, amelynek értéke High, akkor a keresési indexben definiálnia kell egy Sensitivity nevű mezőt, amelyet a(z) High értékkel tölt fel.

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áhúzott mezőket az index definíciójához, de a mezőleképezéseket elhagyhatja, mert az indexelő automatikusan elvégzi az összerendelést.

• metadata_storage_name (Edm.String) – a blob fájljának neve. Ha például van egy blob /my-container/my-folder/subfolder/resume.pdf, 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 Keresés 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 indexelendő adatokat, a hitelesítő adatokat és azokat a szabályzatokat, amelyek a változások azonosítására szolgálnak az adatokban. Egy adatforrás független erőforrásként van definiálva, így több indexelő is használhatja.

1. 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>" }
   }
   

2. Állítsa be a "adlsgen2" "type" (típus) értéket (kötelező).

3. Állítsa be "credentials" egy Azure Storage kapcsolati karakterláncra. A következő szakasz a támogatott formátumokat ismerteti.

4. Á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 karakterláncok

Az indexelők az alábbi kapcsolatokkal csatlakozhatnak egy blobtárolóhoz.

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.

1. 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 }     
       ]
   }
   

2. 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) metadata_storage_path értékeivel van 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 blobokat nem lehet indexelni. 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. Az indexelő automatikusan kódolja a kulcs metaadat-tulajdonságát, és nincs szükség konfigurációra vagy mezőleképezésre.

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

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

1. 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,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Állítsa be a "batchSize" értéket, ha az alapértelmezett (10 dokumentum) nem használja vagy túlterheli a rendelkezésre álló erőforrásokat. 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.

3. 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 az indexelésből ki lesz zárva.

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

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

6. 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. Metaadat-tulajdonságok esetén az indexelő automatikusan lecseréli a kötőjeleket - aláhúzásjelekre a keresési indexben.

7. 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át lásd : Indexelő létrehozása (REST) 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=2026-04-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ő.

Hibák kezelése

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=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

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 azoknak az indexelőknek vonatkoznak, amelyek tartalmat húznak le az Azure Storage-ból.

• Változásészlelés és törlésészlelés
• Nagyméretű adathalmazok indexelése
• C# minta: Data Lake Gen2 indexelése a Microsoft Entra ID használatával