Condividi tramite

Indicizzare i dati da File di Azure

  • Articolo

Importante

L'indicizzatore di File di Azure è attualmente disponibile in anteprima pubblica in condizioni supplementari per l'utilizzo. Usare un’API REST di anteprima per creare l'origine dati dell'indicizzatore.

Questo articolo illustra come configurare un indicizzatore che importa contenuto da File di Azure e lo rende ricercabile in Azure AI Search. Gli input per l'indicizzatore sono i file in una singola condivisione. 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'indicizzazione dei file in Archiviazione di Azure. 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.

Prerequisiti

  • File di Azure, livello ottimizzato per le transazioni.

  • Una condivisione file SMB che fornisce il contenuto di origine. Le condivisioni NFS non sono supportate.

  • File contenenti testo. Se si dispone di dati binari, è possibile includere l'arricchimento tramite intelligenza artificiale per l'analisi delle immagini.

  • Autorizzazioni di lettura in Archiviazione di Azure. Una stringa di connessione "accesso completo" include una chiave che concede l'accesso al contenuto.

  • Usare un client REST per formulare chiamate REST analoghe a quelle illustrate in questo articolo.

Formati di documento supportati

L'indicizzatore di File di Azure può estrarre 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

Modalità di indicizzazione di File di Azure

Per impostazione predefinita, la maggior parte dei file viene indicizzata come un singolo documento di ricerca nell'indice, inclusi i file con contenuto strutturato, ad esempio JSON o CSV, indicizzati come un singolo blocco di testo.

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.

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.

È possibile usare 2020-06-30-preview o versione successiva per "type": "azurefile". È consigliabile usare l'API di anteprima più recente.

  1. Creare un'origine dati per impostarne la definizione usando un'API di anteprima per "type": "azurefile".

    POST /datasources?api-version=2024-05-01-preview
{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

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

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

  4. Impostare "contenitore" sulla condivisione file radice 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 una condivisione file usando le connessioni seguenti.

Stringa di connessione dell'account di archiviazione per accesso completo
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
È possibile ottenere la stringa di connessione dalla pagina Account di archiviazione nel portale di Azure selezionando Chiavi di accesso nel riquadro di spostamento sinistro. Assicurarsi di selezionare una stringa di connessione completa e non soltanto una chiave.

Aggiungere campi di ricerca a un indice

Nell’indice di ricerca, aggiungere campi per accettare il contenuto e i metadati dei file di Azure.

  1. Creare o aggiornare un indice per definire i campi di ricerca che conserveranno il contenuto e i metadati dei file.

    POST /indexes?api-version=2023-11-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_path", "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": true, "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. Le proprietà dei metadati includono spesso caratteri, ad esempio / e -, non validi per le chiavi del documento. Essendo dotato di una proprietà "base64EncodeKeys" (true per impostazione predefinita), l’indicizzatore codifica automaticamente la proprietà dei metadati, senza che sia richiesta alcuna configurazione o mapping dei campi.

    • metadata_storage_path (impostazione predefinita) percorso completo dell'oggetto o del file

    • metadata_storage_name, utilizzabile solo se i nomi sono univoci

    • 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.

  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. Nell'indicizzazione dei file, le proprietà dei metadati standard sono le stesse delle proprietà dei metadati BLOB. L'indicizzatore di File di Azure crea automaticamente mapping di campi interni per queste proprietà che converte i nomi di proprietà sillabati in nomi di proprietà con caratteri di sottolineatura. È comunque necessario aggiungere i campi da usare per la definizione dell'indice, ma è possibile omettere la creazione di mapping dei campi nell'origine dati.

    • metadata_storage_name (Edm.String): nome del file. Se, ad esempio, è presente un /my-share/my-folder/subfolder/resume.pdf, il valore di questo campo è resume.pdf.
    • metadata_storage_path (Edm.String): URI completo del file, incluso l'account di archiviazione. Ad esempio, https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
    • metadata_storage_content_type (Edm.String): tipo di contenuto specificato dal codice utilizzato per caricare il file. Ad esempio: application/octet-stream.
    • metadata_storage_last_modified (Edm.DateTimeOffset): timestamp dell'ultima modifica per il file. Azure AI Search usa questo timestamp per identificare i file modificati, in modo da evitare di reindicizzare tutto dopo l'indicizzazione iniziale.
    • metadata_storage_size (Edm.Int64): dimensioni del file in byte.
    • metadata_storage_content_md5 (Edm.String): hash MD5 del contenuto del file, 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 file. Questo token non deve essere archiviato per uso successivo poiché potrebbe scadere.

Configurare ed eseguire l'indicizzatore di File di Azure

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.

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

    POST /indexers?api-version=2023-11-01
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "base64EncodeKeys": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

  2. Nella sezione facoltativa "configurazione" specificare eventuali criteri di inclusione o esclusione. Se non specificato, vengono recuperati tutti i file nella condivisione file.

    Se sono presenti entrambi i parametri indexedFileNameExtensions e excludedFileNameExtensions, Ricerca di intelligenza artificiale di Azure esamina prima indexedFileNameExtensions, quindi in excludedFileNameExtensions. Se la stessa estensione di file è presente in entrambi gli elenchi, verrà esclusa dall'indicizzazione.

  3. 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 dei file è 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 tipizzati in modo analogo in un indice. Per le proprietà dei metadati, l'indicizzatore sostituirà automaticamente i trattini - con trattini bassi nell'indice di ricerca.

  4. Per ulteriori informazioni su altre proprietà, vedere Creare un indicizzatore.

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.

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=2023-11-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.

Passaggi successivi

Ora è possibile eseguire l'indicizzatore, monitorare lo stato o pianificare l'esecuzione dell'indicizzatore. Gli articoli seguenti si applicano agli indicizzatori che eseguono il pull di contenuto da Archiviazione di Azure: