Indicizzare dati da Archiviazione BLOB di Azure

Annotazioni

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Importante

Queste funzionalità e caratteristiche supportano la connessione ad altri servizi Microsoft e a servizi di terze parti. L'utilizzo di questi servizi è soggetto alle rispettive condizioni e potrebbe comportare l'elaborazione o l'archiviazione dei dati al di fuori del limite di conformità Azure, nonché il flusso dei dati nel limite di conformità Azure.

È tua responsabilità gestire l'eventuale trasferimento dei tuoi dati al di fuori dei confini di conformità e geografici della tua organizzazione e le relative implicazioni, nonché garantire che siano predisposte le autorizzazioni, i limiti e le approvazioni appropriati.

L'utente è responsabile di esaminare e testare attentamente le applicazioni compilate nel contesto dei casi d'uso specifici e di prendere tutte le decisioni e le personalizzazioni appropriate. Ciò include l'implementazione di mitigazioni di intelligenza artificiale responsabili, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza, e garantire che le applicazioni soddisfino gli standard di qualità, affidabilità, sicurezza e attendibilità appropriati. Per altre informazioni, vedere la nota sulla trasparenza Azure AI Search.

L'indicizzatore BLOB importa contenuto da Archiviazione BLOB di Azure e lo rende ricercabile in Azure AI Search. L'indicizzatore riceve i BLOB in un singolo contenitore come input. L'output è un indice di ricerca che archivia contenuto e metadati ricercabili in singoli campi.

Questo articolo usa le API REST del servizio di ricerca per illustrare come configurare ed eseguire l'indicizzatore. Tuttavia, è anche possibile usare:

Annotazioni

Azure AI Search può inserire l'ambito del controllo degli accessi in base al ruolo durante l'indicizzazione e trasferire tali autorizzazioni al contenuto indicizzato in un indice di ricerca. Per altre informazioni, vedere Usare un indicizzatore BLOB o una fonte di conoscenza per inserire i metadati degli ambiti di controllo degli accessi in base al ruolo (anteprima).

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 piano tariffario.

    I limiti dell'indicizzatore BLOB coprono le dimensioni massime del BLOB e il numero di caratteri che Azure AI Search estraggono da un BLOB. Se si usa un set di competenze, il limite di input o di servizio di ogni competenza viene applicato separatamente dopo il cracking del documento.

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

Attività supportate

È possibile usare questo indicizzatore per le attività seguenti:

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)
  • Markdown
  • 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 determinare se è necessario apportare modifiche. Un indicizzatore può indicizzare il contenuto da un contenitore alla volta. Per impostazione predefinita, l'indicizzatore elabora tutti i BLOB nel contenitore. 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 query parametro che può accettare una cartella virtuale. Se si specifica una cartella virtuale, l'indicizzatore indicizza solo i BLOB nella cartella .

  • 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. È possibile controllare questa funzionalità tramite le impostazioni di configurazione nell'indicizzatore.

  • Includere o escludere BLOB arbitrari. Per saltare un BLOB specifico, aggiungere le seguenti proprietà e valori dei metadati ai BLOB in Archiviazione BLOB di Azure. Quando un indicizzatore rileva tale proprietà, ignora il BLOB o il relativo contenuto nell'esecuzione dell'indicizzazione.

    Nome della proprietà Il valore della proprietà Explanation
    AzureSearch_Skip true Indica all'indicizzatore BLOB di ignorare completamente il BLOB. L'indicizzatore non tenta di estrarre metadati o contenuto. Questa proprietà è utile quando un blob specifico ha esito negativo ripetutamente e interrompe il processo di indicizzazione.
    AzureSearch_SkipContent true L'indicizzatore ignora il contenuto ed estrae solo i metadati. Questa proprietà equivale all'impostazione "dataToExtract": "allMetadata" descritta nelle impostazioni di configurazione, ma ha come ambito un BLOB specifico.

Se non si configurano criteri di inclusione o esclusione, l'indicizzatore segnala un blob non idoneo come errore e passa oltre. 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 vengono restituite nel normalized_images campo. Se si dispone di immagini, è consigliabile aggiungere l'arricchimento tramite intelligenza artificiale per ottenere più utilità di ricerca da tale contenuto.

L'indicizzatore estrae il contenuto testuale di un documento in un campo stringa denominato content. È anche possibile estrarre metadati standard e definiti dall'utente.

Indicizzazione di metadati BLOB

È possibile indicizzare i metadati dei BLOB insieme al contenuto. L'indicizzatore estrae le proprietà dei metadati e le archivia nei campi di indice, utile per la creazione di filtri e query.

Definire i campi nell'indice di ricerca per le proprietà dei metadati da acquisire. Non è necessario definire ogni proprietà di metadati standard o personalizzata disponibile. È sufficiente acquisire le proprietà delle quali hai bisogno per la tua applicazione.

Attualmente, questo indicizzatore non supporta l'indicizzazione dei tag di indice BLOB.

Importante

L'indicizzatore popola solo i campi di metadati già definiti nell'indice di ricerca. Questo requisito si applica sia ai metadati BLOB standard che ai metadati personalizzati. Se un campo non è definito, il valore dei metadati viene estratto durante l'indicizzazione ma ignorato automaticamente, quindi non viene visualizzato nei risultati della ricerca. Questa è l'origine più comune dei campi di metadati Null nei risultati della ricerca. Per ulteriori informazioni, vedere I campi dei metadati sono nulli nei risultati della ricerca.

Proprietà standard dei metadati dei blob

Per i metadati BLOB standard, definire i campi nell'indice usando gli stessi nomi con caratteri di sottolineatura. Per esempi di definizione dei campi passo passo, vedere Aggiungere campi di ricerca a un indice.

Per la configurazione dell'indicizzatore, inclusa l'impostazione dataToExtract che controlla i metadati da estrarre, vedere Configurare ed eseguire l'indicizzatore BLOB.

L'indicizzatore riconosce e può eseguire il mapping di queste proprietà di metadati standard se si definiscono i campi corrispondenti nell'indice:

  • metadata_storage_name (Edm.String) è il nome file del BLOB. Ad esempio, se si dispone di un BLOB /my-container/my-folder/subfolder/resume.pdf, il valore di questo campo è resume.pdf.

  • metadata_storage_path (Edm.String) è l'URI completo del BLOB, incluso l'account di archiviazione. Ad esempio: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf. Usa questa proprietà per includere gli URL di BLOB nei risultati di ricerca per la navigazione o l'attribuzione della fonte.

  • metadata_storage_content_type (Edm.String) è il tipo di contenuto specificato dal codice usato per caricare il BLOB. Ad esempio: application/octet-stream.

  • metadata_storage_last_modified (Edm.DateTimeOffset) è il timestamp dell'ultima modifica per il BLOB. Azure AI Search usa questo timestamp per identificare i BLOB modificati ed evitare di reindicizzare tutti gli elementi dopo l'indicizzazione iniziale.

  • metadata_storage_size (Edm.Int64) è la dimensione del BLOB in byte.

  • metadata_storage_content_md5 (Edm.String) è l'hash MD5 del contenuto del BLOB, se disponibile.

  • metadata_storage_sas_token (Edm.String) è un token di firma di accesso condiviso temporaneo che le competenze personalizzate possono usare per ottenere l'accesso al BLOB. Non archiviare questo token per usarlo in un secondo momento, perché potrebbe scadere.

Metadati personalizzati e specifici del contenuto

Per i metadati BLOB personalizzati o definiti dall'utente, definire un campo con lo stesso nome della chiave di metadati del BLOB. Ad esempio, se i BLOB hanno una chiave Sensitivity di metadati con valore High, definire un campo denominato Sensitivity di tipo Edm.String nell'indice.

È anche possibile rappresentare le proprietà dei metadati specifiche per il formato di documento dei BLOB indicizzati. Per altre informazioni, vedere Proprietà dei metadati del contenuto.

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. Imposta credentials su una stringa di connessione di Archiviazione di Azure. Nella sezione successiva vengono descritti i formati supportati.

  4. Impostare container sul contenitore BLOB e utilizzare query per specificare le eventuali sottocartelle.

È anche possibile includere criteri di eliminazione temporanea in una definizione di origine dati 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.

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 sinistro. Assicurarsi di selezionare una stringa di connessione completa e non soltanto una chiave.
Stringa di connessione con identità gestita
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
Questa stringa di connessione non richiede una chiave dell'account, ma è necessario aver configurato in precedenza un servizio di ricerca per la connessione tramite un'identità gestita.
Stringa di connessione della firma di accesso condiviso dell'account di archiviazione
{ "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 per il 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 Concedere accesso limitato alle risorse di Archiviazione di Azure tramite firme di accesso condiviso.

Annotazioni

Se si usano le credenziali SAS, è necessario aggiornare periodicamente le credenziali della sorgente dati con firme rinnovate per evitarne la scadenza. Se le credenziali di firma di accesso condiviso scadono, l'indicizzatore ha esito negativo e viene visualizzato 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.

  1. Creare o aggiornare un indice per definire i campi di ricerca che archiviano il contenuto e i metadati dei BLOB:

    POST https://[service name].search.windows.net/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_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 del documento ("key": true). Per il contenuto di BLOB, le opzioni migliori sono le proprietà dei metadati.

    • metadata_storage_path (impostazione predefinita) è il percorso completo dell'oggetto o del file. Il campo chiave (ID in questo esempio) viene 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, 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, qualsiasi BLOB che manca di un valore non può essere indicizzato. Se si usa una proprietà di metadati personalizzata come chiave, evitare di apportare modifiche a tale proprietà. Gli indicizzatori aggiungono documenti duplicati per lo stesso BLOB se la proprietà della chiave cambia.

    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 content campo per archiviare il testo estratto da ogni file tramite la proprietà del content blob. Non è necessario usare questo nome, ma usandolo, è 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, creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti di runtime. È 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=2026-04-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 configuration controllare quali BLOB vengono indicizzati in base al tipo di file o lasciare il valore 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 per indicare le estensioni che l'indicizzatore deve ignorare. Se la stessa estensione si trova in entrambi gli elenchi, l'indicizzatore lo esclude dall'indicizzazione.

  4. In configurationimpostare dataToExtract per controllare quali parti dei BLOB vengono indicizzate:

  5. In configurationimpostare 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:

  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 BLOB, è spesso possibile omettere la mappatura dei campi perché l'indicizzatore ha un supporto predefinito per la mappatura delle proprietà content e dei metadati ai campi con nomi e tipi simili in un indice. Per le proprietà dei metadati, l'indicizzatore sostituisce automaticamente i trattini - con caratteri underscore 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 impedire questa azione impostando disabled su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.

Indicizzare i 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 è necessario indicizzare i dati da più contenitori e consolidarlo in un singolo indice di ricerca di intelligenza artificiale, configurare più indicizzatori che puntano allo stesso indice. Tenere presente il numero massimo di indicizzatori disponibili per SKU.

Ad esempio, è possibile usare due indicizzatori per eseguire il pull dei 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=2026-04-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=2026-04-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=2026-04-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 delle esecuzioni completate più di recente. Gli elementi vengono ordinati in ordine cronologico inverso, di conseguenza l'esecuzione più recente viene prima.

Risoluzione dei problemi

Usa questa sezione per individuare valori di metadati mancanti e gli errori comuni di indicizzazione dei BLOB.

I campi dei metadati sono Null nei risultati della ricerca

Se vengono visualizzati valori Null o vuoti per i campi dei metadati nei risultati della ricerca, usare questo elenco di controllo:

  1. Verificare che il campo esista nello schema dell'indice: Verificare di aver definito un campo per ogni proprietà di metadati da acquisire. Eseguire una richiesta GET sull'indice per verificare che il campo sia presente.

  2. Usare il nome del campo corretto: Per le proprietà blob standard, usare il nome con caratteri di sottolineatura, ad esempio metadata_storage_path anziché metadata-storage-path. Per i metadati personalizzati, il nome del campo deve corrispondere esattamente alla chiave di metadati del BLOB.

  3. Verificare che l'indicizzatore abbia dataToExtract impostato correttamente:

    • contentAndMetadata (impostazione predefinita) estrae sia il contenuto che i metadati standard/personalizzati.
    • storageMetadata estrae solo le proprietà blob standard e i metadati personalizzati.
    • allMetadata estrae le proprietà standard e i metadati specifici del tipo di contenuto.

    Controllare la configurazione dell'indicizzatore per assicurarsi che l'impostazione corrisponda alla finalità.

  4. Eseguire nuovamente l'indicizzatore dopo gli aggiornamenti dello schema: Se è stato aggiunto un nuovo campo all'indice, eseguire di nuovo l'indicizzatore in modo che i documenti vengano elaborati sullo schema aggiornato. Potrebbe essere necessario rielaborare i documenti esistenti prima che il nuovo campo venga popolato.

  5. Controllare la cronologia di esecuzione dell'indicizzatore: Passare all'indicizzatore nel portale di Azure o usare Get Indexer Status (API REST) per visualizzare i dettagli dell'esecuzione ed eventuali messaggi di errore.

Errori dell'indicizzatore e tipi di contenuto non supportati

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.

Se si vuole continuare l'indicizzazione quando alcuni documenti hanno esito negativo, modificare i parametri seguenti e quindi esaminare i singoli documenti in un secondo momento. Per altre informazioni, vedere Indicazioni sulla risoluzione dei problemi dell'indicizzatore e errori e avvisi dell'indicizzatore.

Quando si verificano errori, cinque parametri dell'indicizzatore controllano la risposta dell'indicizzatore:

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}
Parametro Valori validi Description
maxFailedItems -1, null o 0, numero intero positivo Continuare l'indicizzazione se si verificano errori in qualsiasi momento dell'elaborazione, durante l'analisi dei BLOB o durante l'aggiunta di documenti a un indice. Impostare questa proprietà sul numero di errori accettabili. Un valore -1 consente l'elaborazione indipendentemente dal numero di errori che si verificano. Altrimenti, il valore è un numero intero positivo.
maxFailedItemsPerBatch -1, null o 0, numero intero positivo Come sopra, ma usato per l'indicizzazione batch.
failOnUnsupportedContentType vero o falso Se l'indicizzatore non riesce a determinare il tipo di contenuto, specificare se continuare o non eseguire il processo.
failOnUnprocessableDocument vero o falso 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.
indexStorageMetadataOnlyForOversizedDocuments vero o falso I BLOB sovradimensionati vengono gestiti come errori per impostazione predefinita. Se si imposta questo parametro su true, l'indicizzatore tenta di indicizzare i metadati anche se il contenuto non può essere indicizzato. Per i limiti relativi alle dimensioni dei BLOB, vedere Limiti del servizio.