Indicizzare il contenuto da SharePoint in Microsoft 365 (anteprima)

Il SharePoint in Microsoft 365 indicizzatore (anteprima) importa documenti da raccolte documenti di SharePoint e li rende ricercabili in Azure AI Search. I passaggi di configurazione sono innanzitutto seguiti da comportamenti e scenari.

In Azure AI Search un indicizzatore estrae dati e metadati ricercabili da un'origine dati. Il SharePoint nell'indicizzatore di Microsoft 365 offre le funzionalità seguenti:

• Indicizza file e metadati da una o più raccolte documenti.
• Indicizza gli elenchi SharePoint e i valori dei campi dei relativi elementi, con ogni colonna dell'elenco disponibile come campo di origine per la mappatura dei campi. Questa funzionalità è disponibile in anteprima, a partire dall'API REST 2026-05-01-preview.
• Indicizza le pagine del sito ASPX (pagine del sito moderne). Questa funzionalità è disponibile in anteprima, a partire dall'API REST 2026-05-01-preview.
• Indicizza il contenuto SharePoint misto (raccolte documenti, elenchi e pagine del sito) in un singolo indicizzatore usando il valore del contenitore allSiteContent. Questa funzionalità è disponibile in anteprima, a partire dall'API REST 2026-05-01-preview.
• Indicizza il contenuto nei sottositi quando includeSubsites=true è impostato nella query dell'origine dati. Questa funzionalità è disponibile in anteprima, a partire dall'API REST 2026-05-01-preview.
• Indici in modo incrementale, raccogliendo solo i file nuovi e modificati, gli elementi di elenco, le pagine e i metadati.
• Rileva automaticamente il contenuto eliminato. L'eliminazione di file, elementi di elenco o pagine viene prelevata nella successiva esecuzione 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 l'arricchimento più approfondito dell'intelligenza artificiale, ad esempio il riconoscimento ottico dei caratteri (OCR) o il riconoscimento di entità.
• Supporta l'inserimento in anteprima degli elenchi di controllo di accesso di base (ACL). A partire dalla versione 2026-05-01-preview, le modifiche ACL vengono rilevate e aggiornate in modo incrementale in ogni indicizzatore riuscito eseguito per gli elementi con autorizzazioni univoche. Questa versione estende anche l'inserimento ACL agli elementi di elenco, alle pagine del sito ASPX e ai gruppi di SharePoint. Per informazioni dettagliate e passaggi di configurazione, vedere Usare un indicizzatore SharePoint per inserire i metadati delle autorizzazioni.
• Supporta l'inserimento di etichette di riservatezza di Microsoft Purview e il loro rispetto in fase di query. Questa funzionalità è disponibile in anteprima.

Prerequisiti

• Completare il modulo di registrazione dell'anteprima dell'indicizzatore. La registrazione viene approvata automaticamente.

• Azure AI Search, piano tariffario Basic o superiore.

• SharePoint nel servizio cloud Microsoft 365 (OneDrive non è un'origine dati supportata).

• File in una raccolta documenti.

• Visual Studio Code con l'estensione client REST per la configurazione e l'esecuzione della pipeline dell'indicizzatore.

Scegliere la configurazione delle autorizzazioni

Prima di creare la registrazione dell'app nel passaggio 3, identificare lo scenario nella tabella seguente. Si notino le autorizzazioni Microsoft Graph necessarie, le autorizzazioni api SharePoint e il tipo di credenziale. Seguire quindi i passaggi collegati più avanti in questo articolo per applicarli.

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

• Le autorizzazioni delegate sono valide solo per i test di piccole dimensioni e non supportano l'inserimento ACL.
• Le credenziali federate sono l'autenticazione senza segreti consigliata. Copre sia l'autenticazione dell'indicizzatore sia la risoluzione dei gruppi di SharePoint in fase di esecuzione della query.
• Quando si usa Sites.Selected, concedere all'app l'accesso esplicito a ogni sito di destinazione SharePoint prima dell'indicizzazione. Il consenso amministratore per Sites.Selected in Microsoft Entra ID non autorizza l'app ad accedere al contenuto del sito. È anche necessario assegnare un'autorizzazione per ogni sito di destinazione. Se si aggiunge un sito all'origine dati senza un'autorizzazione esplicita per il sito, l'indicizzatore non riesce. Vedere Consentire l'accesso al sito quando si usa Sites.Selected.

Formati di documento supportati

Il SharePoint in Microsoft 365 indicizzatore può estrarre testo dai formati di documento seguenti:

• CSV (vedere Indicizzazione di BLOB CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (vedere Indicizzazione di BLOB JSON)
• KML (XML per le rappresentazioni geografiche)
• Markdown
• Microsoft Office formati: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (messaggi di posta elettronica di Outlook), XML (Word XML sia 2003 che 2006)
• Formati di documento aperti: ODT, ODS, ODP
• PDF
• File di testo normale (vedere anche Indicizzazione di testo normale)
• RTF
• XML
• ZIP

Limitazioni e considerazioni

Ecco le limitazioni di questa funzionalità:

• I file del blocco appunti di OneNote non sono supportati.

• Limitazioni dell'indicizzazione incrementale:

  • La ridenominazione di una cartella SharePoint interrompe l'indicizzazione incrementale. Una cartella rinominata viene considerata come nuovo contenuto.

  • Microsoft 365 processi che aggiornano i metadati del file system di SharePoint possono provocare l'indicizzazione incrementale, anche se non sono presenti altre modifiche al contenuto. Testare la configurazione prima di basarsi sull'indicizzatore o sull'arricchimento tramite intelligenza artificiale. Verificare come Microsoft 365 elabora i documenti.

• Limitazioni di sicurezza:

  • Nessun supporto per gli endpoint privati. La configurazione di rete sicura deve essere abilitata tramite un firewall.

  • Nessun supporto per i tenant con Microsoft Entra ID Conditional Access abilitato.

  • Nessun supporto per i file crittografati dall'utente e i file ZIP protetti da password. Tuttavia, il contenuto crittografato è consentito se è protetto da Microsoft Purview etichette di riservatezza e se la configurazione per mantenere e rispettare tali etichette (anteprima) è abilitata.

  • Supporto limitato per le autorizzazioni di accesso a livello di documento. Un livello di base di sincronizzazione ACL è attualmente in anteprima. Per informazioni dettagliate e configurazione, vedere la documentazione di configurazione SharePoint ACL. Per le autorizzazioni necessarie per scenario, vedere Scegliere la configurazione delle autorizzazioni.

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

• Per sviluppare un'app Copilot personalizzata o un'app di generazione aumentata tramite recupero (RAG) che interagisca con i dati di SharePoint tramite Azure AI Search, Microsoft consiglia di usare la fonte di conoscenza SharePoint remota. Questa fonte di conoscenze usa l'API di recupero Copilot per eseguire query sul contenuto testuale direttamente da SharePoint in Microsoft 365, restituendo risultati al motore di recupero basato sull'agentività per l'unione, la classificazione e la formulazione della risposta. Non esiste alcun indice di ricerca usato da questa origine delle informazioni e viene eseguita una query solo sul contenuto testuale. Azure AI Search non duplica i dati. Applica il modello di autorizzazione SharePoint restituendo solo i risultati che ogni utente è autorizzato a visualizzare.

• Se è necessario creare un'applicazione di Copilot/RAG personalizzata o un agente di intelligenza artificiale per chattare con i dati di SharePoint negli ambienti di produzione, è consigliabile crearla direttamente tramite Microsoft Copilot Studio. Se Copilot Studio non soddisfa le tue esigenze, considera:

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

  • Creazione di un flusso di lavoro App per la logica di Azure che usa il connettore App per la logica di Azure SharePoint e il connettore Azure AI Search. Il connettore Azure AI Search è disponibile quando raggiunge la disponibilità generale. Usare il flusso di lavoro generato dalla procedura guidata Azure portale come punto di partenza, quindi personalizzarlo nella finestra di progettazione App per la logica di Azure per aggiungere i passaggi di trasformazione necessari. Il flusso di lavoro creato dalla procedura guidata Azure AI Search è un flusso di lavoro di consumo. Per i carichi di lavoro in produzione, passa a un flusso di lavoro standard di app per la logica per usare le funzionalità aziendali aggiuntive.

Indipendentemente dall'approccio scelto, se creare un connettore personalizzato con webhook SharePoint o creare un flusso di lavoro App per la logica di Azure, assicurarsi di implementare misure di sicurezza affidabili. Queste misure includono la configurazione di collegamenti privati condivisi, la configurazione dei firewall e la conservazione delle autorizzazioni utente dall'origine e il rispetto di tali autorizzazioni in fase di query. Dovresti anche verificare e monitorare regolarmente la pipeline.

Se indicizzate gli ACL di SharePoint, consultate le relazioni tra gruppi supportate. I gruppi Microsoft Entra annidati all'interno dei gruppi di SharePoint non vengono espansi.

Configurare il SharePoint nell'indicizzatore Microsoft 365

Per configurare il SharePoint in Microsoft 365 indicizzatore, usare un'API REST di anteprima. In questa sezione vengono illustrati i passaggi.

(Facoltativo) Passaggio 1: Abilitare un'identità gestita assegnata dal sistema

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

Eseguire questo passaggio se il sito di SharePoint e il servizio di ricerca si trovano nello stesso tenant Microsoft Entra. Ignorare questo passaggio se si trovano in tenant di Microsoft Entra diversi. L'identità viene usata per l'individuazione del tenant. È anche possibile ignorare questo passaggio se si vuole inserire l'ID tenant Microsoft Entra nel stringa di connessione. Per usare l'identità gestita assegnata dal sistema o assegnata dall'utente per l'indicizzazione senza segreto, configurare le autorizzazioni dell'applicazione con l'autenticazione senza segreto.

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

Passaggio 2: Decidere quali autorizzazioni l'indicizzatore richiede

Per la matrice decisionale che copre gli scenari ACL e non ACL, vedere Scegliere la configurazione delle autorizzazioni. Se si scelgono le autorizzazioni delegate, i token con delega dell'utente scadono ogni 75 minuti e richiedono l'indicizzazione manuale usando Run Indexer (anteprima) alla scadenza. Le autorizzazioni delegate sono consigliate solo per operazioni di test di piccole dimensioni.

Passaggio 3: Creare una registrazione dell'applicazione Microsoft Entra

Il SharePoint in Microsoft 365 indicizzatore usa un'applicazione Microsoft Entra per l'autenticazione. Creare la registrazione dell'applicazione prima di configurarne le autorizzazioni e le credenziali.

1. Accedere al portale Azure.

2. Cercare o passare a Microsoft Entra ID.

3. Nella pagina Panoramica selezionare + Aggiungi>registrazione app.

   1. Immettere un nome per l'app.
   2. Selezionare Solo tenant singolo - nome tenant.
   3. Ignorare il passo di assegnazione URI. Non è necessario alcun URI di reindirizzamento.
   4. Selezionare Registra.

4. Nel riquadro sinistro selezionare Gestisci>autorizzazioni API.

5. Selezionare + Aggiungi un'autorizzazione e quindi selezionare Microsoft Graph.

   • Se l'indicizzatore usa le autorizzazioni API dell'applicazione, selezionare Autorizzazioni applicazione.

     • Per l'indicizzazione standard, selezionare:

       • Files.Read.All
       • Sites.Read.All

       

     • Se si abilita ACL inserimento (anteprima), le autorizzazioni necessarie dipendono dai tipi di elemento (file della raccolta documenti, elementi elenco, pagine ASPX) e dai tipi di gruppo (Microsoft Entra e SharePoint gruppi di siti) indicizzati. Prima di completare questo passaggio, consulta scenario delle autorizzazioni tramite ACL. Per il riepilogo dello scenario incrociato, vedere Scegliere la configurazione delle autorizzazioni.

       L'uso delle autorizzazioni dell'applicazione significa che l'indicizzatore accede al sito SharePoint in un contesto del servizio. Pertanto, quando si esegue l'indicizzatore, ha accesso a tutto il contenuto nel tenant SharePoint, che richiede l'approvazione dell'amministratore tenant. Per l'autenticazione è necessario anche un segreto client o una configurazione senza segreto. La configurazione del meccanismo di autenticazione è descritta più avanti in questo articolo in Metodi di autenticazione disponibili solo per le autorizzazioni API dell'applicazione.

   • Se l'indicizzatore usa autorizzazioni API delegate, selezionare Autorizzazioni delegate e quindi selezionare:

     • Files.Read.All
     • Sites.Read.All
     • User.Read

     

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

6. Selezionare Concedere il consenso amministratore per nome del tenant.

   Il consenso dell'amministratore tenant è necessario quando si usano le autorizzazioni API dell'applicazione. Alcuni tenant sono soggetti a restrizioni tali da richiedere anche il consenso dell'amministratore del tenant per le autorizzazioni API delegate. Se si applica una delle due condizioni, un amministratore tenant deve concedere il consenso per questa applicazione Microsoft Entra prima di creare l'indicizzatore.

   

7. Nel riquadro sinistro selezionare Gestisci>autenticazione (anteprima).

8. Nella scheda Configurazione URI di reindirizzamento selezionare + Aggiungi URI di reindirizzamento.

   1. Selezionare Applicazioni per dispositivi mobili e desktop.
   2. Selezionare l'URI https://login.microsoftonline.com/common/oauth2/nativeclient di reindirizzamento.
   3. Seleziona Configura.

9. Nella scheda Impostazioni abilitare l'interruttore Consenti flussi client pubblici e quindi selezionare Salva.

10. Configurare il metodo di autenticazione dell'indicizzatore in base alle esigenze della soluzione.

Concedere l'accesso al sito quando si usa Sites.Selected

Se si configura la registrazione dell'app con Sites.Selected, completare i passaggi seguenti prima di eseguire l'indicizzatore. Il consenso amministratore per Sites.Selected in Microsoft Entra ID consente solo all'app di usare le autorizzazioni di SharePoint con ambito. Non concede l'accesso ad alcun sito finché non si assegna separatamente un'autorizzazione al sito.

1. In Microsoft Entra ID: aggiungere Sites.Selected alla registrazione dell'app e concedere il consenso amministratore. Aggiungere l'autorizzazione nell'area API richiesta dallo scenario, ad esempio Microsoft Graph e, per gli scenari di inserimento ACL, SharePoint.

2. In SharePoint: assegnare all'app un ruolo di autorizzazione in ogni sito di destinazione. Per l'indicizzazione dei contenuti, concedere almeno accesso in lettura.

   Per concedere l'autorizzazione al sito, usare Microsoft Graph. Sostituire {siteId} con l'ID sito:

   POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
   Content-Type: application/json
   
   {
     "roles": ["read"],
     "grantedToIdentities": [
       {
         "application": {
           "id": "<application-client-id>",
           "displayName": "<application-display-name>"
         }
       }
     ]
   }
   

   Per concedere la stessa autorizzazione usando PowerShell PnP:

   Grant-PnPEntraIDAppSitePermission `
     -AppId "<application-client-id>" `
     -DisplayName "<application-display-name>" `
     -Site "https://<tenant>.sharepoint.com/sites/<site-name>" `
     -Permissions Read
   

Metodi di autenticazione disponibili solo per le autorizzazioni API dell'applicazione

Per autenticare l'applicazione Microsoft Entra con le autorizzazioni dell'applicazione, l'indicizzatore usa un segreto client o una configurazione senza segreto.

Uso del segreto del client

Queste istruzioni configurano l'applicazione in modo da usare un segreto client per autenticare l'indicizzatore, in modo da poter inserire dati da SharePoint.

• Selezionare Certificati e segreti dal menu a sinistra e quindi selezionare Segreti client e 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, è necessario ricrearlo e aggiornare l'indicizzatore con il nuovo segreto.

  

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

  

Uso dell'autenticazione senza segreto per ottenere i token dell'applicazione

Usare le credenziali federate per accedere senza un segreto client. Microsoft Entra considera attendibile un'identità gestita per ottenere un token dell'applicazione, in modo che l'indicizzatore possa inserire dati da SharePoint senza un segreto archiviato. La sezione successiva illustra come configurare un'identità gestita.

Configurazione dell'applicazione registrata con un'identità gestita

1. Creare (o selezionare) un'identità gestita assegnata dall'utente e assegnarla al servizio di ricerca o a un'identitàgestita assegnata dal sistema, a seconda dei requisiti dello scenario.

2. Acquisire l'ID dell'oggetto (principale). Usare questo valore come parte della configurazione delle credenziali quando si crea l'origine dati.

3. Selezionare Certificati e segreti dal menu a sinistra.

4. In Credenziali federate selezionare + Aggiungi credenziali.

5. In Scenario di credenziali federate selezionare Identità gestita.

6. Selezionare Identità gestita: scegliere l'identità gestita creata nel passaggio 1.

7. Aggiungere un nome per le credenziali e selezionare Salva.

Passaggio 4: Creare un'origine dati

A partire da questa sezione, usare l'API REST di anteprima più recente e un client REST o l'SDK beta supportato più recente delle preferenze per i passaggi rimanenti.

Un'origine dati specifica i dati da indicizzare, credenziali e criteri per identificare in modo efficiente le modifiche nei dati (righe nuove, modificate o eliminate). Più indicizzatori nello stesso servizio di ricerca possono usare la stessa origine dati.

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

• name è il nome univoco dell'origine dati all'interno del servizio di ricerca.
• Il tipo deve essere "SharePoint". Questo valore fa distinzione tra maiuscole e minuscole.
• credentials forniscono l'endpoint SharePoint e il metodo di autenticazione consentito all'applicazione per richiedere i token di Microsoft Entra. Un esempio di endpoint SharePoint è https://[your-tenant-name].sharepoint.com/teams/MySharePointSite. È possibile ottenere l'endpoint passando alla home page del sito SharePoint e copiando l'URL dal browser. Esaminare il formato stringa di connessione per la sintassi supportata.
• contenitore specifica la raccolta documenti da indicizzare. Le proprietà controllano i documenti indicizzati.

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

Ecco un esempio di definizione di un'origine dati per credenziali con segreto dell'applicazione o identità gestita assegnata dal sistema.

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

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

Le configurazioni delle credenziali federate richiedono FederatedCredentialApplicationId nella stringa di connessione. Il valore è diverso dal tipo di identità:

• Identità gestita assegnata dal sistema: impostare FederatedCredentialApplicationId sull'ID applicazione (client) dell'identità gestita assegnata dal sistema del servizio. Omettere il identity blocco.
• Identità gestita assegnata dall'utente: specificare il identity blocco con il percorso della risorsa identità gestita assegnata dall'utente. Impostare FederatedCredentialApplicationId sull'ID applicazione (client) dell'identità gestita assegnata dall'utente.

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

{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "[connection-string]" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null },
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[Azure subscription ID]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user-assigned managed identity]"
    }
}

Formato stringa di connessione

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

• Formato della stringa di connessione per le autorizzazioni API delegate

  SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]

• Autorizzazioni API dell'applicazione con formato stringa di connessione segreta dell'applicazione

  SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];ApplicationSecret=[Microsoft Entra application client secret];TenantId=[SharePoint site's Microsoft Entra tenant ID]

• Autorizzazioni API dell'applicazione con formato della stringa di connessione senza segreti (credenziale di identità federata):

  SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];FederatedCredentialApplicationId=[managed identity's application (client) ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]

La tabella seguente descrive ogni campo stringa di connessione.

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

Per garantire la compatibilità con le versioni precedenti, l'indicizzatore SharePoint accetta ancora FederatedCredentialObjectId (ID oggetto/entità della credenziale dell'identità federata nell'app di inserimento) nella stringa di connessione, quindi le origini dati esistenti continuano a funzionare senza modifiche. Usare FederatedCredentialApplicationId per le origini dati nuove e aggiornate.

Per ottenere TenantId, aprire il Interfaccia di amministrazione di Microsoft Entra per il tenant proprietario del sito di SharePoint e copiare l'ID tenant da Panoramica.

È possibile ottenere l'identità object (principal) ID gestita dalla sezione Configurazione dell'applicazione registrata con un'identità gestita .

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

Se il sito SharePoint e il servizio di ricerca si trovano nella stessa Microsoft Entra tenant e l'identità gestita assegnata dal sistema è abilitata, non è necessario includere TenantId nella stringa di connessione. Se si trovano in tenant di Microsoft Entra diversi, è necessario includere TenantId.

Gli esempi seguenti mostrano le origini dati create con FederatedCredentialApplicationId:

Identità gestita assegnata dal sistema con credenziali federate:

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

{
  "name": "sharepoint-ds",
  "type": "sharepoint",
  "credentials": {
    "connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[system-assigned managed identity's application (client) ID]"
  },
  "container": { "name": "defaultSiteLibrary" }
}

Identità gestita assegnata dall'utente con credenziali federate (tenant singolo):

{
  "name": "sharepoint-uami-fed",
  "type": "sharepoint",
  "credentials": {
    "connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[user-assigned managed identity application (client) ID]"
  },
  "container": { "name": "defaultSiteLibrary" },
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]"
  }
}

Identità gestita assegnata dall'utente tra tenant con credenziali federate (avanzate):

Prima di usare questa configurazione, assicurarsi che l'identità gestita assegnata dall'utente sia configurata con una credenziale di identità federata che considera attendibile l'app multi-tenant Microsoft Entra. Per la procedura di installazione, vedere Configurazione dell'applicazione registrata con un'identità gestita.

{
  "name": "sharepoint-uami-crosstenantfed",
  "type": "sharepoint",
  "credentials": {
    "connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[multitenant app client ID]"
  },
  "container": { "name": "defaultSiteLibrary" },
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]",
    "federatedIdentityClientId": "[multi-tenant app client ID]"
  }
}

Usare la configurazione cross-tenant dell'identità gestita assegnata dall'utente quando l'identità gestita assegnata dall'utente si federa con un'app Microsoft Entra multi-tenant. In questo caso, impostare federatedIdentityClientId nel blocco identity sull'ID client dell'app multi-tenant e impostare FederatedCredentialApplicationId nella stringa di connessione sull'ID client della stessa app multi-tenant. In questo scenario, l'impostazione di FederatedCredentialApplicationId sull'ID client stesso dell'identità gestita assegnata dall'utente non supera la convalida.

Se l'indicizzatore usa la configurazione ACL di SharePoint (anteprima) o mantiene e rispetta le etichette di riservatezza di Microsoft Purview (anteprima), consulta gli articoli correlati prima di creare l'indicizzatore. Ogni funzionalità include specifici passaggi di configurazione dell'origine dati, dell'indice e del set di competenze.

Passaggio 5: Creare un indice

L'indice specifica i campi in un documento, attributi e altri costrutti che modellano l'esperienza di ricerca.

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

POST https://[service name].search.windows.net/indexes?api-version=2026-08-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 }
    ]
}

Passaggio 6: Creare un indicizzatore

Un indicizzatore connette un'origine dati con un indice di ricerca di destinazione e fornisce una pianificazione per automatizzare l'aggiornamento dei dati. Dopo aver creato l'origine dati e l'indice, creare l'indicizzatore.

Per creare l'indicizzatore:

1. Inviare una richiesta di creazione dell'indicizzatore (anteprima):

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   
   {
       "name" : "sharepoint-indexer",
       "dataSourceName" : "sharepoint-datasource",
       "targetIndexName" : "sharepoint-index",
       "parameters": {
       "batchSize": null,
       "maxFailedItems": null,
       "base64EncodeKeys": null,
       "maxFailedItemsPerBatch": null,
       "configuration": {
           "indexedFileNameExtensions" : ".pdf, .docx",
           "excludedFileNameExtensions" : ".png, .jpg",
           "dataToExtract": "contentAndMetadata"
         }
       },
       "schedule" : { },
       "fieldMappings" : [
           { 
             "sourceFieldName" : "metadata_spo_site_library_item_id", 
             "targetFieldName" : "id", 
             "mappingFunction" : { 
               "name" : "base64Encode" 
             } 
            }
       ]
   }
   

   Per le origini dati che utilizzano i valori del contenitore allSiteLists, allSitePages o allSiteContent, mappare metadata_spo_site_asset_item_id anziché metadata_spo_site_library_item_id.

   Quando si usano le autorizzazioni dell'applicazione, è possibile eseguire query sull'indice mentre è in corso l'esecuzione iniziale dell'indicizzatore, ma solo gli elementi già indicizzati restituiscono risultati. Attendi il completamento dell'esecuzione per ottenere una copertura completa. Le istruzioni rimanenti in questo passaggio si applicano solo alle autorizzazioni delegate.

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

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

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

3. Copia il codice di accesso del dispositivo dalla risposta Get Indexer Status. Il codice di accesso del dispositivo è reperibile 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. Immettere il codice incluso nel messaggio di errore.

   

5. Il SharePoint in Microsoft 365 indicizzatore accede al contenuto SharePoint come utente connesso. L'utente che accede durante questo passaggio è 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 ha accesso a tale documento.

   Se possibile, creare un nuovo account utente dell'organizzazione e concedergli le autorizzazioni esatte che si vuole 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 e entro l'intervallo di tempo di 10 minuti.

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

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, chiamare Get Indexer Status:After creating the indexer, call Get Indexer Status:

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

GET https://[service-name].search.windows.net/indexes/[index-name]/docs?search=*&$count=true&api-version=2026-08-01-preview
api-key: [admin-api-key]

Aggiornare l'origine dati

Se non si aggiorna l'oggetto origine dati, l'indicizzatore viene eseguito in base a una pianificazione senza alcuna interazione dell'utente.

Se si modifica l'origine dati mentre il codice del dispositivo è scaduto, accedere di nuovo per eseguire l'indicizzatore. Ad esempio, se si modifica la query dell'origine dati, accedere di nuovo usando https://microsoft.com/devicelogin e ottenere il nuovo codice del dispositivo.

Per aggiornare un'origine dati, seguire questa procedura presupponendo un codice del dispositivo scaduto:

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

   POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2026-08-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=2026-08-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 l'indicizzatore manualmente e controllare lo stato dell'indicizzatore. Questa volta l'esecuzione dell'indicizzatore dovrebbe essere avviata correttamente.

Metadati del documento di indice

Se si indicizzano i metadati del documento ("dataToExtract": "contentAndMetadata"), è possibile usare i metadati seguenti per l'indicizzazione.

Il SharePoint in Microsoft 365 indicizzatore supporta anche metadati specifici di ogni tipo di documento. Per altre informazioni, vedere proprietà dei metadati Content usate in Azure AI Search.

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

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

Indicizzare elenchi di SharePoint

elenchi di SharePoint sono indicizzabili in anteprima, a partire dalla versione di anteprima 2026-05-01 dell'API REST. Impostare l'origine dati container.name su allSiteLists per indicizzare tutte le voci dell'elenco di un sito, oppure su allSiteContent per combinare le voci dell'elenco con le librerie di documenti e le pagine del sito in un unico indicizzatore. Per includere elenchi di siti secondari, aggiungere includeSubsites=true all'oggetto container.query.

Per gli indicizzatori basati su elenco o a contenuto misto, il campo della chiave dell'indice deve essere mappato da metadata_spo_site_asset_item_id. Il contenuto dell'elemento content di elenco viene visualizzato nel campo come valori di campo in formato JSON e i campi standard metadata_spo_item_* (ad esempio metadata_spo_item_name, metadata_spo_item_weburie metadata_spo_item_last_modified) vengono popolati per ogni voce di elenco.

Associare le colonne dell'elenco ai campi dell'indice

Ogni colonna definita in un SharePoint list viene visualizzata come campo di origine con lo stesso nome della colonna SharePoint. Usa le mappature dei campi per associare ogni colonna a un campo dell'indice.

Si consideri, ad esempio, un SharePoint list con le colonne seguenti.

Aggiungere campi corrispondenti alla definizione dell'indice e quindi eseguire il mapping di ogni colonna al relativo campo di destinazione nell'indicizzatore:

{
  "name": "my-sharepoint-list-indexer",
  "dataSourceName": "my-sharepoint-list-ds",
  "targetIndexName": "products-index",
  "fieldMappings": [
    {
      "sourceFieldName": "metadata_spo_site_asset_item_id",
      "targetFieldName": "id",
      "mappingFunction": { "name": "base64Encode" }
    },
    { "sourceFieldName": "Title", "targetFieldName": "productName" },
    { "sourceFieldName": "Price", "targetFieldName": "price" },
    { "sourceFieldName": "InStock", "targetFieldName": "available" },
    { "sourceFieldName": "Category", "targetFieldName": "category" },
    { "sourceFieldName": "metadata_spo_item_last_modified", "targetFieldName": "lastUpdated" },
    { "sourceFieldName": "metadata_spo_item_weburi", "targetFieldName": "itemUrl" }
  ]
}

Assicurarsi che ogni campo di destinazione esista nell'indice con un tipo compatibile, Edm.String ad esempio per Titleo Edm.DoubleEdm.Int64 per Price, Edm.Boolean per InStock.

Pagine del sito in formato ASPX

È possibile indicizzare le pagine moderne del sito ASPX in anteprima, a partire dall'API REST 2026-05-01-preview. Impostare l'origine dati container.name su allSitePages per indicizzare tutte le pagine di un sito oppure su allSiteContent per combinare pagine con librerie di documenti ed elenchi in un unico indicizzatore. Per includere pagine del sito secondario, aggiungere includeSubsites=true all'oggetto container.query.

Per gli indicizzatori basati su pagine o a contenuto misto, il campo della chiave dell'indice deve essere mappato da metadata_spo_site_asset_item_id. Il testo della pagina viene estratto nel content campo e i campi standard metadata_spo_item_* (ad esempio metadata_spo_item_name, metadata_spo_item_weburie metadata_spo_item_last_modified) vengono popolati per ogni pagina.

Includere o escludere in base al tipo di file

Impostare criteri di inclusione ed esclusione nella sezione "parametri" della definizione dell'indicizzatore per controllare quali file vengono indicizzati.

Per includere estensioni di file specifiche, impostare su "indexedFileNameExtensions" un elenco delimitato da virgole di estensioni di file con un punto iniziale. Per escludere estensioni di file specifiche, impostare "excludedFileNameExtensions" sulle estensioni da ignorare. Se la stessa estensione viene visualizzata in entrambi gli elenchi, l'indicizzatore lo esclude dall'indicizzazione.

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

Controllare quali documenti sono indicizzati

Un singolo SharePoint in Microsoft 365 indicizzatore può indicizzare il contenuto da una o più raccolte documenti. Per specificare i siti e le raccolte documenti da indicizzare, usare il parametro "contenitore" nella definizione dell'origine dati.

La sezione "contenitore" della fonte di dati ha due proprietà per questo compito: "name" e "query".

Nome

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

Per le origini dati che usano allSiteLists, allSitePages o allSiteContent, il mapping del campo chiave dell'indicizzatore deve usare metadata_spo_site_asset_item_id anziché metadata_spo_site_library_item_id. Per informazioni dettagliate, vedere Passaggio 6: Creare un indicizzatore.

Query

Il parametro "query" dell'origine dati è costituito da coppie di parole chiave/valore. Usare le parole chiave seguenti. I valori sono URL del sito o URL della raccolta documenti.

Quando si configurano le autorizzazioni, prendere in considerazione le informazioni seguenti:

Per ottenere il valore per una parola chiave specifica, passare alla raccolta documenti da includere o escludere e copiare l'URI dal browser. Questo metodo è il modo più semplice per ottenere il valore da usare con una parola chiave nella query.

Gestire gli errori

Per un messaggio Invalid AAD tenant, un ID tenant Microsoft Entra mancante o un tenant non corrispondente che compare nella cronologia di esecuzione dell'indicizzatore, vedere Risolvere errori e avvisi comuni dell'indicizzatore.

Per impostazione predefinita, il SharePoint in Microsoft 365 indicizzatore si arresta non appena rileva un documento con un tipo di contenuto non supportato, ad esempio un'immagine. Usare il excludedFileNameExtensions parametro per ignorare determinati tipi di contenuto. Tuttavia, potrebbe essere necessario indicizzare i documenti senza conoscere in anticipo tutti i tipi di contenuto possibili. Per continuare l'indicizzazione quando l'indicizzatore rileva un tipo di contenuto non supportato, impostare il failOnUnsupportedContentType parametro di configurazione su false:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-08-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 questa modalità di errore, impostare il failOnUnprocessableDocument parametro di configurazione su false:

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

I file di origine di SharePoint utilizzano i limiti condivisi relativi alla dimensione dei file di origine e al numero di caratteri estratti per gli indicizzatori di tipo BLOB. Per impostazione predefinita, i documenti sovradimensionati vengono considerati come errori. Tuttavia, è comunque possibile indicizzare i metadati di archiviazione dei documenti sovradimensionati se si imposta il indexStorageMetadataOnlyForOversizedDocuments parametro di configurazione su true:

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

Se si aggiunge un set di competenze, controllare separatamente i limiti di input e di servizio downstream di ogni competenza. Una competenza può accettare meno dati rispetto agli estratti dell'indicizzatore SharePoint.

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

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

Contenuto correlato

• Video di YouTube: indicizzazione di SharePoint in Microsoft 365
• Indicizzatori in Azure AI Search
• Proprietà dei metadati di contenuto utilizzate in Azure AI Search
• Indicizza il contenuto di SharePoint e altre origini di contenuto in Azure AI Search usando i connettori di Azure Logic App
• Inserire la configurazione ACL di SharePoint (anteprima)
• Sincronizzare ACL tra SharePoint e l'indice
• Configurare il supporto dei gruppi di SharePoint
• Preserve e onorare le etichette di riservatezza di Microsoft Purview (anteprima)