Indicizzare dati da Archiviazione BLOB di Azure

Questo articolo illustra come configurare un indicizzatore che importa contenuto da Archiviazione BLOB di Azure e lo rende ricercabile in Azure AI Search. 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. Esso usa le API REST per illustrare un flusso di lavoro a tre passaggi comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione di dati si verifica all’invio della 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 indicizzazione basata su testo, nei quali vengono inseriti solo il contenuto testuale e i metadati per scenari di ricerca full-text.

Prerequisiti

• Archiviazione BLOB di Azure, prestazioni Standard (v2 per utilizzo generico).

• I Livelli di accesso includono accesso frequente, sporadico, saltuario e archivio. Gli indicizzatori possono recuperare BLOB in livelli di accesso frequente, sporadico e saltuario.

• 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. Una stringa di connessione di archiviazione che includa 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 disponga delle autorizzazioni di lettura dei dati dei BLOB di archiviazione.

  Per impostazione predefinita, sia la ricerca che l'archiviazione accettano richieste da indirizzi IP pubblici. Se la sicurezza di rete non è una preoccupazione immediata, è possibile indicizzare i dati BLOB usando solo la stringa di connessione e le autorizzazioni di lettura. Quando si è pronti ad aggiungere protezioni di rete, consultare 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 analoghe 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 (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 stabilire 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 di un indicizzatore include un parametro "query" che può accettare una cartella virtuale. Se si specifica una cartella virtuale, solo i BLOB in tale cartella vengono indicizzati.

• Includere o escludere BLOB in base al tipo di file. L'elenco dei formati di documento supportati consente di determinare quali BLOB escludere. Ad esempio, è possibile escludere file 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 desidera, per qualsiasi motivo, ignorare un BLOB specifico, è possibile aggiungere le seguenti proprietà e valori di metadati ai BLOB nell'archiviazione BLOB. Quando un indicizzatore rileva tale 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. Ciò equivale all'impostazione "dataToExtract" : "allMetadata" descritta in Impostazioni di configurazione, con ambito limitato a uno specifico BLOB.

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

Generalmente, un indicizzatore crea un documento di ricerca per ogni BLOB, in cui il contenuto di testo e i metadati vengono acquisiti come campi ricercabili all’interno di 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 ciascuna riga.

Anche un documento composito o incorporato (ad esempio, un archivio ZIP, un documento di Word con una e-mail di Outlook incorporata con allegati o un file .MSG con allegati) viene indicizzato come documento singolo. Ad esempio, tutte le immagini estratte dagli allegati di un file .MSG verranno restituite nel campo normalized_images. Se si dispone di 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

Anche i metadati di BLOB possono essere indicizzati; questa è un’operazione utile se si ritiene che una delle proprietà dei metadati standard o personalizzate possa risultare vantaggiosa in filtri e query.

Le proprietà dei metadati specificate dall'utente vengono estratte letteralmente. 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, che verrà popolato con il valore High.

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

È comunque necessario aggiungere i campi con trattini bassi alla definizione dell'indice, ma è possibile omettere i mapping dei campi, poiché l'indicizzatore esegue l'associazione automaticamente.

• 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 utilizzato per caricare il BLOB. Ad esempio: application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset): timestamp dell'ultima modifica per il BLOB. Azure AI Search usa questo timestamp per identificare i BLOB modificati, in modo da evitare di reindicizzare tutto 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 uso successivo poiché 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, ma solo 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 e credenziali e criteri per identificare modifiche nei dati. Un’origine dati è definita come risorsa indipendente affinché possa essere usata da più indicizzatori.

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

2. Impostare "type" su "azureblob" (obbligatorio).

3. Impostare "credenziali" su una stringa di connessione di Archiviazione di Azure. Nella sezione successiva vengono descritti i formati supportati.

4. 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 e stringhe di connessione supportate

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

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.

1. 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=2024-07-01
   {
       "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. Creare un campo chiave documento ("chiave": true). Per il contenuto di BLOB, le opzioni 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, poiché si tratta dell'impostazione predefinita.

   • metadata_storage_name, utilizzabile solo se i nomi sono univoci. Se si vuole usare questo campo come chiave, trasferire "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 potranno essere indicizzati. Se si usa una proprietà di metadati personalizzata come chiave, evitare di apportare modifiche a tale proprietà. Se la proprietà della chiave viene modificata, gli indicizzatori aggiungeranno documenti duplicati per lo stesso BLOB.

   Le proprietà dei metadati includono spesso caratteri, ad esempio / e -, non validi per le chiavi del documento. Tuttavia, l'indicizzatore codifica automaticamente la proprietà dei metadati della chiave, senza che sia richiesta alcuna configurazione o mapping dei campi.

3. Aggiungere un campo "contenuto" per archiviare il testo estratto da ogni file tramite la proprietà "contenuto" del BLOB. Non è necessario usare questo nome, ma in questo modo è possibile sfruttare i mapping dei campi impliciti.

4. 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 della fase di esecuzione. È inoltre possibile specificare le parti di un BLOB da indicizzare.

1. Creare o aggiornare l'indicizzatore assegnandogli un nome e il riferimento all’origine dati e all'indice di destinazione:

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   {
     "name" : "my-blob-indexer",
     "dataSourceName" : "my-blob-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. Impostare batchSize se il valore predefinito (10 documenti) sottoutilizza o sovraccarica le risorse disponibili. Le dimensioni batch predefinite sono specifiche dell'origine dati. L’indicizzazione dei BLOB limita le dimensioni dei batch a 10 documenti, tenendo in considerazione le dimensioni medie maggiori dei documenti.

3. In "configurazione", controllare quali BLOB vengono indicizzati in base al tipo di file oppure lasciare non specificato per recuperare tutti i BLOB.

   Per "indexedFileNameExtensions", specificare un elenco di estensioni di file delimitato da virgole (precedute da un punto). Eseguire la stessa operazione per "excludedFileNameExtensions" a indicare quali estensioni devono essere ignorate. Se la stessa estensione si trova in entrambi gli elenchi, verrà esclusa dall'indicizzazione.

4. In "configurazione", impostare "dataToExtract" per controllare quali parti dei BLOB siano indicizzate:

   • "contentAndMetadata" specifica che tutti i metadati e il contenuto testuale estratti dal BLOB vengono indicizzati. Questo è il valore predefinito.

   • "storageMetadata" specifica che vengono indicizzati solo i metadati specificati dall'utente e le proprietà BLOB standard.

   • "allMetadata" specifica che le proprietà dei BLOB standard e i metadati per tipi di contenuto trovati vengono estratti dal contenuto del file e indicizzati.

5. In "configurazione", impostare "parsingMode". La modalità di analisi predefinita è un documento di ricerca per BLOB. Se i BLOB consistono in testo normale, è possibile ottenere prestazioni migliori passando all'analisi di testo normale. Se si necessita di un'analisi più granulare che esegua il mapping dei BLOB a più documenti di ricerca, specificare un’altra modalità. L'analisi uno-a-molti è supportata per BLOB che consistono in:

   • Documenti JSON
   • File CSV

6. Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo oppure se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

   Nell'indicizzazione di BLOB, è spesso possibile omettere i mapping dei campi, poiché l'indicizzatore dispone di supporto integrato per il mapping delle proprietà dei metadati e del "contenuto" a campi denominati e tipizzati in modo analogo all’interno di un indice. Per le proprietà dei metadati, l'indicizzatore sostituirà automaticamente i trattini - con trattini bassi nell'indice di ricerca.

7. Per ulteriori informazioni su altre proprietà, vedere Creare un indicizzatore. Per l'elenco completo delle descrizioni dei parametri, vedere API REST.

Un indicizzatore viene eseguito automaticamente al momento della sua creazione. È possibile ovviare a questo problema impostando "disabilitato" su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.

Indicizzazione di dati da più contenitori BLOB di Azure a un singolo indice

Tenere presente che un indicizzatore può indicizzare solo i dati di un singolo contenitore. Se si necessita di indicizzare dati da più contenitori e consolidarli in un singolo indice di ricerca di intelligenza artificiale, è possibile farlo configurando più indicizzatori, tutti indirizzati allo stesso indice. Tenere presente il numero massimo di indicizzatori disponibili per SKU.

Per esemplificare: si considerino due indicizzatori che estraggono dati da due origini dati distinte, denominate my-blob-datasource1 e my-blob-datasource2. Ogni origine dati punta a un contenitore BLOB di Azure diverso, ma entrambi sono diretti allo stesso indice, denominato my-search-index.

Primo esempio di definizione dell'indicizzatore:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Seconda definizione dell'indicizzatore eseguita in parallelo:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Controllare lo stato dell'indicizzatore

Per monitorare lo stato dell'indicizzatore e la cronologia di esecuzione, inviare una richiesta Ottieni stato dell’indicizzatore:

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

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe risultare 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 esecuzioni completate più recenti in ordine cronologico inverso, in modo che l'esecuzione più recente venga visualizzata per 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 viene rilevato un BLOB con un tipo di contenuto non supportato, ad esempio un'immagine. È possibile usare il parametro "excludedFileNameExtensions" per ignorare determinati tipi di contenuto. Tuttavia, si potrebbe voler procedere con l'indicizzazione 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=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

Vedi anche

• Rilevamento di modifiche ed eliminazioni
• Indicizzare set di dati di grandi dimensioni
• Accesso dell'indicizzatore a contenuto protetto dalle funzionalità di sicurezza di rete di Azure