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.

Assicurarsi di visitare la sezione limitazioni note prima di iniziare.

Per usare questa anteprima, compilare questo modulo. Non si riceverà alcuna notifica di approvazione subito dopo, perché qualsiasi richiesta di accesso viene accettata automaticamente dopo l'invio. Quando l'accesso viene abilitato, usare un'API REST in 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

Funzionalità

In Azure AI Search un indicizzatore è un crawler che estrae metadati e dati 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:

• Indicizzazione di file e metadati di una o più raccolte documenti.
• Indicizzazione incrementale, per cui vengono prelevati solo i file e i metadati nuovi e modificati.
• Rilevamento integrato delle eliminazioni. L'eliminazione in una raccolta documenti viene prelevata all'esecuzione successiva dell'indicizzatore e il documento viene rimosso dall'indice.
• Estrazione di testo e immagini normalizzate per impostazione predefinita dai 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

• Servizio cloud SharePoint in Microsoft 365

• File in una raccolta documenti

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

Limitazioni e considerazioni

Ecco le limitazioni di questa funzionalità:

• L'indicizzazione degli elenchi di SharePoint non è supportata.

• L'indicizzazione del contenuto di siti ASPX di SharePoint non è supportata.

• I file di blocchi appunti di OneNote non sono supportati.

• L'endpoint privato non è supportato.

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

• SharePoint supporta un modello di autorizzazione granulare che determina l'accesso per utente a livello di documento. L'indicizzatore non esegue il pull di queste autorizzazioni nell'indice e Azure AI Search non supporta l'autorizzazione a livello di documento. Quando un documento viene indicizzato da SharePoint in un servizio di ricerca, il contenuto è disponibile per chiunque abbia accesso in lettura all'indice. Se sono necessarie autorizzazioni a livello di documento, è consigliabile considerare i filtri di sicurezza per troncare i risultati e automatizzare la copia delle autorizzazioni a livello di file in un campo nell'indice.

• L'indicizzazione di file crittografati dall'utente, file protetti da Information Rights Management (IRM), file ZIP con password o contenuto crittografato simile non è supportata. Affinché il contenuto crittografato venga elaborato, l'utente con autorizzazioni appropriate per il file specifico deve rimuovere la crittografia in modo che l'elemento possa essere indicizzato di conseguenza quando l'indicizzatore esegue l'iterazione pianificata successiva.

• L'indicizzazione di siti secondari in modo ricorsivo da un sito specifico indicato non è supportata.

Ecco gli aspetti da considerare per l'uso di questa funzionalità:

• Se è necessaria una soluzione di indicizzazione del contenuto di SharePoint in un ambiente di produzione, è consigliabile creare un connettore personalizzato con 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.

• Se la configurazione di SharePoint consente ai processi di Microsoft 365 di aggiornare i metadati del file system di SharePoint, tenere presente che questi aggiornamenti possono attivare l'indicizzatore di SharePoint Online, per cui i documenti possono essere inseriti più volte. Poiché l'indicizzatore di SharePoint Online è un connettore di terze parti in Azure, l'indicizzatore non può leggere la configurazione o variarne il comportamento. Risponde alle modifiche apportate al contenuto nuovo e modificato, indipendentemente dal modo in cui vengono eseguiti gli aggiornamenti. Per questo motivo, assicurarsi di testare la configurazione e comprendere il conteggio dell'elaborazione documenti prima di usare l'indicizzatore e qualsiasi arricchimento tramite intelligenza artificiale.

Configurare l'indicizzatore di SharePoint Online

Per configurare l'indicizzatore di SharePoint Online, usare sia il portale di Azure sia un'API REST di anteprima. È possibile usare la versione 2020-06-30-preview o successiva. È consigliabile usare l'API di anteprima più recente.

In questa sezione vengono illustrati i passaggi. È anche possibile guardare il video seguente.

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.

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

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 dei token ogni 75 minuti, in base alle librerie di sicurezza più recenti usate per implementare questo tipo di autenticazione. Questo comportamento non può essere modificato. Un token scaduto richiede l'indicizzazione manuale tramite Esegui indicizzatore (anteprima). Per questo motivo, si potrebbe optare invece per le autorizzazioni basate su app.

Se l'organizzazione Microsoft Entra ha l'accesso condizionale abilitato e l'amministratore non è in grado di concedere l'accesso ai dispositivi per le autorizzazioni delegate, è consigliabile scegliere le autorizzazioni basate su app. Per altre informazioni, vedere Criteri di accesso condizionale di Microsoft Entra.

Passaggio 3: Creare una registrazione dell'applicazione Microsoft Entra

L'indicizzatore di SharePoint Online usa questa applicazione Microsoft Entra per l'autenticazione.

1. Accedere al portale di Azure.

2. Cercare o passare a Microsoft Entra ID, e quindi selezionare 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. A sinistra selezionare Autorizzazioni API, quindi Aggiungi un'autorizzazione e infine Microsoft Graph.

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

     • Application - Files.Read.All
     • Application - Sites.Read.All

     

     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:

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

     

     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.

   

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.

   

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.

     

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

     

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

     

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=2024-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=2024-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=2024-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=2024-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.

   

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.

   

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.

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=2024-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=2024-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=2024-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 esegue l'indicizzazione dei metadati del documento ("dataToExtract": "contentAndMetadata"), saranno disponibili i metadati seguenti.

Identifier	Tipo	Descrizione
metadata_spo_site_library_item_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_spo_item_last_modified	Edm.DateTimeOffset	La data/ora dell'ultima modifica (UTC) dell'elemento.
metadata_spo_item_name	Edm.String	Nome dell'elemento.
metadata_spo_item_size	Edm.Int64	Le dimensioni (in byte) dell'elemento.
metadata_spo_item_content_type	Edm.String	Il tipo di contenuto dell'elemento.
metadata_spo_item_extension	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=2024-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
defaultSiteLibrary	Indicizza tutto il contenuto dalla raccolta documenti predefinita del sito.
allSiteLibraries	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".

Query

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 }
includeLibrariesInSite	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" }
includeLibrary	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" }
excludeLibrary	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" }
additionalColumns	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=2024-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 riscontrato un messaggio di errore simile al 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

• Indicizzatori in Azure AI Search
• Proprietà dei metadati del contenuto usate in Azure AI Search