Indexování dat z Azure Data Lake Storage Gen2

Indexer Azure Data Lake Storage Gen2 importuje obsah z Azure Data Lake Storage Gen2 (ADLS Gen2) do indexu Azure AI Vyhledávač. Vstupy do indexovacího modulu jsou blobové objekty v jednom kontejneru. Výstup je index vyhledávání s prohledávatelným obsahem a metadaty uloženými v jednotlivých polích.

Tento článek doplňuje článek o vytvoření indexeru s informacemi specifickými pro indexování z ADLS Gen2. Pomocí rozhraní REST API demonstruje třídílný pracovní postup společný pro všechny indexery: vytvoření zdroje dat, vytvoření indexeru a vytvoření indexeru. Extrakce dat nastane, když odešlete požadavek Create Indexer.

Ukázku kódu v jazyce C# najdete v tématu Index Datové Jezero Gen2 pomocí ID Microsoft Entra na GitHubu.

Požadavky

• ADLS Gen2 s povoleným hierarchickým oborem názvů ADLS Gen2 je k dispozici prostřednictvím Služby Azure Storage. Při nastavování účtu úložiště máte možnost povolit hierarchický obor názvů, uspořádat soubory do hierarchie adresářů a vnořených podadresářů. Povolením hierarchického oboru názvů povolíte ADLS Gen2.

• Úrovně přístupu pro ADLS Gen2 zahrnují horkou, studenou a archivní úroveň. Indexery vyhledávání mají přístup pouze k horké a studené.

• Blob objekty obsahující text Pokud máte binární data, můžete zahrnout rozšiřování AI pro analýzu obrázků. Obsah objektů blob nemůže překročit limity indexeru pro vaši úroveň vyhledávací služby.

  Zacházejte s rozšiřováním zdrojového indexování a AI jako s samostatnými fázemi zpracování. Dovednost nebo externí služba může mít nižší vstupní limit, než je množství obsahu, které může indexer extrahovat. Projděte si referenční článek pro každou dovednost v sadě dovedností.

• Oprávnění ke čtení ve službě Azure Storage Řetězec připojení s úplným přístupem obsahuje klíč, který uděluje přístup k obsahu, pokud ale místo toho používáte role Azure, ujistěte se, že spravovaná identita služby vyhledávání má oprávnění Čtenář dat Storage Blob.

• Pomocí klienta REST formulujte volání REST podobně jako volání, která jsou uvedená v tomto článku.

Omezení

• Na rozdíl od indexerů objektů blob nemůžou indexery ADLS Gen2 používat tokeny SAS na úrovni kontejneru k vytvoření výčtu a indexování obsahu z účtu úložiště. Toto omezení existuje, protože indexer provádí kontrolu, zda má účet úložiště povolený hierarchický obor názvů, voláním rozhraní API Filesystem - Get properties. Pro účty úložiště, kde není povolený hierarchický obor názvů, použijte místo toho indexery blobů, aby se zajistil výkonný výčet blobů.

• Pokud je vlastnost metadata_storage_path mapována na pole klíče indexu, objekty blob nejsou zaručeny, že se při přejmenování adresáře přeindexují. Pokud chcete přeindexovat objekty blob, které jsou součástí přejmenovaných adresářů, aktualizujte LastModified časové razítka pro všechny z nich.

Podporované formáty dokumentů

Indexer ADLS Gen2 může extrahovat text z následujících formátů dokumentu:

• CSV (viz indexování CSV blobů)
• EML
• EPUB
• GZ
• jazyk HTML
• JSON (viz indexování JSON blobů)
• KML (XML pro geografické reprezentace)
• Markdown
• formáty systém systém Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPTM, MSG (e-maily Outlooku), XML (2003 i 2006 WORD XML)
• Formáty otevřených dokumentů: ODT, ODS, ODP
• soubor PDF
• Soubory ve formátu prostého textu (viz také indexování prostého textu)
• RTF
• jazyk XML
• ZIP

Určení objektů blob, které se mají indexovat

Než nastavíte indexování, zkontrolujte zdrojová data a zjistěte, jestli se mají předem provést nějaké změny. Indexer může indexovat obsah z jednoho kontejneru najednou. Ve výchozím nastavení se zpracovávají všechny bloby v kontejneru. Pro selektivní zpracování máte několik možností:

• Umístěte objekty blob do virtuální složky. Definice zdroje dat indexeru obsahuje parametr dotazu, který může převzít virtuální složku. Pokud zadáte virtuální složku, indexují se pouze tyto objekty blob ve složce.

• Zahrnout nebo vyloučit objekty blob podle typu souboru Seznam podporovaných formátů dokumentů vám může pomoct určit, které objekty blob se mají vyloučit. Můžete například chtít vyloučit obrázky nebo zvukové soubory, které neposkytují prohledávatelný text. Tato funkce se řídí nastavením konfigurace v indexeru.

• Zahrnout nebo vyloučit libovolné objekty blob. Pokud chcete konkrétní objekt blob z jakéhokoli důvodu přeskočit, můžete do objektů blob ve službě Blob Storage přidat následující vlastnosti a hodnoty metadat. Když indexer na tuto vlastnost narazí, přeskočí objekt blob nebo jeho obsah při spuštění indexování.

  Název vlastnosti	Hodnota vlastnosti	Explanation
  AzureSearch_Skip	"true"	Dává indexeru pro objekty blob pokyn, aby objekt blob zcela přeskočil. Ani metadata, ani obsah se nepokouší extrahovat. To je užitečné, když se konkrétní objekt blob opakovaně nezdaří a přeruší proces indexování.
  "AzureSearch_PřeskočitObsah"	"true"	Přeskočí obsah a extrahuje jenom metadata. Toto nastavení odpovídá "dataToExtract" : "allMetadata" nastavení popsanému v nastavení konfigurace, ale vztahuje se na konkrétní objekt blob.

Pokud nenastavíte kritéria zahrnutí nebo vyloučení, indexer hlásí neoprávněný blob jako chybu a pokračuje dál. Pokud dojde k dostatečným chybám, zpracování se může zastavit. V nastavení konfigurace indexeru můžete zadat odolnost proti chybám.

Indexer obvykle vytvoří jeden prohledávací dokument na objekt blob, kde se textový obsah a metadata zachytí jako prohledávatelná pole v indexu. Pokud jsou objekty blob celé soubory, můžete je potenciálně analyzovat do více vyhledávacích dokumentů. Můžete například analyzovat řádky v souboru CSV a vytvořit jeden hledaný dokument na řádek.

Indexování metadat objektů blob

Metadata objektů blob můžete indexovat, což je užitečné, pokud si myslíte, že některé ze standardních nebo vlastních vlastností metadat jsou užitečné ve filtrech a dotazech.

Vlastnosti metadat zadaných uživatelem se extrahují doslovně. Pokud chcete získat hodnoty, musíte definovat pole v indexu vyhledávání typu Edm.String se stejným názvem jako klíč metadat objektu blob. Pokud má například objekt blob klíč metadat s názvem Sensitivity hodnota High, měli byste definovat pole pojmenované Sensitivity v indexu vyhledávání, které je naplněno hodnotou High.

Standardní vlastnosti metadat objektů blob je možné extrahovat do podobně pojmenovaných a typových polí, jak je uvedeno níže. Indexer objektů blob automaticky vytvoří mapování interních polí pro tyto vlastnosti metadat objektů blob, přičemž převede původní název s pomlčkami („metadata-storage-name“) na ekvivalentní název s podtržítky („metadata_storage_name“).

Stále potřebujete do definice indexu přidat podtržítka, ale mapování polí můžete vynechat, protože indexer přidružení automaticky provede.

• metadata_storage_name (Edm.String) – název souboru blobu. Pokud máte například objekt blob /my-container/my-folder/podsložku/resume.pdf, hodnota tohoto pole je resume.pdf.

• metadata_storage_path (Edm.String) – úplná URI adresa objektu blob, včetně účtu úložiště. Například https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

• metadata_storage_content_type (Edm.String) – typ obsahu zadaný kódem, který jste použili k nahrání objektu blob. Například: application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset) – časové razítko poslední změny objektu blob. Azure AI Vyhledávač používá toto časové razítko k identifikaci změněných objektů blob, aby se zabránilo přeindexování všeho po počátečním indexování.

• metadata_storage_size (Edm.Int64) – velikost objektu blob v bajtech.

• metadata_storage_content_md5 (Edm.String) – MD5 hash obsahu objektu blob, pokud je k dispozici.

• metadata_storage_sas_token (Edm.String) – dočasný token SAS, který je možné použít vlastními dovednostmi k získání přístupu k objektu blob. Tento token by neměl být uložen pro pozdější použití, protože může vypršet jeho platnost.

Nakonec můžou být všechny vlastnosti metadat specifické pro formát dokumentu objektů blob, které indexujete, reprezentovány také ve schématu indexu. Další informace o metadatech specifických pro obsah naleznete v tématu Vlastnosti metadat obsahu.

Je důležité zdůraznit, že nemusíte definovat pole pro všechny výše uvedené vlastnosti v indexu vyhledávání – stačí zachytávat vlastnosti, které potřebujete pro vaši aplikaci.

Definování zdroje dat

Definice zdroje dat určuje data, která se mají indexovat, přihlašovací údaje a zásady pro identifikaci změn v datech. Zdroj dat je definován jako nezávislý prostředek, aby ho mohl používat více indexerů.

1. Vytvořte nebo aktualizujte zdroj dat a nastavte jeho definici:

   {
       "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. Nastavte "typ" na "adlsgen2" (povinné).

3. Nastavte "credentials" na připojovací řetězec služby Azure Storage. Následující část popisuje podporované formáty.

4. Nastavte "container" kontejner objektů blob a pomocí dotazu určete všechny podsložky.

Definice zdroje dat může také zahrnovat zásady měkkého odstranění, pokud chcete, aby indexer odstranil vyhledávací dokument, když je zdrojový dokument označen příznakem pro odstranění.

Podporované přihlašovací údaje a připojovací řetězec

Indexéři se můžou připojit ke kontejneru objektů blob pomocí následujících připojení.

Přidání vyhledávacích polí do indexu

Do indexu vyhledávání přidejte pole pro příjem obsahu a metadat objektů blob Azure.

1. Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která ukládají obsah a metadata objektů blob:

   {
       "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. Vytvoření pole klíče dokumentu ("key": true) Nejlepšími kandidáty pro obsah objektů blob jsou vlastnosti metadat.

   • metadata_storage_path (výchozí) úplná cesta k objektu nebo souboru. Pole klíče (ID v tomto příkladu) se naplní hodnotami z metadata_storage_path, protože se jedná o výchozí hodnotu.

   • metadata_storage_name, použitelné pouze v případě, že názvy jsou jedinečné. Pokud chcete toto pole použít jako klíč, přejděte "key": true na tuto definici pole.

   • Vlastní vlastnost metadat, kterou přidáte do objektů blob. Tato možnost vyžaduje, aby proces nahrání objektu blob přidal tuto vlastnost metadat do všech objektů blob. Vzhledem k tomu, že klíč je požadovaná vlastnost, všechny objekty blob, kterým chybí hodnota, se nedaří indexovat. Pokud jako klíč použijete vlastní vlastnost metadat, vyhněte se změnám této vlastnosti. Indexery při změně klíčové vlastnosti přidají duplicitní dokumenty pro stejný objekt blob.

   Vlastnosti metadat často obsahují znaky, například / a -, které jsou neplatné pro klíče dokumentu. Indexer automaticky zakóduje klíčovou vlastnost metadat bez nutnosti konfigurace nebo mapování polí.

3. Přidejte pole "content" pro uložení extrahovaného textu z každého souboru prostřednictvím vlastnosti "content" objektu blob. Tento název nemusíte používat, ale můžete tak využít implicitní mapování polí.

4. Přidejte pole pro standardní vlastnosti metadat. Indexer může číst vlastní vlastnosti metadat, standardní vlastnosti metadat a vlastnosti metadat specifických pro obsah.

Konfigurace a spuštění indexeru ADLS Gen2

Po vytvoření indexu a zdroje dat můžete indexer vytvořit. Konfigurace indexeru určuje vstupy, parametry a vlastnosti, které řídí chování doby běhu. Můžete také určit, které části objektu blob se mají indexovat.

1. Vytvořte nebo aktualizujte indexer tak, že ho pojmenujte a odkazujete na zdroj dat a cílový index:

   {
     "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. Nastavte „batchSize“, pokud výchozí hodnota (10 dokumentů) nevyužívá dostupné prostředky dostatečně nebo je přetěžuje. Výchozí velikosti dávek jsou specifické pro zdroj dat. Indexování objektů blob nastavuje dávkovou velikost na 10 dokumentů při rozpoznávání větší průměrné velikosti dokumentu.

3. V části "konfigurace" určete, které objekty blob se indexují na základě typu souboru, nebo ponechte nezadané, aby se načetly všechny objekty blob.

   Zadejte "indexedFileNameExtensions"čárkami oddělený seznam přípon souborů (s úvodní tečkou). Stejným způsobem označte, která rozšíření by se měla přeskočit pro "excludedFileNameExtensions". Pokud je stejné rozšíření v obou seznamech, je vyloučené z indexování.

4. V části "konfigurace" nastavte "dataToExtract", abyste mohli určit, které části objektů blob se indexují:

   • "contentAndMetadata" určuje, že se indexují všechna metadata a textový obsah extrahovaný z objektu blob. Toto je výchozí hodnota.

   • Parametr storageMetadata určuje, že se indexují pouze standardní vlastnosti objektů blob a metadata zadaná uživatelem.

   • AllMetadata určuje, že standardní vlastnosti objektu blob a všechna metadata nalezených typů obsahu se extrahují z obsahu objektu blob a indexují se.

5. V části "konfigurace" nastavte "parsingMode", pokud by se objekty blob měly mapovat na více vyhledávacích dokumentů nebo pokud se skládají z prostého textu, dokumentů JSON nebo souborů CSV.

6. Určete mapování polí, pokud existují rozdíly v názvu nebo typu pole nebo pokud potřebujete v indexu vyhledávání více verzí zdrojového pole.

   Při indexování objektů blob můžete často vynechat mapování polí, protože indexer má integrovanou podporu mapování vlastností obsahu a metadat na podobně pojmenovaná a zapisovaná pole v indexu. U vlastností metadat indexer automaticky nahradí pomlčky - podtržítky v indexu vyhledávání.

7. Další informace o dalších vlastnostech najdete v tématu Vytvoření indexeru . Úplný seznam popisů parametrů najdete v tématu Vytvoření indexeru (REST) v rozhraní REST API.

Indexer se spustí automaticky při jeho vytvoření. Můžete tomu zabránit nastavením "zakázáno" na hodnotu true. Pokud chcete řídit provádění indexeru, spusťte indexer na vyžádání nebo ho umístěte do plánu.

Kontrola stavu indexeru

Pokud chcete monitorovat stav indexeru a historii spuštění, odešlete žádost o získání stavu indexeru:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-01
  Content-Type: application/json  
  api-key: [admin key]

Odpověď zahrnuje stav a počet zpracovaných položek. Měl by vypadat podobně jako v následujícím příkladu:

    {
        "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
        ]
    }

Historie vykonávání obsahuje až 50 nedávno dokončených vykonání, které jsou seřazeny v obráceném chronologickém pořadí tak, aby nejnovější vykonání bylo první.

Řešte chyby

Mezi chyby, ke kterým běžně dochází během indexování, patří nepodporované typy obsahu, chybějící obsah nebo nadměrné objekty blob.

Ve výchozím nastavení se indexer objektů blob zastaví, jakmile narazí na objekt blob s nepodporovaným typem obsahu (například zvukový soubor). K přeskočení určitých typů obsahu můžete použít parametr "excludedFileNameExtensions". Můžete ale chtít, aby indexování pokračovalo i v případě, že dojde k chybám, a později ladit jednotlivé dokumenty. Další informace o chybách indexeru naleznete v Pokyny k řešení potíží s indexerem a Chyby a upozornění indexeru.

Existuje pět vlastností indexeru, které řídí odpověď indexeru při výskytu chyb.

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Další kroky

Teď můžete spustit indexer, monitorovat stav nebo naplánovat spuštění indexeru. Následující články platí pro indexery, které načítá obsah ze služby Azure Storage:

• Detekce změn a detekce odstranění
• Indexování velkých datových sad
• Ukázka jazyka C#: Indexování Datové Jezero Gen2 pomocí ID Microsoft Entra