Indexování dat z Azure Blob Storage

Článek
05/18/2023

V tomto článku se dozvíte, jak nakonfigurovat indexer, který importuje obsah z Azure Blob Storage a umožňuje ho prohledávat v Azure Cognitive Search. Vstupy do indexeru jsou vaše objekty blob v jednom kontejneru. Výstup je vyhledávací index s prohledávatelným obsahem a metadaty uloženými v jednotlivých polích.

Tento článek doplňuje vytvoření indexeru informacemi, které jsou specifické pro službu Blob Storage. Pomocí rozhraní REST API předvádí třídílný pracovní postup společný všem indexerům: vytvoření zdroje dat, vytvoření indexu a vytvoření indexeru. K extrakci dat dochází při odeslání požadavku vytvořit indexer.

Indexery objektů blob se často používají jak pro rozšiřování AI , tak pro zpracování textu. Tento článek se zaměřuje na indexery pro indexování založené na textu, kde se pro scénáře fulltextového vyhledávání ingestuje jenom textový obsah a metadata.

Požadavky

Azure Blob Storage, výkon standardu (pro obecné účely v2).
Mezi úrovně přístupu pro blob storage patří Horká, Studená a Archivní. Indexery vyhledávání mají přístup pouze k horkému a studenému.
Objekty blob poskytující textový obsah a metadata Pokud objekty blob obsahují binární obsah nebo nestrukturovaný text, zvažte přidání rozšíření AI pro zpracování obrázků a přirozeného jazyka. Obsah objektů blob nemůže překročit limity indexeru pro vaši úroveň vyhledávací služby.
Podporovaná konfigurace sítě a přístup k datům. Minimálně budete potřebovat oprávnění ke čtení ve službě Azure Storage. Připojovací řetězec úložiště, který obsahuje přístupový klíč, vám poskytne přístup ke čtení obsahu úložiště. Pokud místo toho používáte Azure AD přihlášení a role, ujistěte se, že spravovaná identita vyhledávací služby má oprávnění čtenáře dat v objektech blob služby Storage.

Vyhledávání i úložiště ve výchozím nastavení přijímají požadavky z veřejných IP adres. Pokud zabezpečení sítě není okamžitý problém, můžete indexovat data objektů blob jenom pomocí připojovacího řetězce a oprávnění ke čtení. Až budete připraveni přidat ochranu sítě, pokyny k přístupu k datům najdete v tématu Přístup indexeru k obsahu chráněnému funkcemi zabezpečení sítě Azure .
Pokud chcete formulovat volání REST podobně jako v tomto článku, použijte klienta REST, jako je aplikace Postman.

Podporované formáty dokumentů

Indexer objektů blob může extrahovat text z následujících formátů dokumentů:

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 Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (e-maily Outlooku), XML (2003 i 2006 WORD XML)
Formáty otevřeného dokumentu: ODT, ODS, ODP
PDF
Soubory 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 by se nějaké změny měly udělat předem. Indexer může indexovat obsah z jednoho kontejneru najednou. Ve výchozím nastavení se zpracovávají všechny objekty blob v kontejneru. Máte několik možností pro selektivnější zpracování:

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 jenom objekty blob ve složce.
Zahrňte nebo vylučte 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 nějakého 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 v běhu indexování.

Název vlastnosti	Hodnota vlastnosti	Vysvětlení
"AzureSearch_Skip"	`"true"`	Dá indexeru objektů blob pokyn, aby objekt blob úplně přeskočil. Nepokusí se o extrakci metadat ani obsahu. To je užitečné, když konkrétní objekt blob opakovaně selže a přeruší proces indexování.
"AzureSearch_SkipContent"	`"true"`	Přeskočí obsah a extrahuje jenom metadata. odpovídá nastavení popsanému `"dataToExtract" : "allMetadata"` v nastavení konfigurace , jen s oborem pro konkrétní objekt blob.

Pokud nenastavíte kritéria zahrnutí nebo vyloučení, indexer oznámí nezpůsobilý objekt blob jako chybu a přejde k dalšímu kroku. Pokud dojde k dostatečnému množství chyb, může se zpracování zastavit. Odolnost proti chybám můžete zadat v nastavení konfigurace indexeru.

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

Složený nebo vložený dokument (například archiv ZIP, Word dokument s vloženým outlookovým e-mailem obsahujícím přílohy nebo . Soubor MSG s přílohami) je také indexován jako jeden dokument. Například všechny obrázky extrahované z příloh objektu . Soubor MSG se vrátí v poli normalized_images. Pokud máte obrázky, zvažte přidání rozšíření AI , abyste z tohoto obsahu získali další vyhledávací nástroje.

Textový obsah dokumentu se extrahuje do pole řetězce s názvem "content". Můžete také extrahovat standardní a uživatelem definovaná metadata.

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ě. Abyste získali hodnoty, musíte v indexu vyhledávání definovat pole typu Edm.Stringse stejným názvem jako klíč metadat objektu blob. Pokud má například objekt blob klíč Sensitivity metadat s hodnotou High, měli byste ve vyhledávacím indexu definovat pole s názvem Sensitivity a naplní se hodnotou High.

Standardní vlastnosti metadat objektů blob je možné extrahovat do polí s podobným názvem a typem, 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 s dělením slov ("metadata-storage-name") na ekvivalentní název s podtržítkem ("metadata_storage_name").

Do definice indexu musíte přidat pole s podtržítky, 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 Cognitive Search toto časové razítko používá k identifikaci změněných objektů blob, aby se zabránilo opětovnému indexová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ý můžou vlastní dovednosti použít 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 jeho platnost může vypršet.

A konečně, všechny vlastnosti metadat specifické pro formát dokumentu objektů blob, které indexujete, mohou být také reprezentovány ve schématu indexu. Další informace o metadatech specifických pro obsah najdete v tématu Vlastnosti metadat obsahu.

Je důležité upozornit, že nemusíte definovat pole pro všechny výše uvedené vlastnosti ve vyhledávacím indexu – stačí zachytit vlastnosti, které potřebujete pro vaši aplikaci.

Indexování značek indexu objektů blob tento indexer v současné době nepodporuje.

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 mohlo používat více indexerů.

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

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Nastavte typ na "azureblob" (povinné).
Nastavte "přihlašovací údaje" na připojovací řetězec služby Azure Storage. Další část popisuje podporované formáty.
Nastavte "container" na kontejner objektů blob a pomocí příkazu "query" zadejte všechny podsložky.

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

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

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 Účet úložiště v Azure Portal tak, že v levém navigačním podokně vyberete Přístupové klíče. 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>/;" }`
Tento připojovací řetězec nevyžaduje klíč účtu, ale musíte mít dříve nakonfigurovanou vyhledávací službu, aby se připojila pomocí spravované identity.

Připojovací řetězec sdíleného přístupového podpisu** (SAS) účtu úložiště
`{ "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 oprávnění pro seznam a čtení kontejnerů a objektů (v tomto případě objektů blob).

Sdílený přístupový podpis kontejneru
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
Sas by měl mít v kontejneru oprávnění pro seznam a čtení. Další informace najdete v tématu Používání sdílených přístupových podpisů.

Poznámka

Pokud používáte přihlašovací údaje SAS, budete muset pravidelně aktualizovat přihlašovací údaje ke zdroji dat 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 této: Přihlašovací údaje zadané v připojovacím řetězci jsou neplatné nebo vypršela jejich platnost.

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

Do vyhledávacího indexu 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 objektů blob a metadata:

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
{
    "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řte pole klíče dokumentu ("klíč": true). Pro obsah objektů blob jsou nejlepšími kandidáty vlastnosti metadat.
- metadata_storage_path (výchozí) úplná cesta k objektu nebo souboru. Pole klíče (v tomto příkladu ID) se naplní hodnotami z metadata_storage_path, protože je výchozí.
- metadata_storage_name, použitelné pouze v případě, že jsou názvy jedinečné. Pokud chcete, aby toto pole bylo klíčem, přejděte "key": true k této definici pole.
- Vlastnost vlastních metadat, kterou přidáte do objektů blob. Tato možnost vyžaduje, aby proces nahrávání do objektu blob přidal 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 nepodaří indexovat. Pokud jako klíč použijete vlastní vlastnost metadat, vyhněte se provádění změn této vlastnosti. Indexery přidají duplicitní dokumenty pro stejný objekt blob, pokud se změní vlastnost klíče.
Vlastnosti metadat často obsahují znaky, například / a -, které jsou pro klíče dokumentu neplatné. Vzhledem k tomu, že indexer má vlastnost "base64EncodeKeys" (ve výchozím nastavení true), 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 umožní vám to využívat 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 objektů blob

Po vytvoření indexu a zdroje dat jste připraveni vytvořit indexer. Konfigurace indexeru určuje vstupy, parametry a vlastnosti, které řídí chování za 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:

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-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 , jestli je výchozí (10 dokumentů) nevyužité nebo zahlcení dostupných prostředků. Výchozí velikosti dávek jsou specifické pro zdroj dat. Indexování objektů blob nastaví velikost dávky na 10 dokumentů podle větší průměrné velikosti dokumentu.
V části konfigurace určete, které objekty blob se indexují na základě typu souboru, nebo nechte neurčené, aby se načetly všechny objekty blob.

Pro "indexedFileNameExtensions"zadejte seznam přípon souborů oddělených čárkami (s počáteční tečkou). Stejným "excludedFileNameExtensions" způsobem označte, která rozšíření se mají přeskočit. Pokud je v obou seznamech stejné rozšíření, bude vyloučeno z indexování.
V části konfigurace nastavte dataToExtract a určete, které části objektů blob se budou indexovat:
- ContentAndMetadata určuje, že se budou indexovat všechna metadata a textový obsah extrahovaný z objektu blob. Toto je výchozí hodnota.
- "storageMetadata" určuje, že se indexují pouze standardní vlastnosti objektu blob a metadata zadaná uživatelem .
- AllMetadata určuje, že se z obsahu objektu blob extrahují standardní vlastnosti objektů blob a všechna metadata pro nalezené typy obsahu a indexují se.
V části konfigurace nastavte parsingMode, jestli se mají objekty blob mapovat na více dokumentů hledání nebo jestli se skládají z prostého textu, dokumentů JSON nebo souborů CSV.
Mapování polí zadejte , pokud existují rozdíly v názvu nebo typu pole nebo pokud potřebujete více verzí zdrojového pole v indexu vyhledávání.

Při indexování objektů blob můžete mapování polí často vynechat, protože indexer má integrovanou podporu mapování vlastností obsahu a metadat na pole s podobným názvem a zadáním v indexu. U vlastností metadat indexer automaticky nahradí spojovníky - podtržítky ve vyhledávacím indexu.
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 po vytvoření spustí automaticky. Tomu můžete zabránit nastavením hodnoty zakázáno na hodnotu true. Pokud chcete řídit provádění indexeru, spusťte indexer na vyžádání nebo ho zařaďte podle 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=2020-06-30
  Content-Type: application/json  
  api-key: [admin key]

Odpověď obsahuje 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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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 nejnovější provádění bylo na prvním místě.

Ošetření 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ě velké objekty blob.

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

Existuje pět vlastností indexeru, které řídí odpověď indexeru, když dojde k chybám.

PUT /indexers/[indexer name]?api-version=2020-06-30
{
  "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 při analýze objektů blob nebo při přidávání dokumentů do indexu dojde k chybám. Nastavte tyto vlastnosti na počet přijatelných selhání. Hodnota umožňuje `-1` zpracování bez ohledu na to, k kolika chybám dojde. Jinak 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 má úloha pokračovat nebo selhat.
"failOnUnprocessableDocument"	true nebo false	Pokud indexer nemůže zpracovat dokument jinak podporovaného typu obsahu, určete, jestli má úloha pokračovat, nebo selhat.
"indexStorageMetadataOnlyForOversizedDocuments"	true nebo false	Objekty blob naddimenzované jsou ve výchozím nastavení považovány za chyby. Pokud nastavíte tento parametr na hodnotu true, indexer se pokusí indexovat svá metadata, i když obsah nebude možné indexovat. Omezení velikosti objektu blob najdete v tématu Limity služby.

Další kroky

Teď můžete řídit způsob spuštění indexeru, monitorovat stav nebo naplánovat spuštění indexeru. Následující články se týkají indexerů, které přetahují obsah ze služby Azure Storage: