Indicizzare i dati di Archiviazione BLOB di Azure

Articolo
03/18/2024

Questo articolo illustra come configurare un indicizzatore che importa contenuto da Archiviazione BLOB di Azure e lo rende ricercabile in Ricerca di intelligenza artificiale di Azure. Gli input per l'indicizzatore sono i BLOB, in un singolo contenitore. L'output è un indice di ricerca con contenuto ricercabile e metadati archiviati in singoli campi.

Questo articolo integra Creare un indicizzatore con informazioni specifiche per l'Archiviazione BLOB. Usa le API REST per illustrare un flusso di lavoro in tre parti comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione dei dati si verifica quando si invia la richiesta Crea indicizzatore.

Gli indicizzatori BLOB vengono spesso usati sia per l'arricchimento tramite intelligenza artificiale che per l'elaborazione basata su testo. Questo articolo è incentrato sugli indicizzatori per l'indicizzazione basata su testo, in cui vengono inseriti solo il contenuto testuale e i metadati per scenari di ricerca full-text.

Prerequisiti

Archiviazione BLOB di Azure, prestazioni Standard (utilizzo generico v2).
I livelli di accesso per i BLOB Archiviazione includono accesso frequente, sporadico e archivio. È possibile accedere solo agli indicizzatori di ricerca ad accesso frequente e sporadico.
BLOB che forniscono contenuto di testo e metadati. Se i BLOB contengono contenuto binario o testo non strutturato, è consigliabile aggiungere l'arricchimento tramite intelligenza artificiale per l'elaborazione di immagini e linguaggio naturale. Il contenuto del BLOB non può superare i limiti dell'indicizzatore per il livello di servizio di ricerca.
Configurazione di rete e accesso ai dati supportati. Sono necessarie almeno le autorizzazioni di lettura in Archiviazione di Azure. Un stringa di connessione di archiviazione che include una chiave di accesso consente di accedere in lettura al contenuto di archiviazione. Se invece si usano account di accesso e ruoli di Microsoft Entra, assicurarsi che l'identità gestita del servizio di ricerca abbia Archiviazione autorizzazioni di lettura dati BLOB.

Per impostazione predefinita, sia la ricerca che l'archiviazione accettano richieste da indirizzi IP pubblici. Se la sicurezza di rete non è un problema immediato, è possibile indicizzare i dati BLOB usando solo le autorizzazioni di stringa di connessione e lettura. Quando si è pronti ad aggiungere protezioni di rete, vedere Accesso dell'indicizzatore al contenuto protetto dalle funzionalità di sicurezza di rete di Azure per indicazioni sull'accesso ai dati.
Usare un client REST per formulare chiamate REST simili a quelle illustrate in questo articolo.

Formati di documento supportati

L'indicizzatore BLOB può estrarre il testo dai formati di documento seguenti:

CSV (vedere Indicizzazione di BLOB CSV)
EML
EPUB
GZ
HTML
JSON (vedere Indicizzazione di BLOB JSON)
KML (XML per le rappresentazioni geografiche)
Formati di Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPTM, MSG (messaggi di posta elettronica di Outlook), XML (xml sia 2003 che 2006 WORD XML)
Formati di documento aperti: ODT, ODS, ODP
PDF
File di testo normale (vedere anche Indicizzazione di testo normale)
RTF
XML
ZIP

Determinare i BLOB da indicizzare

Prima di configurare l'indicizzazione, esaminare i dati di origine per determinare se devono essere apportate in anticipo eventuali modifiche. Un indicizzatore può indicizzare il contenuto da un contenitore alla volta. Per impostazione predefinita, tutti i BLOB nel contenitore vengono elaborati. Sono disponibili diverse opzioni per un'elaborazione più selettiva:

Posizionare i BLOB in una cartella virtuale. Una definizione di origine dati dell'indicizzatore include un parametro "query" che può accettare una cartella virtuale. Se si specifica una cartella virtuale, vengono indicizzati solo i BLOB nella cartella .
Includere o escludere BLOB per tipo di file. L'elenco dei formati di documento supportati consente di determinare quali BLOB escludere. Ad esempio, è possibile escludere file di immagine o audio che non forniscono testo ricercabile. Questa funzionalità viene controllata tramite le impostazioni di configurazione nell'indicizzatore.

Includere o escludere BLOB arbitrari. Se si vuole ignorare un BLOB specifico per qualsiasi motivo, è possibile aggiungere le proprietà e i valori di metadati seguenti ai BLOB in BLOB Archiviazione. Quando un indicizzatore rileva questa proprietà, ignora il BLOB o il relativo contenuto nell'esecuzione dell'indicizzazione.

Nome della proprietà	Valore proprietà	Spiegazione
"AzureSearch_Skip"	`"true"`	Indica all'indicizzatore BLOB di ignorare completamente il BLOB. Non verrà tentata l'estrazione dei metadati né del contenuto. È utile quando un determinato BLOB ha ripetutamente esito negativo e interrompe il processo di indicizzazione.
"AzureSearch_SkipContent"	`"true"`	Ignora il contenuto ed estrae solo i metadati. equivale all'impostazione `"dataToExtract" : "allMetadata"` descritta in Impostazioni di configurazione , con ambito limitato a un BLOB specifico.

Se non si configurano criteri di inclusione o esclusione, l'indicizzatore segnala un BLOB non idoneo come errore e spostarsi. Se si verificano errori sufficienti, l'elaborazione potrebbe interrompersi. È possibile specificare la tolleranza di errore nelle impostazioni di configurazione dell'indicizzatore.

Un indicizzatore crea in genere un documento di ricerca per BLOB, in cui il contenuto di testo e i metadati vengono acquisiti come campi ricercabili in un indice. Se i BLOB sono interi file, è possibile analizzarli in più documenti di ricerca. Ad esempio, è possibile analizzare le righe in un file CSV per creare un documento di ricerca per riga.

Documento composto o incorporato,ad esempio un archivio ZIP, un documento di Word con posta elettronica di Outlook incorporata contenente allegati o un oggetto . Anche il file MSG con allegati) viene indicizzato come singolo documento. Ad esempio, tutte le immagini estratte dagli allegati di un oggetto . Il file MSG verrà restituito nel campo normalized_images. Se si hanno immagini, è consigliabile aggiungere l'arricchimento tramite intelligenza artificiale per ottenere più utilità di ricerca da tale contenuto.

Il contenuto testuale di un documento viene estratto in un campo stringa denominato "content". È anche possibile estrarre metadati standard e definiti dall'utente.

Indicizzazione di metadati BLOB

I metadati dei BLOB possono anche essere indicizzati ed è utile se si ritiene che una delle proprietà dei metadati standard o personalizzate sia utile nei filtri e nelle query.

Le proprietà dei metadati specificate dall'utente vengono estratte in verbatim. Per ricevere i valori, è necessario definire il campo nell'indice di ricerca di tipo Edm.String, con lo stesso nome della chiave di metadati del BLOB. Ad esempio, se un BLOB ha una chiave di metadati di Sensitivity con valore High, è necessario definire un campo denominato Sensitivity nell'indice di ricerca e verrà popolato con il valore High.

Le proprietà dei metadati blob standard possono essere estratte in campi denominati e tipizzato in modo analogo, come indicato di seguito. L'indicizzatore BLOB crea automaticamente mapping di campi interni per queste proprietà dei metadati BLOB, convertendo il nome sillabato originale ("metadata-storage-name") in un nome equivalente con caratteri di sottolineatura ("metadata_storage_name").

È comunque necessario aggiungere i campi con caratteri di sottolineatura alla definizione dell'indice, ma è possibile omettere i mapping dei campi perché l'indicizzatore rende automaticamente l'associazione.

metadata_storage_name (Edm.String): nome del file del BLOB. Se, ad esempio, è presente un BLOB /my-container/my-folder/subfolder/resume.pdf, il valore di questo campo è resume.pdf.
metadata_storage_path (Edm.String): URI completo del BLOB, incluso l'account di archiviazione. Ad esempio, https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String): tipo di contenuto specificato dal codice usato per caricare il BLOB. Ad esempio: application/octet-stream.
metadata_storage_last_modified (Edm.DateTimeOffset): timestamp dell'ultima modifica per il BLOB. Ricerca di intelligenza artificiale di Azure usa questo timestamp per identificare i BLOB modificati, per evitare di reindicizzare tutti gli elementi dopo l'indicizzazione iniziale.
metadata_storage_size (Edm.Int64): dimensioni del BLOB in byte.
metadata_storage_content_md5 (Edm.String): hash MD5 del contenuto del BLOB, se disponibile.
metadata_storage_sas_token (Edm.String): token di firma di accesso condiviso temporaneo che può essere usato dalle competenze personalizzate per ottenere l'accesso al BLOB. Questo token non deve essere archiviato per un uso successivo perché potrebbe scadere.

Infine, tutte le proprietà dei metadati specifiche del formato documento dei BLOB indicizzati possono essere rappresentate anche nello schema dell'indice. Per altre informazioni sui metadati specifici del contenuto, vedere Proprietà dei metadati del contenuto.

È importante sottolineare che non è necessario definire i campi per tutte le proprietà precedenti nell'indice di ricerca. È sufficiente acquisire le proprietà necessarie per l'applicazione.

Attualmente, l'indicizzazione dei tag di indice BLOB non è supportata da questo indicizzatore.

Definire l'origine dati

La definizione dell'origine dati specifica i dati da indicizzare, credenziali e criteri per identificare le modifiche nei dati. Un'origine dati viene definita come risorsa indipendente in modo che possa essere usata da più indicizzatori.

Creare o aggiornare un'origine dati per impostarne la definizione:

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

Impostare "type" su "azureblob" (obbligatorio).
Impostare "credentials" su un Archiviazione di Azure stringa di connessione. Nella sezione successiva vengono descritti i formati supportati.
Impostare "container" sul contenitore BLOB e usare "query" per specificare eventuali sottocartelle.

Una definizione di origine dati può includere anche criteri di eliminazione temporanea, se si desidera che l'indicizzatore elimini un documento di ricerca quando il documento di origine viene contrassegnato per l'eliminazione.

Credenziali supportate e stringa di connessione

Gli indicizzatori possono connettersi a un contenitore BLOB usando le connessioni seguenti.

Stringa di connessione dell'account di archiviazione con accesso completo
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
È possibile ottenere il stringa di connessione dalla pagina dell'account Archiviazione in portale di Azure selezionando Chiavi di accesso nel riquadro di spostamento a sinistra. Assicurarsi di selezionare un stringa di connessione completo e non solo una chiave.

Identità gestita stringa di connessione
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Questo stringa di connessione non richiede una chiave dell'account, ma è necessario aver configurato in precedenza un servizio di ricerca per la connessione usando un'identità gestita.

Archiviazione firma di accesso condiviso dell'account** (SAS) stringa di connessione
`{ "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;" }`
La firma di accesso condiviso deve avere le autorizzazioni per le operazioni di elenco e lettura per i contenitori e gli oggetti (BLOB).

Firma di accesso condiviso del contenitore
`{ "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;" }`
La firma di accesso condiviso deve avere le autorizzazioni per le operazioni di elenco e lettura sul contenitore. Per altre informazioni, vedere Uso delle firme di accesso condiviso.

Nota

Se si usano le credenziali di firma di accesso condiviso, sarà necessario aggiornare periodicamente le credenziali dell'origine dati con firme rinnovate per impedire che scadano. Se le credenziali di firma di accesso condiviso scadono, l'indicizzatore avrà esito negativo con un messaggio di errore simile a "Le credenziali fornite nella stringa di connessione non sono valide o sono scadute".

Aggiungere campi di ricerca a un indice

In un indice di ricerca aggiungere campi per accettare il contenuto e i metadati dei BLOB di Azure.

Creare o aggiornare un indice per definire i campi di ricerca che archivieranno contenuto e metadati BLOB:

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 },        
    ]
}

Creare un campo chiave documento ("chiave": true). Per il contenuto BLOB, i candidati migliori sono le proprietà dei metadati.
- metadata_storage_path (impostazione predefinita) percorso completo dell'oggetto o del file. Il campo chiave ("ID" in questo esempio) verrà popolato con valori di metadata_storage_path perché è l'impostazione predefinita.
- metadata_storage_name, utilizzabile solo se i nomi sono univoci. Se si vuole usare questo campo come chiave, passare "key": true a questa definizione di campo.
- Proprietà dei metadati personalizzata aggiunta ai BLOB. Questa opzione richiede che il processo di caricamento del BLOB aggiunga la proprietà dei metadati a tutti i BLOB. Poiché la chiave è una proprietà obbligatoria, gli eventuali BLOB che mancano di un valore non verranno indicizzati. Se si usa una proprietà di metadati personalizzata come chiave, evitare di apportare modifiche a tale proprietà. Gli indicizzatori aggiungeranno documenti duplicati per lo stesso BLOB se la proprietà della chiave cambia.
Le proprietà dei metadati includono spesso caratteri, ad esempio / e -, che non sono validi per le chiavi del documento. Poiché l'indicizzatore ha una proprietà "base64EncodeKeys" (true per impostazione predefinita), codifica automaticamente la proprietà dei metadati, senza alcuna configurazione o mapping dei campi richiesto.
Aggiungere un campo "content" per archiviare il testo estratto da ogni file tramite la proprietà "content" del BLOB. Non è necessario usare questo nome, ma in questo modo è possibile sfruttare i mapping dei campi impliciti.
Aggiungere campi per le proprietà dei metadati standard. L'indicizzatore può leggere le proprietà dei metadati personalizzate, le proprietà dei metadati standard e le proprietà dei metadati specifiche del contenuto.

Configurare ed eseguire l'indicizzatore BLOB

Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti di runtime. È anche possibile specificare le parti di un BLOB da indicizzare.

Creare o aggiornare un indicizzatore assegnando un nome e facendo riferimento all'origine dati e all'indice di destinazione:

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" : [ ]
}

Impostare batchSize se il valore predefinito (10 documenti) è sottoutilizzabile o sovraccarico delle risorse disponibili. Le dimensioni batch predefinite sono specifiche dell'origine dati. L'indicizzazione BLOB imposta le dimensioni batch a 10 documenti in riconoscimento delle dimensioni medie del documento maggiori.
In "configurazione", controllare quali BLOB vengono indicizzati in base al tipo di file o lasciare non specificati per recuperare tutti i BLOB.

Per "indexedFileNameExtensions"specificare un elenco delimitato da virgole di estensioni di file (con un punto iniziale). Eseguire la stessa operazione per "excludedFileNameExtensions" per indicare quali estensioni devono essere ignorate. Se la stessa estensione si trova in entrambi gli elenchi, verrà esclusa dall'indicizzazione.
In "configurazione", impostare "dataToExtract" per controllare le parti dei BLOB indicizzate:
- "contentAndMetadata" specifica che tutti i metadati e il contenuto testuale estratti dal BLOB vengono indicizzati. Questo è il valore predefinito.
- "storageMetadata" specifica che vengono indicizzate solo le proprietà del BLOB standard e i metadati specificati dall'utente.
- "allMetadata" specifica che le proprietà del BLOB standard e i metadati per i tipi di contenuto trovati vengono estratti dal contenuto del BLOB e indicizzati.
In "configuration" impostare "parsingMode". La modalità di analisi predefinita è un documento di ricerca per BLOB. Se i BLOB sono testo normale, è possibile ottenere prestazioni migliori passando all'analisi di testo normale. Se è necessaria un'analisi più granulare che esegue il mapping dei BLOB a più documenti di ricerca, specificare una modalità diversa. L'analisi uno-a-molti è supportata per i BLOB costituiti da:
- Documenti JSON
- File CSV
Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo o se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

Nell'indicizzazione BLOB è spesso possibile omettere i mapping dei campi perché l'indicizzatore dispone del supporto predefinito per il mapping delle proprietà dei metadati e del "contenuto" ai campi denominati e tipizzato in modo analogo in un indice. Per le proprietà dei metadati, l'indicizzatore sostituirà automaticamente i - trattini con caratteri di sottolineatura nell'indice di ricerca.
Per altre informazioni sulle altre proprietà, vedere Creare un indicizzatore . Per l'elenco completo delle descrizioni dei parametri, vedere Parametri di configurazione BLOB nell'API REST.

Un indicizzatore viene eseguito automaticamente quando viene creato. È possibile evitare questo problema impostando "disabilitato" su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.

Controllare lo stato dell'indicizzatore

Per monitorare lo stato dell'indicizzatore e la cronologia di esecuzione, inviare una richiesta Get Indexer Status :To monitor the indexer status and execution history, send a Get Indexer Status request:

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

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe essere simile all'esempio seguente:

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

La cronologia di esecuzione contiene fino a 50 delle esecuzioni completate più di recente, ordinate in ordine cronologico inverso in modo che l'esecuzione più recente venga prima.

Gestione degli errori

Gli errori che si verificano comunemente durante l'indicizzazione includono tipi di contenuto non supportati, contenuto mancante o BLOB sovradimensionati.

Per impostazione predefinita, l'indicizzatore BLOB si arresta non appena rileva un BLOB con un tipo di contenuto non supportato , ad esempio un file audio. È possibile usare il parametro "excludedFileNameExtensions" per ignorare determinati tipi di contenuto. Tuttavia, è possibile eseguire l'indicizzazione per continuare anche se si verificano errori e quindi eseguire il debug di singoli documenti in un secondo momento. Per altre informazioni sugli errori dell'indicizzatore, vedere Indicazioni sulla risoluzione dei problemi relativi all'indicizzatore e errori e avvisi dell'indicizzatore.

Esistono cinque proprietà dell'indicizzatore che controllano la risposta dell'indicizzatore quando si verificano errori.

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

Parametro	Valori validi	Descrizione
"maxFailedItems"	-1, null o 0, numero intero positivo	Continuare l'indicizzazione se si verificano errori in qualsiasi momento di elaborazione, durante l'analisi dei BLOB o durante l'aggiunta di documenti a un indice. Impostare queste proprietà sul numero di errori accettabili. Un valore di consente l'elaborazione `-1` indipendentemente dal numero di errori che si verificano. In caso contrario, il valore è un numero intero positivo.
"maxFailedItemsPerBatch"	-1, null o 0, numero intero positivo	Come sopra, ma usato per l'indicizzazione batch.
"failOnUnsupportedContentType"	true o false	Se l'indicizzatore non è in grado di determinare il tipo di contenuto, specificare se continuare o non eseguire il processo.
"failOnUnprocessableDocument"	true o false	Se l'indicizzatore non è in grado di elaborare un documento di un tipo di contenuto altrimenti supportato, specificare se continuare o non eseguire il processo.
"index Archiviazione MetadataOnlyForOversizedDocuments"	true o false	I BLOB sovradimensionati vengono gestiti come errori per impostazione predefinita. Se si imposta questo parametro su true, l'indicizzatore tenterà di indicizzare i metadati anche se il contenuto non può essere indicizzato. Per i limiti relativi alle dimensioni dei BLOB, vedere Limiti del servizio.