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

Indicizzazione di documenti, insieme agli Elenchi di Controllo Accessi (ACL) e ai ruoli del Controllo Accessi basato sui Ruoli (RBAC) nei contenitori associati, in un indice di Azure AI Search tramite le API REST push, mantiene l'autorizzazione a livello di documento per il contenuto indicizzato al momento della 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.

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

• 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"
}

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-05-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 come viene determinato l'accesso ai documenti per un utente in base ai valori ACL assegnati a ogni documento. La regola chiave è che un utente deve corrispondere solo a un tipo ACL per ottenere l'accesso al documento. Ad esempio, se un documento contiene campi per userIds, groupIdse rbacScope, l'utente può accedere al documento associando uno di questi campi ACL.

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 di campo ACL del documento specifici. Per la leggibilità, questo scenario usa alias ACL, ad esempio "user1", "group1", anziché GUID.

Vedere anche

• 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