Indicizzazione degli elenchi di controllo di accesso ai documenti (ACL) tramite le API REST push (anteprima)

L'inserimento delle autorizzazioni a livello di documento tramite le API REST push (anteprima) consente di indicizzare i documenti insieme ai relativi elenchi di controllo di accesso (ACL) associati e ai ruoli controllo degli accessi in base al ruolo del contenitore. Quando si esegue il push del contenuto in un indice Azure AI Search tramite le API REST push, il servizio mantiene tali autorizzazioni per il contenuto indicizzato e le applica in fase di query.

Le funzionalità principali includono:

• Controllo flessibile sulle pipeline di inserimento.
• Schema standardizzato per i metadati delle autorizzazioni.
• Supporto per autorizzazioni gerarchica, ad esempio ACL a livello di cartella.

Questo articolo illustra come usare l'API REST push per indicizzare i metadati delle autorizzazioni a livello di documento in Azure AI Search. Questo processo prepara l'indice per eseguire query e applicare le autorizzazioni degli utenti finali ai risultati di ricerca.

Prerequisiti

• Contenuto con metadati ACL da Microsoft Entra ID o da un altro sistema ACL di tipo POSIX. Per i campi ACL userIds e groupIds, usare gli ID oggetto di Microsoft Entra (GUID) e non gli UPN o gli indirizzi di posta elettronica. Gli ID oggetto stabile garantiscono la corrispondenza affidabile delle identità in fase di query, anche se gli attributi della directory cambiano.

• L'API REST latest preview o un pacchetto Azure SDK di anteprima che fornisce funzionalità equivalenti.

• Schema di indice con permissionFilterOption abilitato, oltre a permissionFilter attributi di campo che memorizzano le autorizzazioni del documento.

Limitazioni

• Un campo ACL con tipo di userIds filtro di autorizzazione o groupIds può contenere al massimo 1000 valori.

• Un indice può contenere al massimo cinque valori univoci tra i campi di tipo rbacScope in tutti i documenti. Non esiste alcun limite al numero di documenti che condividono lo stesso valore di rbacScope.

• È possibile aggiornare un campo esistente per includere un'assegnazione permissionFilter per il filtro dei metadati ACL o RBAC predefinito. Per abilitare il filtro in base a un indice esistente, aggiungere nuovi campi o aggiornare i campi esistenti per includere un permissionFilter valore.

• Un solo campo di ogni permissionFilter tipo (uno di groupIds, userIdse rbacScope) può esistere in un indice.

• Ogni permissionFilter campo deve essere filterable impostato su true.

• L'applicazione delle autorizzazioni al momento della query riflette i valori ACL scritti più di recente nell'indice. Se le autorizzazioni di origine cambiano, tali aggiornamenti non vengono riflessi fino a quando non si esegue il ripristino o l'aggiornamento dei documenti interessati. Pianificare la ripetizione incrementale o gli aggiornamenti parziali per mantenere aggiornati gli elenchi di controllo di accesso.

• Questa funzionalità non è attualmente supportata nel portale di Azure.

Creare un indice con campi di filtro delle autorizzazioni

L'indicizzazione degli ACL del documento e dei metadati RBAC con l'API REST richiede la configurazione di uno schema di indice che abilita i filtri di autorizzazione e include campi con assegnazioni di filtro delle autorizzazioni.

Per prima cosa, aggiungere permissionFilterOption. I valori validi sono enabled o disablede è necessario impostarlo su enabled. È possibile passare a disabled se si vuole disattivare la funzionalità di filtro delle autorizzazioni a livello di indice.

In secondo luogo, creare campi stringa per i metadati delle autorizzazioni e includere permissionFilter. Tenere presente che è possibile avere uno di ogni tipo di filtro delle autorizzazioni.

Ecco uno schema di esempio di base che include tutti i permissionFilter tipi:

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

Per i repository aziendali, ad esempio SharePoint Online, risolvere le autorizzazioni a livello di documento o di cartella negli ID oggetto utente e gruppo di Microsoft Entra durante l'acquisizione prima di chiamare l'API push. È quindi necessario archiviare tali ID nei campi di autorizzazione corrispondenti.

Esempio di indicizzazione dell'API REST

Dopo aver creato un indice con campi di filtro autorizzazioni, è possibile popolare tali valori usando l'API di indicizzazione push, esattamente come qualsiasi altro campo del documento. Di seguito è riportato un esempio che usa lo schema di indice specificato, in cui ogni documento specifica l'azione di indicizzazione, il campo chiave (DocumentId) e i campi di autorizzazione. I documenti devono includere anche contenuto, ma tale campo viene omesso in questo esempio per brevità.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Regole di determinazione dell'accesso ACL

Questa sezione illustra in che modo il sistema determina l'accesso ai documenti di un utente in base ai campi di autorizzazione per ogni documento. Questi campi sono ACL (userIds e , dove groupIds includono gruppi di sicurezza e Gruppi di Microsoft 365) o un ambito RBAC (groupIdsrbacScope). Azure valuta l'ambito RBAC e gli ACL in un ordine definito, coerente con il modello di autorizzazioni ADLS Gen2.

Un utente ottiene l'accesso soddisfacendo uno dei campi seguenti: una voce corrispondente in userIds o groupIds, oppure un'assegnazione di ruolo Azure idonea per il rbacScope. Per informazioni su come viene fornita l'identità del chiamante al momento della query, vedere Applicazione di ACL e RBAC al momento della query.

Valori ACL speciali "all" e "none"

I campi ACL, ad esempio userIds e groupIds, in genere contengono elenchi di GUID (Identificatori univoci globali) che identificano utenti e gruppi con accesso al documento. Per questi tipi di campo ACL sono supportati due valori stringa speciali, "all" e "none". Questi valori fungono da filtri generali per controllare l'accesso a livello globale, come illustrato nella tabella seguente.

Poiché un utente deve corrispondere a un solo tipo di campo, il valore speciale "all" concede l'accesso pubblico indipendentemente dagli altri valori di campo ACL. Al contrario, l'impostazione userIds su "none" o una matrice vuota indica che nessun utente ha accesso al documento in base all'ID utente. Potrebbero comunque essere concessi l'accesso tramite l'ID del gruppo o i metadati RBAC corrispondenti.

Esempio di controllo di accesso

In questo esempio viene illustrato come vengono risolte le regole di accesso ai documenti in base ai valori dei campi di autorizzazione in userIds, groupIdse rbacScope. Per facilitare la lettura, in questo scenario si usano alias come "user1" e "group1" anziché GUID; nell'ambiente di produzione, usare gli ID oggetto di Microsoft Entra (GUID).

Contenuti correlati

• Connettiti ad Azure AI Search utilizzando i ruoli
• Applicazione dell'elenco di controllo di accesso e del controllo degli accessi in base al ruolo in fase di query
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API