Esercitazione: Indicizzare i metadati delle autorizzazioni da ADLS Gen2 ed eseguire query con risultati filtrati con autorizzazioni (anteprima)

Questa esercitazione illustra Azure Data Lake Storage (ADLS) Gen2 per l'inserimento dei metadati delle autorizzazioni (anteprima), in cui un indicizzatore Azure AI Search aggiunge elenchi di controllo di accesso (ACL) e l'ambito del controllo degli accessi in base al ruolo a un indice di ricerca.

Viene inoltre illustrato come strutturare una query che rispetta le autorizzazioni di accesso utente. Un esito positivo della query conferma il trasferimento delle autorizzazioni che si è verificato durante l'indicizzazione.

Per altre informazioni sull'indicizzazione degli elenchi di controllo di accesso, vedere Usare un indicizzatore ADLS Gen2 per inserire i metadati delle autorizzazioni.

In questa esercitazione si apprenderà come:

Usare un client REST per completare questa esercitazione e l'API REST di anteprima più recente. Attualmente non è disponibile alcun supporto per l'indicizzazione ACL nel portale di Azure.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.

• L'autenticazione e l'autorizzazione di Microsoft Entra ID. I servizi e le app devono trovarsi nello stesso tenant. Le assegnazioni di ruolo vengono usate per ogni connessione autenticata. Gli utenti e i gruppi devono trovarsi nello stesso tenant. È necessario disporre di utenti e gruppi con cui lavorare. La creazione di tenant e di entità di sicurezza non è oggetto di questa esercitazione.

• ADLS Gen2 con uno spazio dei nomi gerarchico.

• File in una struttura di cartelle gerarchica. Questa esercitazione presuppone la demo di ADLS Gen2 della struttura di cartelle per il file /Oregon/Portland/Data.txt. Questa esercitazione illustra l'assegnazione ACL in cartelle e file in modo da poter completare correttamente l'esercizio.

• Azure AI Search, qualsiasi regione. Il livello Basic o superiore è necessario per il supporto delle identità gestite.

• Visual Studio Code con l'estensione client REST.

Preparare i dati di esempio

Caricare i dati di esempio dei parchi statali in un contenitore in ADLS Gen2. Il nome del contenitore deve essere "parchi" e deve avere due cartelle: "Oregon" e "Washington".

Controllare la configurazione del servizio di ricerca

Il servizio di ricerca deve essere configurato per l'autenticazione e l'autorizzazione tramite Microsoft Entra ID. Esaminare questo elenco di controllo per assicurarsi di essere preparati.

• Abilitare l'accesso in base al ruolo

• Configurare un'identità gestita assegnata dal sistema.

Ottenere un token di identità personale per i test locali

Questa esercitazione presuppone che un client REST in un sistema locale si connetta a Azure tramite una connessione Internet pubblica.

Seguire questi passaggi per acquisire un token di identità personale e configurare Visual Studio Code per le connessioni locali alle risorse Azure.

Impostare le autorizzazioni in ADLS Gen2

Come procedura consigliata, usare Group i set anziché assegnare direttamente i set User.

1. Concedere all'identità del servizio di ricerca l'accesso in lettura al contenitore. L'indicizzatore si connette all'Archiviazione di Azure con l'identità del servizio di ricerca. Per recuperare i dati, il servizio di ricerca deve disporre delle autorizzazioni di lettura dei dati dei BLOB di archiviazione .

2. Concedere le autorizzazioni per gruppo o utente nella gerarchia di file. Nella gerarchia dei file identificare tutti i Group set e User assegnati a contenitori, directory e file.

3. È possibile usare il portale di Azure per gestire gli elenchi di controllo di accesso. Nel Browser di archiviazione selezionare la directory Oregon e quindi selezionare Gestisci ACL dal menu contestuale.

4. Aggiungere nuovi entità di sicurezza per utenti e gruppi.

5. Rimuovere le entità esistenti per i gruppi di proprietà, gli utenti proprietari e altri. Queste entità non sono supportate per l'indicizzazione ACL durante l'anteprima.

Creare un indice di ricerca per i metadati delle autorizzazioni

Creare un indice contenente i campi per i metadati del contenuto e delle autorizzazioni.

Assicurarsi di usare l'API REST latest preview o un pacchetto di anteprima Azure SDK che fornisce funzionalità equivalenti. Le proprietà del filtro delle autorizzazioni sono disponibili solo nelle API di anteprima.

Ai fini della demo, il campo delle autorizzazioni è retrievable abilitato in modo da poter controllare i valori dell'indice. In un ambiente di produzione è consigliabile disabilitare retrievable per evitare perdite di informazioni riservate.

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

Creare un'origine dati

Modificare la configurazione dell'origine dati per specificare l'inserimento delle autorizzazioni dell'indicizzatore e i tipi di metadati di autorizzazione da indicizzare.

Un'origine dati richiede indexerPermissionOptions.

In questa esercitazione usare un'identità gestita assegnata dal sistema per la connessione autenticata.

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "parks",
    "query": null
    }
}

Creare ed eseguire l'indicizzatore

La configurazione dell'indicizzatore per l'inserimento delle autorizzazioni riguarda principalmente la definizione fieldMappings dai metadati delle autorizzazioni.

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

Dopo la creazione e l'esecuzione immediata dell'indicizzatore, il contenuto del file insieme alle informazioni sui metadati di autorizzazione viene indicizzato nell'indice.

Eseguire una query per controllare i risultati

Ora che i documenti vengono caricati, è possibile eseguire query su di essi usando Documenti - Post di ricerca (REST).

L'URI viene esteso per includere un input di query, specificato tramite l'operatore /docs/search . Il token di query viene passato nell'intestazione della richiesta. Per ulteriori informazioni, consultare l'applicazione di ACL e RBAC durante la fase di interrogazione.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Contenuto correlato

• https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl