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

Questo articolo illustra come inserire un elenco di controllo di accesso (ACL) insieme ad altri contenuti di SharePoint in Microsoft 365 usando un indicizzatore di Ricerca di intelligenza artificiale di Azure. Le autorizzazioni di SharePoint vengono mantenute come metadati di autorizzazione per ogni documento indicizzato. Quando gli utenti eseguono query su un indice contenente contenuto da SharePoint, i risultati della ricerca sono costituiti solo dai documenti a cui dispongono dell'autorizzazione per l'accesso.

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.

• Configurare le autorizzazioni dell'applicazione con Files.Read.All e Sites.FullControl.All (o Sites.Selected invece di Sites.FullControl.All) per indicizzare solo il contenuto e le autorizzazioni di siti specifici. Concedere quindi all'applicazione autorizzazioni di controllo completo per i siti selezionati.

• API REST versione 2025-11-01-preview o un pacchetto SDK di anteprima equivalente.

Limitazioni

• Durante l'anteprima pubblica, l'inserimento ACL si applica solo all'indicizzazione iniziale. Gli ACL vengono acquisiti al primo inserimento di ogni file. Se le autorizzazioni cambiano nell'origine, è necessario reindicizzare in modo esplicito tali documenti o i rispettivi elenchi di controllo di accesso.

• Il portale di Azure non supporta questa funzionalità.

• In questa anteprima non sono supportati gli elementi seguenti:

  • Criteri di SharePoint Information Management applicabili all'accesso utente.

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

  • Gruppi di SharePoint che non possono essere risolti nei gruppi di Microsoft Entra (ad esempio Proprietari, Membri, Gruppi visitatori).

• Le funzionalità dell'indicizzatore seguenti non supportano l'ereditarietà delle autorizzazioni nei documenti indicizzati provenienti da ADLS Gen2. 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

  • Competenza Prompt GenAI

  • Archivio conoscenze

  • Cache di arricchimento dell'indicizzatore

  • Sessioni di debug

Supporto per il modello di autorizzazione di SharePoint

Questa anteprima supporta solo gli ACL di base per i documenti, come illustrato nella tabella seguente. L'indicizzatore di SharePoint non supporta l'inserimento di elenchi, quindi esclude le autorizzazioni degli elenchi.

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.

Configurare il servizio di ricerca per l'inserimento ACL e rispettare in fase di query

Questi passaggi consentono di configurare il servizio di ricerca per l'acquisizione di ACL e di rispettare l'ACL durante l'esecuzione della query.

1. Configurazione dell'origine 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 recuperabile da true a false senza la necessità di ricompilare l'indice.

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

Se l'indicizzatore usa un set di competenze con suddivisione in blocchi di dati, ad esempio una competenza divisa quando si abilita la vettorizzazione integrata, assicurarsi di eseguire il mapping delle proprietà ACL a ogni blocco usando proiezioni di indice.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2025-11-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" }, // <-- parent → child
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" } // <-- parent → child
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

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

Oltre alla configurazione dell'indicizzatore richiesta, mappare i 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" }
  ]
}

Sincronizzare le autorizzazioni tra il contenuto indicizzato e quello di origine

Durante l'anteprima pubblica, quando la configurazione è completata, le ACL vengono acquisite durante la prima esecuzione dell'indicizzatore e solo per i nuovi file. Per riprendere le modifiche apportate successivamente:

Reimpostare documenti specifici

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

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2025-11-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=2025-11-01-preview
{
  "options": ["permissions"]
}

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

Contenuto correlato

• Indicizzare il contenuto di SharePoint in Azure AI Search (anteprima)
• Imposizione dell'ACL al tempo di query