Condividi tramite

Indicizzare i dati delle raccolte documenti di SharePoint

Importante

Il supporto dell'indicizzatore di SharePoint Online è disponibile in anteprima pubblica. Viene offerto "così come è", in base alle Condizioni per l'utilizzo supplementari e supportato solo con la massima diligenza possibile. Le funzionalità di anteprima non sono consigliate per i carichi di lavoro di produzione e non è garantito che diventeranno disponibili a livello generale.

Prima di iniziare, vedere la sezione limitazioni note .

Compilare questo modulo per registrarsi per l'anteprima. Tutte le richieste vengono approvate automaticamente. Dopo aver compilato il modulo, usare un'API REST di anteprima per indicizzare il contenuto.

Questo articolo illustra come configurare un indicizzatore di ricerca per indicizzare i documenti archiviati nelle raccolte documenti di SharePoint per la ricerca full-text in Azure AI Search. Vengono prima descritti i passaggi di configurazione, seguiti da comportamenti e scenari

In Ricerca di intelligenza artificiale di Azure un indicizzatore estrae dati e metadati ricercabili da un'origine dati. L'indicizzatore di SharePoint Online si connette al sito di SharePoint e indicizza i documenti di una o più raccolte. L'indicizzatore offre le funzionalità seguenti:

  • Indicizza file e metadati da una o più raccolte documenti.
  • Indici in modo incrementale, raccogliendo solo i file e i metadati nuovi e modificati.
  • Rileva automaticamente il contenuto eliminato. L'eliminazione di documenti nella biblioteca viene registrata per l'esecuzione successiva dell'indicizzatore e il documento di ricerca corrispondente viene rimosso dall'indice.
  • Estrae automaticamente testo e immagini normalizzate da documenti indicizzati. Facoltativamente, è possibile aggiungere un set di competenze per un arricchimento più approfondito tramite intelligenza artificiale, ad esempio OCR o traduzione di testo.

Prerequisiti

Formati di documento supportati

L'indicizzatore di SharePoint Online 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
  • formato ZIP

Limitazioni e considerazioni

Ecco le limitazioni di questa funzionalità:

  • L'indicizzatore può indicizzare il contenuto dai formati di documento supportati in una raccolta documenti. Non è disponibile alcun supporto per l'indicizzazione degli elenchi di SharePoint, il contenuto del sito ASPX o i file del blocco appunti di OneNote. Inoltre, l'indicizzazione di siti secondari in modo ricorsivo da un sito specifico non è supportata.

  • Limitazioni dell'indicizzazione incrementale:

    • La ridenominazione di una cartella di SharePoint interrompe l'indicizzazione incrementale. Le cartelle rinominate vengono considerate come nuovo contenuto.

    • I processi di Microsoft 365 che aggiornano i metadati del file system di SharePoint possono attivare l'indicizzazione incrementale, anche se non sono presenti altre modifiche al contenuto. Assicurarsi di testare la configurazione e comprendere il numero di elaborazione dei documenti prima di usare l'indicizzatore e qualsiasi arricchimento tramite intelligenza artificiale.

  • Limitazioni di sicurezza:

    • Nessun supporto per l'endpoint privato.

    • Nessun supporto per le raccolte documenti o il contenuto configurato per l'accesso condizionale di Microsoft Entra ID.

    • Non è supportato alcun file crittografato dall'utente, file protetti da Information Rights Management (IRM), file ZIP con password o contenuti crittografati simili.

    • Nessun supporto per il modello di autorizzazione granulare di SharePoint che determina l'accesso per utente a livello di documento. L'indicizzatore non esegue il pull di queste autorizzazioni nell'indice. Il contenuto è disponibile per chiunque abbia accesso in lettura all'indice. Se sono necessarie autorizzazioni a livello di documento, considerare i filtri di sicurezza per tagliare i risultati e automatizzare la copia delle autorizzazioni a livello di file in un campo nell'indice.

Di seguito sono riportate alcune considerazioni sull'uso di questa funzionalità:

  • Se è necessario creare un'applicazione Copilot o RAG (Recupero di generazione aumentata) personalizzata per chattare con i dati di SharePoint, Microsoft consiglia di usare Microsoft Copilot Studio invece di questa funzionalità di anteprima.

  • Se è ancora necessaria una soluzione di indicizzazione dei contenuti di SharePoint Online personalizzata usando Ricerca di intelligenza artificiale di Azure in un ambiente di produzione, nonostante la raccomandazione di usare Microsoft Copilot Studio, prendere in considerazione:

    • Creazione di un connettore personalizzato con i webhook di SharePoint, chiamando l'API Microsoft Graph per esportare i dati in un contenitore Blob di Azure e quindi usare l'indicizzatore Blob di Azure per l'indicizzazione incrementale.

    • Creare il proprio flusso di lavoro Azure Logic Apps utilizzando il connettore SharePoint di Azure Logic Apps e il connettore Ricerca AI di Azure mentre si raggiunge la disponibilità generale. È possibile usare il flusso di lavoro generato dalla procedura guidata del portale di Azure come punto di partenza e quindi personalizzarlo nella finestra di progettazione di App per la logica di Azure per includere i passaggi di trasformazione necessari. Il workflow di Azure Logic App creato quando si utilizza la procedura guidata di ricerca AI di Azure per indicizzare i dati di SharePoint Online è un workflow basato sul consumo. Se stai configurando carichi di lavoro di produzione, assicurati di passare a un flusso di lavoro standard dell'app logica e sfruttare le funzionalità aziendali aggiuntive.

    Indipendentemente dall'approccio scelto, che sia costruire un connettore personalizzato con integrazioni di SharePoint o creare un flusso di lavoro mediante Azure Logic Apps, assicurati di implementare misure di sicurezza affidabili. Queste misure includono la configurazione di collegamenti privati condivisi, la configurazione di firewall, la conservazione delle autorizzazioni utente dall'origine e l'rispetto di tali autorizzazioni in fase di query, tra le altre. Dovresti anche controllare e monitorare regolarmente la pipeline.

Configurare l'indicizzatore di SharePoint Online

Per configurare l'indicizzatore di SharePoint Online, usare un'API REST di anteprima. In questa sezione vengono illustrati i passaggi.

Passaggio 1 (facoltativo): Abilitare l'identità gestita assegnata dal sistema

Abilitare un'identità gestita assegnata dal sistema per rilevare automaticamente il tenant in cui viene effettuato il provisioning del servizio di ricerca.

Eseguire questo passaggio se il sito di SharePoint si trova nello stesso tenant del servizio di ricerca. Ignorare questo passaggio se il sito di SharePoint si trova in un tenant diverso. L'identità non viene usata per l'indicizzazione, ma solo per il rilevamento del tenant. È anche possibile ignorare questo passaggio se si vuole inserire l'ID tenant nella stringa di connessione.

Screenshot che mostra come abilitare un'identità gestita assegnata dal sistema.

Dopo aver selezionato Salva, si ottiene un ID oggetto assegnato al servizio di ricerca.

Screenshot dell'identificatore di oggetto.

Passaggio 2: Decidere quali autorizzazioni richiede l'indicizzatore

L'indicizzatore di SharePoint Online supporta sia le autorizzazioni delegate sia quelle basate su applicazione. Scegliere le autorizzazioni da usare in base allo scenario.

È consigliabile usare le autorizzazioni basate su app. Vedere limitazioni per i problemi noti relativi alle autorizzazioni delegate.

  • Autorizzazioni basate su applicazione (scelta consigliata), in cui l'indicizzatore viene eseguito con l'identità del tenant di SharePoint con accesso a tutti i siti e i file. L'indicizzatore richiede un segreto client. L'indicizzatore richiederà anche l'approvazione dell'amministratore tenant prima di poter indicizzare qualsiasi contenuto.

  • Autorizzazioni delegate, in cui l'indicizzatore viene eseguito con l'identità dell'utente o dell'app che invia la richiesta. L'accesso ai dati è limitato ai siti e ai file a cui il chiamante ha accesso. Per supportare le autorizzazioni delegate, l'indicizzatore richiede il prompt di un codice dispositivo per accedere per conto dell'utente. Le autorizzazioni delegate dall'utente applicano la scadenza del token ogni 75 minuti, in base alle librerie di sicurezza più recenti usate per implementare questo tipo di autenticazione. Questo non è un comportamento che può essere modificato. Un token scaduto richiede l'indicizzazione manuale tramite Esegui indicizzatore (anteprima). Per questo motivo, è consigliabile usare invece le autorizzazioni basate su app.

Passaggio 3: Creare una registrazione dell'applicazione Microsoft Entra

L'indicizzatore di SharePoint Online usa un'applicazione Microsoft Entra per l'autenticazione. Creare la registrazione dell'applicazione nello stesso tenant di Ricerca di intelligenza artificiale di Azure.

  1. Accedere al portale di Azure.

  2. Cercare o passare a Microsoft Entra ID, e quindi selezionare Aggiungi>Registrazioni app.

  3. Selezionare + Nuova registrazione:

    1. Specificare un nome per l'app.
    2. Selezionare Tenant singolo.
    3. Ignorare il passaggio di designazione URI. Non è necessario alcun URI di reindirizzamento.
    4. Selezionare Registra.

  4. Nel riquadro di spostamento in Gestisci selezionare Autorizzazioni API, quindi Aggiungi un'autorizzazione, quindi Microsoft Graph.

    • Se l'indicizzatore usa le autorizzazioni dell'API dell'applicazione, selezionare Autorizzazioni applicazione e aggiungere quanto segue:

      • Applicazione - Files.Read.All
      • Applicazione - Sites.Read.All

      Screenshot delle autorizzazioni dell'API dell'applicazione.

      L'uso delle autorizzazioni dell'applicazione implica che l'indicizzatore accede al sito di SharePoint in un contesto del servizio. Quindi, quando viene eseguito, l'indicizzatore avrà accesso a tutto il contenuto nel tenant di SharePoint, il che richiede l'approvazione dell'amministratore tenant. Per l'autenticazione è necessario anche un segreto client. La configurazione del segreto client è descritta più avanti in questo articolo.

    • Se l'indicizzatore usa autorizzazioni dell'API delegate, selezionare Autorizzazioni delegate e aggiungere quanto segue:

      • Delegato - Files.Read.All
      • Delegato - Sites.Read.All
      • Delegato - User.Read

      Screenshot che mostra le autorizzazioni dell'API delegate.

      Le autorizzazioni delegate consentono al client di ricerca di connettersi a SharePoint con l'identità di sicurezza dell'utente corrente.

  5. Concedere il consenso amministratore.

    Il consenso dell'amministratore tenant è necessario quando si usano le autorizzazioni dell'API dell'applicazione. Alcuni tenant sono bloccati in modo tale per cui il consenso dell'amministratore tenant è necessario anche per le autorizzazioni dell'API delegate. Se si applica una di queste condizioni, è necessario avere il consenso di un amministratore tenant per questa applicazione Microsoft Entra prima di creare l'indicizzatore.

    Screenshot che mostra l'opzione Concedi consenso amministratore per l'app Microsoft Entra.

  6. Seleziona la scheda Autenticazione.

  7. Impostare Consenti i flussi client pubblici su Sì e quindi selezionare Salva.

  8. Selezionare + Aggiungi una piattaforma, quindi Applicazioni per dispositivi mobili e desktop, quindi selezionare https://login.microsoftonline.com/common/oauth2/nativeclient e poi Configura.

    Screenshot che mostra la configurazione dell'autenticazione dell'app Microsoft Entra.

  9. (Solo autorizzazioni dell'API dell'applicazione) Per eseguire l'autenticazione per l'applicazione Microsoft Entra usando le autorizzazioni dell'applicazione, l'indicizzatore richiede un segreto client.

    • Selezionare Certificati e segreti nel menu a sinistra, quindi Segreti client e infine Nuovo segreto client.

      Screenshot che mostra un segreto client.

    • Nel menu visualizzato immettere una descrizione per il nuovo segreto client. Modificare la data di scadenza, se necessario. Se il segreto scade, deve essere ricreato e l'indicizzatore deve essere aggiornato con il nuovo segreto.

      Screenshot che mostra come configurare un segreto client.

    • Il nuovo segreto client viene visualizzato nell'elenco dei segreti. Quando si esce dalla pagina, il segreto non è più visibile, quindi copiarlo usando il pulsante di copia e salvarlo in una posizione sicura.

      Screenshot che mostra dove copiare un segreto client.

Passaggio 4: Creare un'origine dati

A partire da questa sezione, usare l'API REST di anteprima per i passaggi rimanenti. È consigliabile usare l'API di anteprima più recente.

Un'origine dati specifica i dati da indicizzare, le credenziali e i criteri che consentono di identificare in modo efficace le modifiche apportate ai dati, ovvero righe nuove, modificate o eliminate. Un'origine dati può essere usata da più indicizzatori nello stesso servizio di ricerca.

Per l'indicizzazione SharePoint, l'origine dati deve avere le proprietà obbligatorie seguenti:

  • name è il nome univoco dell'origine dati all'interno del servizio di ricerca.
  • type deve essere "sharepoint". Per questo valore viene applicata la distinzione tra maiuscole e minuscole.
  • credentials fornisce l'endpoint di SharePoint e l'ID applicazione Microsoft Entra (client). Un esempio di endpoint di SharePoint è https://microsoft.sharepoint.com/teams/MySharePointSite. È possibile ottenere l'endpoint passando alla home page del sito di SharePoint e copiando l'URL dal browser.
  • container specifica la raccolta documenti da indicizzare. Le proprietà controllano quali documenti vengono indicizzati.

Per creare un'origine dati, chiamare Crea origine dati (anteprima).

POST https://[service name].search.windows.net/datasources?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "[connection-string]" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null }
}

Formato della stringa di connessione

Il formato della stringa di connessione cambia in base al fatto che l'indicizzatore usi autorizzazioni dell'API delegate o autorizzazioni dell'API dell'applicazione

  • Formato della stringa di connessione delle autorizzazioni dell'API delegate

    SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];TenantId=[SharePoint site tenant id]

  • Formato della stringa di connessione delle autorizzazioni dell'API dell'applicazione

    SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];ApplicationSecret=[Azure AD App client secret];TenantId=[SharePoint site tenant id]

Nota

Se il sito di SharePoint si trova nello stesso tenant del servizio di ricerca e l'identità gestita assegnata dal sistema è abilitata, TenantId non deve essere incluso nella stringa di connessione. Se il sito di SharePoint si trova in un tenant diverso dal servizio di ricerca, TenantId deve essere incluso.

Passaggio 5: Creare un indice

L'indice consente di specificare i campi in un documento, gli attributi e altri costrutti che danno forma all'esperienza della ricerca.

Per creare un indice, chiamare Crea indice (anteprima):

POST https://[service name].search.windows.net/indexes?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-index",
    "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "metadata_spo_item_name", "type": "Edm.String", "key": false, "searchable": true, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_path", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_content_type", "type": "Edm.String", "key": false, "searchable": false, "filterable": true, "sortable": false, "facetable": true },
        { "name": "metadata_spo_item_last_modified", "type": "Edm.DateTimeOffset", "key": false, "searchable": false, "filterable": false, "sortable": true, "facetable": false },
        { "name": "metadata_spo_item_size", "type": "Edm.Int64", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

Importante

È possibile usare solo metadata_spo_site_library_item_id come campo chiave in un indice popolato dall'indicizzatore di SharePoint Online. Se nell'origine dati non esiste un campo chiave, viene eseguito automaticamente il mapping di metadata_spo_site_library_item_id al campo chiave.

Passaggio 6: Creare un indicizzatore

Un indicizzatore si connette a un'origine dati con un indice di ricerca di destinazione e pianifica l’automatizzazione dell'aggiornamento dei dati. Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore.

Se si usano autorizzazioni delegate, durante questo passaggio viene chiesto di accedere con le credenziali dell'organizzazione che hanno accesso al sito di SharePoint. Se possibile, è consigliabile creare un nuovo account utente dell'organizzazione e concedere al nuovo utente le autorizzazioni esatte che si desidera che l'indicizzatore abbia.

Per creare l'indicizzatore sono necessari alcuni passaggi:

  1. Inviare una richiesta Crea indicizzatore (anteprima):

    POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-indexer",
    "dataSourceName" : "sharepoint-datasource",
    "targetIndexName" : "sharepoint-index",
    "parameters": {
    "batchSize": null,
    "maxFailedItems": null,
    "maxFailedItemsPerBatch": null,
    "base64EncodeKeys": null,
    "configuration": {
        "indexedFileNameExtensions" : ".pdf, .docx",
        "excludedFileNameExtensions" : ".png, .jpg",
        "dataToExtract": "contentAndMetadata"
      }
    },
    "schedule" : { },
    "fieldMappings" : [
        { 
          "sourceFieldName" : "metadata_spo_site_library_item_id", 
          "targetFieldName" : "id", 
          "mappingFunction" : { 
            "name" : "base64Encode" 
          } 
         }
    ]
}

    Se si usano le autorizzazioni dell'applicazione, è necessario attendere il completamento dell'esecuzione iniziale prima di iniziare a eseguire query sull'indice. Le istruzioni seguenti fornite in questo passaggio riguardano in modo specifico le autorizzazioni delegate e non sono applicabili alle autorizzazioni dell'applicazione.

  2. Quando si crea l'indicizzatore per la prima volta, la richiesta Crea indicizzatore (anteprima) attende fino al completamento del passaggio successivo. È necessario chiamare Ottieni stato indicizzatore per ottenere il collegamento e immettere il nuovo codice dispositivo.

    GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

    Se non si esegue Ottieni stato indicizzatore entro 10 minuti, il codice scade e sarà necessario ricreare l'origine dati.

  3. Copiare il codice di accesso del dispositivo dalla risposta di Ottieni stato indicizzatore. L'account di accesso del dispositivo è disponibile in "errorMessage".

    {
    "lastResult": {
        "status": "transientFailure",
        "errorMessage": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code <CODE> to authenticate."
    }
}

  4. Specificare il codice incluso nel messaggio di errore.

    Screenshot che mostra come immettere un codice dispositivo.

  5. L'indicizzatore di SharePoint Online accederà al contenuto di SharePoint come utente connesso. L'utente che accede durante questo passaggio sarà l'utente connesso. Pertanto, se si accede con un account utente che non ha accesso a un documento nella raccolta documenti da indicizzare, l'indicizzatore non avrà accesso a tale documento.

    Se possibile, è consigliabile creare un nuovo account utente e concedere al nuovo utente le autorizzazioni esatte che si desidera che l'indicizzatore abbia.

  6. Approvare le autorizzazioni richieste.

    Screenshot che mostra come approvare le autorizzazioni dell'API.

  7. La richiesta iniziale Crea indicizzatore (anteprima) viene completata se tutte le autorizzazioni fornite in precedenza sono corrette ed entro l'intervallo di tempo di 10 minuti.

Nota

Se l'applicazione Microsoft Entra richiede l'approvazione dell'amministratore e non è stata approvata prima dell'accesso, è possibile che venga visualizzata la schermata seguente. Per continuare, è necessaria l'approvazione dell'amministratore. Screenshot che mostra l'approvazione dell'amministratore richiesta.

Passaggio 7: Controllare lo stato dell'indicizzatore

Dopo aver creato l'indicizzatore, è possibile chiamare Ottieni stato indicizzatore:

GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

Aggiornamento dell'origine dati

Se non sono stati apportati aggiornamenti all'oggetto origine dati, l'indicizzatore viene eseguito in base a una pianificazione senza alcuna interazione dell'utente.

Tuttavia, se si modifica l'oggetto origine dati mentre il codice dispositivo è scaduto, è necessario eseguire di nuovo l'accesso affinché l'indicizzatore venga eseguito. Ad esempio, se si cambia la query dell'origine dati, accedere di nuovo usando https://microsoft.com/devicelogin e ottenere il nuovo codice dispositivo.

Ecco i passaggi per l'aggiornamento di un'origine dati, presupponendo un codice dispositivo scaduto:

  1. Chiamare Esegui indicizzatore (anteprima) per avviare manualmente l'esecuzione dell'indicizzatore.

    POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2025-05-01-preview  
Content-Type: application/json
api-key: [admin key]

  2. Controllare lo stato dell'indicizzatore.

    GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

  3. Se viene visualizzato un errore che chiede di visitare https://microsoft.com/devicelogin, aprire la pagina e copiare il nuovo codice.

  4. Incollare il codice nella finestra di dialogo.

  5. Eseguire di nuovo manualmente l'indicizzatore e controllare il relativo stato. Questa volta, l'esecuzione dell'indicizzatore dovrebbe essere avviata correttamente.

Indicizzazione dei metadati del documento

Se si indicizzano i metadati del documento ("dataToExtract": "contentAndMetadata"), sono disponibili i metadati seguenti per l'indice.

Identificatore Tipo Descrizione
metadata_spo_sito_biblioteca_elem_id Edm.String La chiave combinata di ID sito, ID raccolta e ID elemento, che identifica in modo univoco un elemento in una raccolta documenti per un sito.
metadata_spo_site_id Edm.String L'ID del sito di SharePoint.
metadata_spo_library_id Edm.String L'ID della raccolta documenti.
metadata_spo_item_id Edm.String L'ID dell'elemento (documento) nella raccolta.
metadata_item_spo_ultima_modifica Edm.DateTimeOffset La data/ora dell'ultima modifica (UTC) dell'elemento.
metadati_spo_nome_oggetto Edm.String Nome dell'elemento.
dimensione_elemento_spo_metadati Edm.Int64 Le dimensioni (in byte) dell'elemento.
metadata_spo_tipo_di_contenuto_item Edm.String Il tipo di contenuto dell'elemento.
metadati_spo_estensione_elemento Edm.String L'estensione dell'elemento.
metadata_spo_item_weburi Edm.String L'URI dell'elemento.
metadata_spo_item_path Edm.String La combinazione del percorso padre e del nome dell'elemento.

L'indicizzatore di SharePoint Online supporta anche metadati specifici di ogni tipo di documento. Altre informazioni sono disponibili in Proprietà dei metadati del contenuto usate in Azure AI Search.

Nota

Per indicizzare metadati personalizzati, è necessario specificare "additionalColumns" nel parametro di query dell'origine dati.

Includere o escludere in base al tipo di file

È possibile controllare quali file vengono indicizzati impostando criteri di inclusione ed esclusione nella sezione "parameters" della definizione dell'indicizzatore.

Includere estensioni di file specifiche impostando "indexedFileNameExtensions" su un elenco delimitato da virgole di estensioni di file (con un punto iniziale). Escludere estensioni di file specifiche impostando "excludedFileNameExtensions" sulle estensioni da ignorare. Se la stessa estensione si trova in entrambi gli elenchi, questa viene esclusa dall'indicizzazione.

PUT /indexers/[indexer name]?api-version=2025-05-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

Controllo dei documenti indicizzati

Un singolo indicizzatore di SharePoint Online può indicizzare il contenuto di una o più raccolte documenti. Usare il parametro "container" nella definizione dell'origine dati per indicare i siti e le raccolte documenti da indicizzare.

La sezione "container" dell'origine dati ha due proprietà per questa attività: "name" e "query".

Nome

La proprietà "name" è obbligatoria e deve essere uno dei tre valori seguenti:

Valore Descrizione
libreriaPredefinitaDelSito Indicizza tutto il contenuto dalla raccolta documenti predefinita del sito.
tutteLeBibliotecheDelSito Indicizza tutto il contenuto di tutte le raccolte documenti in un sito. Le raccolte documenti di un sito secondario non rientrano nell'ambito. Se sono necessari contenuti di siti secondari, scegliere "useQuery" e specificare "includeLibrariesInSite".
useQuery Indicizza solo il contenuto definito in "query".

Quesito

Il parametro "query" dell'origine dati è costituito da coppie di parola chiave/valore. Di seguito sono riportate le parole chiave che è possibile usare. I valori sono URL del sito o URL della raccolta documenti.

Nota

Per ottenere il valore per una parola chiave specifica, è consigliabile passare alla raccolta documenti che si sta tentando di includere/escludere e copiare l'URI dal browser. Questo è il modo più semplice per ottenere il valore da usare con una parola chiave nella query.

Parola chiave Descrizione dei valori ed esempi
Null Se null o vuoto, indicizza la raccolta documenti predefinita o tutte le raccolte documenti a seconda del nome del contenitore.

Esempio:

"container" : { "name" : "defaultSiteLibrary", "query" : null }
includereLibrerieNelSito Indicizza il contenuto di tutte le raccolte nel sito specificato nella stringa di connessione. Il valore deve essere l'URI del sito o del sito secondario.

Esempio 1:

"container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/mysite" }

Esempio 2 (include solo alcuni siti secondari):

"container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite1;includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite2" }
includiLibreria Indicizza tutto il contenuto di questa raccolta. Il valore è il percorso completo della raccolta, che può essere copiato dal browser:

Esempio 1 (percorso completo):

"container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary" }

Esempio 2 (URI copiato dal browser):

"container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" }
escludiLibreria Non indicizza il contenuto di questa raccolta. Il valore è il percorso completo della raccolta, che può essere copiato dal browser:

Esempio 1 (percorso completo):

"container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mysite.sharepoint.com/subsite1; excludeLibrary=https://mysite.sharepoint.com/subsite1/MyDocumentLibrary" }

Esempio 2 (URI copiato dal browser):

"container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/teams/mysite; excludeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" }
colonne aggiuntive Indicizza le colonne della raccolta documenti. Il valore è un elenco delimitato da virgole di nomi di colonna da indicizzare. Usare una doppia barra rovesciata per eseguire l'escape di punti e virgola e virgole nei nomi di colonna:

Esempio 1 (additionalColumns=MyCustomColumn,MyCustomColumn2):

"container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary;additionalColumns=MyCustomColumn,MyCustomColumn2" }

Esempio 2 (caratteri di escape con doppia barra rovesciata):

"container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx;additionalColumns=MyCustomColumnWith\\,,MyCustomColumnWith\\;" }

Gestione degli errori

Per impostazione predefinita, l'indicizzatore di SharePoint Online si arresta non appena rileva un documento con un tipo di contenuto non supportato, ad esempio un'immagine. È possibile usare il parametro excludedFileNameExtensions per ignorare determinati tipi di contenuto. Potrebbe tuttavia essere necessario indicizzare documenti senza conoscere in anticipo tutti i tipi di contenuto possibili. Per continuare l'indicizzazione quando viene rilevato un tipo di contenuto non supportato, impostare il parametro di configurazione failOnUnsupportedContentType su false:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    ... other parts of indexer definition
    "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}

Per alcuni documenti, Azure AI Search non è in grado di determinare il tipo di contenuto o di elaborare un documento di un tipo di contenuto altrimenti supportato. Per ignorare la modalità di errore, impostare il parametro di configurazione failOnUnprocessableDocument su False:

"parameters" : { "configuration" : { "failOnUnprocessableDocument" : false } }

Azure AI Search limita le dimensioni dei documenti indicizzati. Questi limiti sono documentati in Limiti dei servizi in Azure AI Search. I documenti sovradimensionati vengono considerati come errori per impostazione predefinita. È comunque possibile indicizzare i metadati di archiviazione dei documenti sovradimensionati se si imposta il parametro di configurazione indexStorageMetadataOnlyForOversizedDocuments su true:

"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }

È anche possibile continuare l'indicizzazione se si verificano errori in qualsiasi momento dell'elaborazione, durante l'analisi dei documenti o durante l'aggiunta di documenti a un indice. Per ignorare un determinato numero di errori, impostare i parametri di configurazione maxFailedItems e maxFailedItemsPerBatch sui valori desiderati. Ad esempio:

{
    ... other parts of indexer definition
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}

Se è abilitata la crittografia di un file nel sito di SharePoint, potrebbe essere visualizzato il messaggio di errore seguente:

Code: resourceModified Message: The resource has changed since the caller last read it; usually an eTag mismatch Inner error: Code: irmEncryptFailedToFindProtector

Il messaggio di errore includerà anche l'ID del sito di SharePoint, l'ID unità e l'ID dell'elemento di unità nel modello seguente: <sharepoint site id> :: <drive id> :: <drive item id>. Queste informazioni possono essere usate per identificare l'elemento in errore nell'endpoint di SharePoint. L'utente può quindi rimuovere la crittografia dall'elemento per risolvere il problema.

Vedi anche