Indicizzare i dati da File di Azure (anteprima)

Questo articolo illustra come configurare un indexer 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.

Per configurare ed eseguire l'indicizzatore, è possibile usare:

• API REST di anteprima per il servizio di ricerca, qualsiasi versione di anteprima.
• Pacchetto Azure SDK, qualsiasi versione.
• Procedura guidata per importare i dati nel portale di Azure.

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 per 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 simili a quelle illustrate in questo articolo.

Attività supportate

È possibile usare questo indicizzatore per le attività seguenti:

• Indicizzazione dei dati e indicizzazione incrementale: L'indicizzatore può indicizzare i file e i metadati associati dalle tabelle. Rileva i file e i metadati nuovi e aggiornati tramite il rilevamento delle modifiche predefinito. È possibile configurare l'aggiornamento dei dati in base a una pianificazione o su richiesta.
• Rilevamento eliminazione: L'indicizzatore può rilevare le eliminazioni tramite metadati personalizzati.
• L'intelligenza artificiale applicata tramite skillsets:Skillsets è completamente supportata dall'indicizzatore. Sono incluse funzionalità chiave come la vettorizzazione integrata che aggiunge passaggi di incorporamento e suddivisione in blocchi di dati.
• Modalità di analisi: L'indicizzatore supporta le modalità di analisi JSON se si vogliono analizzare matrici o righe JSON in singoli documenti di ricerca. Supporta anche la modalità di analisi Markdown.
• Compatibilità con altre funzionalità: L'indicizzatore è progettato per funzionare senza problemi con altre funzionalità dell'indicizzatore, ad esempio le sessioni di debug, la cache dell'indicizzatore per gli arricchimenti incrementali e l'archivio conoscenze.

Formati di documento supportati

L'indicizzatore 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)
• Markdown
• Microsoft Office formati: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (messaggi di posta elettronica di Outlook), XML (Word XML sia 2003 che 2006)
• Formati di documento aperti: ODT, ODS, ODP
• PDF
• File di testo normale (vedere anche Indicizzazione di testo normale)
• RTF
• XML
• ZIP

Modalità di indicizzazione delle 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.

Un documento composto o incorporato (come un archivio ZIP, un documento Word con un'email di Outlook incorporata contenente allegati o un file .MSG con allegati) viene indicizzato come singolo documento. Ad esempio, tutte le immagini estratte dagli allegati di un file .MSG verranno restituite 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.

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.

È 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=2026-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 "credentials" su la stringa di connessione di Archiviazione di Azure. Nella sezione successiva vengono descritti i formati supportati.

4. Impostare "container" come condivisione file principale 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.

Aggiungere campi di ricerca a un indice

Nell'indice search aggiungere campi per accettare il contenuto e i metadati dei file Azure.

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

   POST /indexes?api-version=2026-04-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 del documento ("chiave": true). Per il contenuto BLOB, i candidati migliori sono le proprietà dei metadati. Le proprietà dei metadati includono spesso caratteri, ad esempio / e -, non validi per le chiavi del documento. L'indicizzatore codifica automaticamente la proprietà dei metadati della chiave, senza alcuna configurazione o mapping dei campi richiesto.

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

   • metadata_storage_name utilizzabile solo se i nomi sono univoci

   • Proprietà di metadati personalizzata che aggiungi 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.

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

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 le mappature interne dei campi per queste proprietà, convertendo i nomi di proprietà con trattini 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. Ad esempio, se si dispone di un file /my-share/my-folder/subfolder/resume.pdf, il valore di questo campo è resume.pdf.
   • metadata_storage_path (Edm.String): l'URI completo del file, incluso l'account di archiviazione. Per 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 usato 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, per evitare di reindicizzare tutti gli elementi 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 SAS temporaneo che può essere usato dalle competenze personalizzate per ottenere l'accesso al file. Questo token non deve essere archiviato per un uso successivo perché potrebbe scadere.

Configurare ed eseguire l'indicizzatore 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 di runtime.

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

   POST /indexers?api-version=2026-04-01
   {
     "name" : "my-file-indexer",
     "dataSourceName" : "my-file-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": 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 di file.

   Se sono presenti entrambi i parametri /indexedFileNameExtensions e excludedFileNameExtensions, Azure AI Search esamina prima indexedFileNameExtensions, 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 o 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 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.

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

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=2026-04-01
  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.

Passaggi successivi

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

• Rilevamento delle modifiche ed eliminazione
• Indicizzare set di dati di grandi dimensioni