Usare un indicizzatore SharePoint per inserire i metadati delle autorizzazioni e filtrare i risultati della ricerca in base ai diritti di accesso utente (anteprima)

L'acquisizione dei metadati delle autorizzazioni di SharePoint (anteprima) utilizza un indicizzatore di Azure AI Search per mantenere i metadati delle autorizzazioni, ad esempio gli elenchi di controllo di accesso (ACL), insieme ad altri contenuti di SharePoint in Microsoft 365. L'indicizzatore archivia le autorizzazioni come metadati in ogni documento indicizzato. In fase di query, gli utenti ricevono solo i documenti a cui hanno l'autorizzazione per accedere.

Prerequisiti

• Azure AI Search su un piano a pagamento (Basic o superiore) in qualsiasi regione.

• SharePoint in siti, raccolte, cartelle e file di Microsoft 365 con autorizzazioni configurate.

• Completare tutti i passaggi di configurazione nella documentazione dell'indicizzatore di SharePoint, applicando i requisiti specifici dell'elenco di controllo di accesso descritti in questo articolo.

• Configura le autorizzazioni dell'applicazione di Microsoft Entra e una credenziale appropriata per il tuo scenario. Vedi lo scenario delle autorizzazioni tramite ACL. L'inserimento ACL richiede le autorizzazioni dell'applicazione. Le autorizzazioni delegate non sono supportate. Per la decisione tra autorizzazioni applicative e delegate, vedi Scegli la configurazione delle autorizzazioni.

• API REST versione 2026-08-01-preview o un pacchetto SDK di anteprima equivalente.

Limitazioni

• Gli aggiornamenti incrementali dell'elenco di controllo di accesso richiedono l'API REST 2026-05-01-preview o versioni successive. Nelle versioni precedenti dell'API di anteprima, il sistema acquisisce gli elenchi di controllo di accesso solo al primo inserimento di ogni elemento. Le modifiche alle autorizzazioni successive richiedono la reindicizzazione esplicita. Per la procedura di migrazione, vedere Sincronizzare le autorizzazioni tra il contenuto indicizzato e quello di origine.

• Le modifiche alle autorizzazioni dell'ambito padre non vengono rilevate automaticamente durante le successive esecuzioni dell'indicizzatore. Per le opzioni di aggiornamento, vedere Sincronizzare le autorizzazioni tra il contenuto indicizzato e quello di origine.

• Il portale di Azure non supporta questa funzionalità.

• In questa anteprima non sono supportate le funzionalità seguenti:

  • Criteri di SharePoint Information Management applicabili all'accesso utente. Il sistema non valuta, non acquisisce né applica tali criteri al momento dell'esecuzione della query.

  • Collegamenti condivisibili con ambito "Chiunque" o "Persone nell'organizzazione". Sono supportati solo i collegamenti con ambito "Utenti specifici".

  • gruppi di SharePoint (come i gruppi Proprietari, Membri e Visitatori) sono supportati a partire dalla versione 2026-05-01-preview dell'API REST. Vedere Configurare il supporto dei gruppi di SharePoint. Nelle versioni precedenti dell'API di anteprima, sono supportati solo i gruppi di SharePoint che corrispondono a gruppi di Microsoft Entra.

• Le funzionalità dell'indicizzatore seguenti non supportano l'ereditarietà delle autorizzazioni nei documenti indicizzati provenienti da SharePoint. Se si usa una di queste funzionalità in un set di competenze o in un indicizzatore, le autorizzazioni a livello di documento non vengono incluse nel contenuto indicizzato.

  • Competenza API Web personalizzata

  • Archivio conoscenze, incluso l'archivio asset necessario per la gestione delle immagini (anteprima) nel recupero agentico. Pertanto, la distribuzione delle immagini non è supportata per le fonti di conoscenza che utilizzano gli ACL di SharePoint.

  • Cache di arricchimento dell'indicizzatore

  • Sessioni di debug

Supporto per il modello di autorizzazione di SharePoint

Questa anteprima supporta gli elenchi di controllo di accesso di base per documenti, elementi di elenco e pagine moderne del sito ASPX.

Relazioni di gruppo supportate

La transitività dei gruppi di Microsoft Entra si applica all'interno di Microsoft Entra. Non espande i gruppi di Microsoft Entra che sono membri di gruppi di SharePoint.

Come vengono valutate le autorizzazioni gerarchica

Le autorizzazioni di SharePoint ereditano la gerarchia della raccolta → sito → cartella → file, a meno che l'ereditarietà non venga interrotta.

Durante l'inserimento, l'indicizzatore raccoglie gli identificatori utente e gruppo (ID) a ogni livello e calcola l'ACL effettivo per ogni file.

Autorizzazioni per scenario ACL

Le autorizzazioni dell'applicazione Microsoft Entra e il tipo di credenziale necessari per l'inserimento ACL dipendono dai tipi di elemento e dai tipi di gruppo indicizzati. Nella registrazione dell'app vengono aggiunte tutte le autorizzazioni in Autorizzazioni> APIAggiungere un'autorizzazione e le credenziali federate vengono aggiunte in Certificati e segreti>Credenziali federate. Per istruzioni dettagliate e screenshot, vedere P 3: Creare una registrazione dell'applicazione Microsoft Entra e Configurare l'applicazione registrata con un'identità gestita.

Una credenziale federata autentica l'app usando un'identità gestita attendibile anziché un segreto client. La stessa credenziale federata copre sia l'inserimento (indicizzatore) che la valutazione in fase di query dei gruppi di siti SharePoint. Per la procedura di installazione, vedere Configurazione dell'applicazione registrata con un'identità gestita.

Prima di abilitare l'acquisizione ACL

Completare questi passaggi nell'applicazione Microsoft Entra registrata:

1. Identifica lo scenario nella tabella precedente in base a ciò che intendi indicizzare (file delle raccolte documenti, elementi degli elenchi, pagine ASPX del sito) e al fatto che sia necessario rispettare i gruppi del sito di SharePoint.
2. Aprire la registrazione dell'app nel Interfaccia di amministrazione di Microsoft Entra e passare a autorizzazioni API>Aggiungi un'autorizzazione.
3. Aggiungere le autorizzazioni Microsoft Graph elencate per lo scenario. Concedere il consenso amministratore.
4. Se lo scenario richiede anche autorizzazioni di SharePoint, selezionare Aggiungi un'autorizzazione, scegliere di nuovo l'API SharePoint e aggiungere Sites.FullControl.All (o Sites.Selected). Concedere il consenso amministratore.
5. Configurare le credenziali:
   • Per gli scenari solo Microsoft Graph, è possibile usare un segreto client (Certificates & secretsClient secrets) o una credenziale federata.
   • Per qualsiasi scenario che preveda autorizzazioni di SharePoint, aggiungere una credenziale federata in Certificates & secrets>Credenziali federate. Vedere Configurazione dell'applicazione registrata con un'identità gestita.
6. Concedere all'applicazione l'accesso ai siti di SharePoint di destinazione (particolarmente importante quando si usa Sites.Selected per l'accesso con ambito) in modo da poter leggere il contenuto e le autorizzazioni da indicizzare.

Trovare gli identificatori di Microsoft Entra corretti

Ogni identificatore compare in una posizione diversa nel portale di Azure e corrisponde a uno specifico campo di configurazione. Usare questa sezione come riferimento quando si configura SharePoint inserimento ACL con credenziali federate. Si fa riferimento a questi identificatori in Configurare il supporto per i gruppi di SharePoint e nella stringa di connessione dell'origine dati.

ID dell'applicazione della credenziale federata

Per FederatedCredentialApplicationId nella stringa di connessione dell'origine dati e federatedCredentialId nella definizione dell'indice, usare l'ID applicazione (client) dell'identità gestita, non l'ID dell'app di inserimento.

Identità gestita assegnata dal sistema:

1. Vai al servizio Azure AI Search.
2. Selezionare Sicurezza e identità di rete>.
3. Nella scheda Assegnata dal sistema prendere nota dell'ID oggetto (entità).
4. Passare a Microsoft Entra ID>Gestisci>applicazioni aziendali.
5. Cerca il nome del servizio di ricerca o incolla l'ID oggetto (principale) nella casella di ricerca.
6. Selezionare il risultato e aprire Proprietà. Copiare l'ID applicazione illustrato di seguito, ovvero il valore per FederatedCredentialApplicationId nell'origine dati e federatedCredentialId nell'indice.

Identità gestita assegnata dall'utente:

1. Passare alla risorsa identità gestita assegnata dall'utente.
2. Selezionare Impostazioni>Proprietà.
3. Copiare l'ID client, ovvero il valore per FederatedCredentialApplicationId nell'origine dati e federatedCredentialId nell'indice.

Configura il tuo servizio di ricerca per l'acquisizione delle ACL e l'applicazione delle stesse in fase di interrogazione

Questa procedura consente di configurare il servizio di ricerca per l'acquisizione dell’elenco di controllo di accesso e di rispettare l’elenco di controllo di accesso in fase di query.

Scegliere dove compilare i campi ACL

La posizione in cui si esegue il mapping dei campi dei metadati ACL dipende dal fatto che l'indicizzatore scriva un documento per ogni elemento di origine o più blocchi per ogni elemento di origine.

In tutti gli scenari con suddivisione in blocchi, ogni blocco deve includere i campi ACL. I filtri di autorizzazione si applicano per documento, quindi non è possibile restituire un blocco di campi ACL mancanti al chiamante corretto.

1. Configurazione dell'origine dati

Questa sezione rappresenta un'estensione rispetto alla base Fase 4: Guida passo passo alla creazione di una fonte dati. Impostare indexerPermissionOptions nella definizione dell'origine dati per consentire l'indicizzazione di userIds e groupIds dai documenti di SharePoint.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Aggiungere campi di autorizzazione alla definizione dell'indice

Aggiungere campi alla definizione dello schema di indice per archiviare gli elenchi di controllo di accesso (ACL) e supportare il filtro durante l'esecuzione delle query.

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Impostare retrievable l'attributo su true solo durante lo sviluppo per verificare i valori. È possibile modificare il valore di recuperabilità da true a false senza dover ricompilare l'indice.

3. Configurare le proiezioni di indici nel set di competenze (se applicabile)

Quando la suddivisione in blocchi è abilitata, il documento padre non viene scritto nell'indice quando projectionMode è skipIndexingParentDocuments. Portare i metadati ACL in ogni blocco tramite indexProjections.selectors[].mappings.

Se l'indicizzatore usa un set di competenze con suddivisione in blocchi di dati, ad esempio la competenza Divisione testo quando si abilita la vettorizzazione integrata, assicurarsi di eseguire il mapping delle proprietà ACL a ogni blocco usando proiezioni di indice. Le // righe nell'esempio seguente sono annotazioni illustrative e non sono JSON valide. Rimuoverli prima di inviare la richiesta.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds, GroupIds e SharePointSiteUrl leggono i metadati a livello di origine generati dall'indicizzatore di SharePoint (/document/metadata_*) e scrivono i valori su ogni blocco.

4. Configurare le mappature dei campi dell'indicizzatore per le ACL

Usare i mapping dei campi dell'indicizzatore quando l'indicizzatore scrive un documento per ogni elemento di origine (senza suddivisione in blocchi) o quando si mantiene un indice padre separato insieme a un indice di blocco. Se il set di competenze suddivide i documenti in un unico indice di destinazione con projectionMode: skipIndexingParentDocuments, le mappature dei campi mostrate qui vengono sostituite da indexProjections.mappings del passaggio precedente per l'indice dei frammenti.

Oltre alla configurazione dell'indicizzatore necessaria, eseguire il mapping dei campi ACL dei metadati non elaborati da SharePoint ai campi dell'indice.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. Avviare l'indicizzatore

I metadati ACL vengono inseriti durante l'esecuzione dell'indicizzatore. Dopo aver creato o aggiornato l'indicizzatore (vedere Passaggio 6: Creare un indicizzatore), attivare un'esecuzione in modo che l'indicizzatore inserisca gli ACL insieme al contenuto.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Se è stato abilitato l'inserimento ACL in un indicizzatore esistente che già ha indicizzato gli elementi, chiamare /resync con options: ["permissions"] per riempire gli ACL per tali elementi o /resetdocs per estrarre nuovamente elementi specifici.

6. Verifica dell'acquisizione dell'ACL

Per verificare che i valori ACL siano stati inseriti correttamente:

1. Imposta temporaneamente retrievable su true per UserIds e GroupIds nella definizione dell'indice. La modifica retrievable non richiede una ricompilazione dell'indice.
2. Eseguire una query con privilegi elevati di lettura che seleziona UserIds e GroupIdse verificare che le raccolte non siano vuote. Per gli scenari in blocchi, verificare che ogni blocco porti entrambi i campi.
3. Tornare retrievable a false dopo la verifica.

Configurare il supporto dei gruppi di SharePoint

A partire dall'API REST in versione 2026-05-01-preview, l'indicizzatore di SharePoint può acquisire le appartenenze ai gruppi del sito di SharePoint (Proprietari, Membri, Visitatori e gruppi del sito personalizzati). Ne tiene conto al momento dell'esecuzione della query. Gli ID gruppo di SharePoint vengono riportati nel campo metadata_group_ids con il prefisso spg: per distinguerli dagli ID oggetto dei gruppi di Microsoft Entra.

Questa guida è completa: segui i passaggi in ordine per configurare l'indice, le mappature dei campi dell'indicizzatore ed eseguire query sull'indice con l'applicazione delle impostazioni del gruppo di siti di SharePoint.

I seguenti componenti funzionano insieme per abilitare la risoluzione dei gruppi di siti di SharePoint:

1. Prerequisiti

• L'indicizzatore di SharePoint è già configurato per l'acquisizione degli ACL. Vedere Configurare le mappature dei campi dell'indicizzatore per le ACL.
• Registrazione di app di Microsoft Entra con una credenziale di identità federata. Vedere Configurazione dell'applicazione registrata con un'identità gestita.
• API REST 2026-05-01-preview o versioni successive.

2. Configurare l'indice

Aggiungere la configurazione sharePointConnectorAppRegistration e il campo SharePointSiteUrl insieme ai campi filtro delle autorizzazioni UserIds e GroupIds, in modo che la struttura completa dell'indice sia in un unico punto. Mantieni permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Configurare i mapping dei campi dell'indicizzatore

Eseguire il mapping dei campi di metadati SharePoint ai campi dell'indice in un singolo blocco di mapping combinato. Le prime due mappature sono le stesse utilizzate per l'acquisizione ACL standard; la terza mappatura attiva la risoluzione dei gruppi di SharePoint.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Se il set di competenze suddivide i documenti in blocchi (ad esempio, con la competenza Suddivisione del testo per la vettorializzazione integrata), proiettare invece SharePointSiteUrl su ogni blocco tramite indexProjections.mappings. Vedi Scegliere dove compilare i campi ACL.

4. Eseguire una query sull'indice

Non è necessaria alcuna modifica sul lato client. Lo stesso token x-ms-query-source-authorization attiva sia l'applicazione delle impostazioni di Microsoft Entra che quelle del gruppo di siti di SharePoint. Il servizio di ricerca risolve lato server le appartenenze ai gruppi di SharePoint utilizzando sharePointConnectorAppRegistration nell'indice.

Per la struttura della richiesta, vedi l'esempio di query generale e l'esempio specifico di SharePoint con imposizione del gruppo di siti di SharePoint.

5. Verificare

Per confermare che gli ID dei gruppi di SharePoint siano stati inseriti nell'indice, eseguire una query elevated-read che selezioni GroupIds e cercare nella risposta i valori con prefisso spg:.

Sincronizzare le autorizzazioni tra il contenuto indicizzato e quello di origine

A partire dall'API REST 2026-05-01-preview, le modifiche ACL per gli elementi con autorizzazioni univoche vengono rilevate e aggiornate in ogni esecuzione corretta dell'indicizzatore. L'indicizzatore usa i token di modifica di SharePoint per rilevare in modo incrementale le aggiunte e le rimozioni delle assegnazioni dei ruoli, allo stesso modo in cui rileva le modifiche al contenuto.

Alcuni scenari richiedono comunque un aggiornamento esplicito:

Reimpostare documenti specifici

È possibile reimpostare documenti specifici per inserire nuovamente contenuto e ACL.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

Risincronizzare gli elenchi di controllo di accesso in tutta l'origine dati

È possibile risincronizzare il contenuto ACL completo del set di dati dopo l'inserimento iniziale. Per avere esito positivo, questa operazione richiede un'esecuzione dell'indicizzatore dopo il completamento.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

Dopo aver indicizzato i dati e gli ACL, è possibile eseguire query sull'indice.

Risoluzione dei problemi

Per risultati mancanti, imprevisti o non riusciti in fase di query dopo l'indicizzazione dei metadati ACL, vedere Risolvere i problemi relativi al filtro delle autorizzazioni SharePoint.

Contenuto correlato

• Indicizzare il contenuto di SharePoint in Azure AI Search (anteprima)
• Applicazione dell’elenco di controllo di accesso in fase di query