Indexování dat z Azure Data Lake Storage Gen2

Článek
02/19/2024

V tomto článku se dozvíte, jak nakonfigurovat indexer , který importuje obsah z Azure Data Lake Storage (ADLS) Gen2 a umožňuje vyhledávání ve službě Azure AI Search. Vstupy indexeru jsou objekty blob 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 Data Lake 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é.
Objekty blob 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.
Oprávnění ke čtení ve službě Azure Storage Úplný přístup připojovací řetězec obsahuje klíč, který uděluje přístup k obsahu, ale pokud místo toho používáte role Azure, ujistěte se, že spravovaná identita vyhledávací služby má oprávnění Čtenář dat objektů blob služby Storage.
Pomocí klienta REST formulujte volání REST podobně jako volání, která jsou uvedená v tomto článku.

Poznámka:

ADLS Gen2 implementuje model řízení přístupu, který podporuje řízení přístupu na základě role v Azure (Azure RBAC) i seznamy řízení přístupu podobné poSIX (ACL) na úrovni objektu blob. Azure AI Search nepodporuje oprávnění na úrovni dokumentu. Všichni uživatelé mají stejnou úroveň přístupu ke všem prohledávatelným a načítaným obsahu v indexu. Pokud oprávnění na úrovni dokumentu představují požadavek aplikace, zvažte oříznutí zabezpečení jako potenciální řešení.

Podporované formáty dokumentů

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

CSV (viz indexování objektů blob CSV)
EML
EPUB
GZ
HTML
JSON (viz indexování objektů blob JSON)
KML (XML pro geografické reprezentace)
formáty 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
PDF
Soubory ve formátu prostého textu (viz také indexování prostého textu)
RTF
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 objekty blob 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	Vysvětlení
"AzureSearch_Skip"	`"true"`	Dává indexeru objektů blob pokyn, aby objekt blob úplně přeskočil. Metadata ani extrakce obsahu se nepokoušnou. To je užitečné, když se konkrétní objekt blob opakovaně nezdaří a přeruší proces indexování.
"AzureSearch_SkipContent"	`"true"`	Přeskočí obsah a extrahuje jenom metadata. toto je ekvivalentem nastavení popsaného `"dataToExtract" : "allMetadata"` v nastavení konfigurace , které je pouze vymezeno na konkrétní objekt blob.

Pokud nenastavíte kritéria zahrnutí nebo vyloučení, indexer nahlásí opravňující objekt blob jako chybu a přejde 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 je také možné indexovat a to je užitečné, pokud si myslíte, že některé ze standardních nebo vlastních vlastností metadat budou užitečné ve filtrech a dotazech.

Vlastnosti metadat zadaných uživatelem se extrahují doslovně. Chcete-li 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íč Sensitivity metadat s hodnotou High, měli byste definovat pole pojmenované Sensitivity v indexu vyhledávání a naplní se 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 a převede původní název dělení slov ("metadata-storage-name") na podtržítka ekvivalentního názvu ("metadata_storage_name").

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

metadata_storage_name (Edm.String) – název souboru objektu blob. 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ý identifikátor URI 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 Search 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) – hodnota hash MD5 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ů.

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

Nastavte "typ" na "adlsgen2" (povinné).
Nastavte "credentials" připojovací řetězec služby Azure Storage. Následující část popisuje podporované formáty.
Nastavte "container" kontejner objektů blob a pomocí dotazu určete všechny podsložky.

Definice zdroje dat může také zahrnovat zásady obnovitelné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

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

Připojovací řetězec účtu úložiště s úplným přístupem
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Připojovací řetězec můžete získat ze stránky účtu úložiště na webu Azure Portal výběrem přístupových klíčů v levém navigačním podokně. Nezapomeňte vybrat úplný připojovací řetězec a ne jenom klíč.

Připojovací řetězec spravované identity
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Tato připojovací řetězec nevyžaduje klíč účtu, ale dříve jste nakonfigurovali vyhledávací službu pro připojení pomocí spravované identity.

Sdílený přístupový podpis účtu úložiště** (SAS) připojovací řetězec
`{ "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;" }`
Sas by měl mít seznam a oprávnění ke čtení pro kontejnery a objekty (v tomto případě objekty blob).

Poznámka:

Pokud používáte přihlašovací údaje SAS, budete muset přihlašovací údaje ke zdroji dat pravidelně aktualizovat obnovenými podpisy, aby se zabránilo jejich vypršení platnosti. Pokud vyprší platnost přihlašovacích údajů SAS, indexer selže s chybovou zprávou podobnou přihlašovacím údajům zadaným v připojovací řetězec jsou neplatné nebo vypršela platnost.

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.

Vytvořte nebo aktualizujte index a definujte vyhledávací pole, která budou ukládat 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 }     
    ]
}

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é chybí, nebudou indexovány. 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. Protože indexer má vlastnost base64EncodeKeys (true ve výchozím nastavení), automaticky kóduje vlastnost metadat bez nutnosti konfigurace nebo mapování polí.
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í.
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.

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

Nastavte "batchSize", pokud je výchozí (10 dokumentů) buď pod využitím nebo zahlcením dostupných prostředků. 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.
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). "excludedFileNameExtensions" Stejným způsobem označte, která rozšíření by se měla přeskočit. Pokud je stejné rozšíření v obou seznamech, bude vyloučeno z indexování.
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. Tato hodnota je výchozí.
- 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.
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.
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í.
Další informace o dalších vlastnostech najdete v tématu Vytvoření indexeru . Úplný seznam popisů parametrů najdete v tématu Parametry konfigurace objektů blob 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=2023-11-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 provádění obsahuje až 50 naposledy dokončených spuštění, které jsou seřazeny v obráceném chronologickém pořadí tak, aby poslední spuštění bylo první.

Zpracování chyb

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 ochybách

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

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

Parametr	Platné hodnoty	Popis
MaxFailedItems	-1, null nebo 0, kladné celé číslo	Pokračujte v indexování, pokud k chybám dochází v jakémkoli okamžiku zpracování, a to buď při analýze objektů blob, nebo při přidávání dokumentů do indexu. Nastavte tyto vlastnosti na počet přijatelných selhání. Hodnota `-1` umožňuje zpracování bez ohledu na počet výskytů chyb. V opačném případě je hodnota kladné celé číslo.
"maxFailedItemsPerBatch"	-1, null nebo 0, kladné celé číslo	Stejné jako výše, ale používá se k dávkovému indexování.
"failOnUnsupportedContentType"	true nebo false	Pokud indexer nemůže určit typ obsahu, určete, jestli se má úloha pokračovat nebo selhat.
"failOnUnprocessableDocument"	true nebo false	Pokud indexer nemůže zpracovat dokument jiného podporovaného typu obsahu, určete, zda chcete pokračovat nebo selhat úlohu.
"indexStorageMetadataOnlyForOversizedDocuments"	true nebo false	Nadlimitní objekty blob se ve výchozím nastavení považují za chyby. Pokud tento parametr nastavíte na hodnotu true, indexer se pokusí indexovat metadata, i když obsah nelze indexovat. Omezení velikosti objektu blob najdete v tématu Omezení služby.

Omezení

Na rozdíl od indexerů objektů blob nemohou indexery ADLS Gen2 využívat tokeny SAS na úrovni kontejneru pro výčet a indexování obsahu z účtu úložiště. Důvodem je to, že indexer provede kontrolu, která určuje, jestli má účet úložiště povolené hierarchické obory názvů voláním systému souborů – Získání vlastností ROZHRANÍ API. Pro účty úložiště, kde nejsou povolené hierarchické obory názvů, se místo toho zákazníkům doporučuje využít indexery objektů blob k zajištění výkonného výčtu objektů 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.

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: