Tutorial: Indexar metadados de permissão do ADLS Gen2 e consultar com resultados filtrados por permissão

Este tutorial demonstra como indexar as ACLs (Listas de Controle de Acesso ) do Azure Data Lake Storage (ADLS) Gen2 e o escopo do RBAC (controle de acesso baseado em função) em um índice de pesquisa usando um indexador.

Ele também mostra como estruturar uma consulta que respeita as permissões de acesso do usuário. Um resultado bem-sucedido de consulta confirma a transferência de permissão realizada durante a indexação.

Para obter mais informações sobre como indexar ACLs, consulte Usar um indexador ADLS Gen2 para ingerir metadados de permissão.

Neste tutorial, você aprenderá como:

Use um cliente REST para concluir este tutorial e a API REST da última versão prévia. Atualmente, não há suporte para a indexação de ACL no portal do Azure.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Autenticação e autorização do Microsoft Entra ID. Serviços e aplicativos devem estar no mesmo locatário. As atribuições de função são usadas para cada conexão autenticada. Usuários e grupos devem estar no mesmo locatário. Você deve ter usuários e grupos com os quais trabalhar. A criação de locatários e entidades de segurança está fora do escopo deste tutorial.

• ADLS Gen2 com um namespace hierárquico.

• Arquivos em uma estrutura de pasta hierárquica. Este tutorial pressupõe a demonstração do ADLS Gen2 da estrutura de pastas para arquivo /Oregon/Portland/Data.txt. Este tutorial orienta você pela atribuição de ACL em pastas e arquivos para que você possa concluir o exercício com êxito.

• Azure AI Search, qualquer região. A camada básica ou superior é necessária para o suporte à identidade gerenciada.

• Visual Studio Code com um cliente REST ou um cliente Python e pacote Jupyter.

Preparar os dados de exemplo

Carregue os dados de exemplo dos parques estaduais em um contêiner no ADLS Gen2. O nome do contêiner deve ser "parks" e deve ter duas pastas: "Oregon" e "Washington".

Verificar a configuração do serviço de pesquisa

O serviço de pesquisa deve ser configurado para autenticação e autorização do Microsoft Entra ID. Examine esta lista de verificação para verificar se você está preparado.

• Habilitar o acesso baseado em função

• Configure uma identidade gerenciada atribuída pelo sistema.

Obter um token de identidade pessoal para testes locais

Este tutorial pressupõe um cliente REST em um sistema local, conectando-se ao Azure por meio de uma conexão de Internet pública.

Siga estas etapas para adquirir um token de identidade pessoal e configurar o Visual Studio Code para conexões locais com seus recursos do Azure.

Definir permissões no ADLS Gen2

Como melhor prática, use Group conjuntos em vez de atribuir User conjuntos diretamente.

1. Conceda à identidade do serviço de pesquisa acesso de leitura ao contêiner. O indexador se conecta ao Armazenamento do Azure sob a identidade do serviço de busca. O serviço de pesquisa deve ter permissões de Leitor de Dados de Blob de Armazenamento para recuperar dados.

2. Conceda permissões por grupo ou de usuário na hierarquia de arquivos. Na hierarquia de arquivos, identifique todos os conjuntos Group e User que estão atribuídos a contêineres, diretórios e arquivos.

3. Você pode usar o portal do Azure para gerenciar ACLs. No Navegador de Armazenamento, selecione o diretório oregon e, em seguida, selecione Gerenciar ACL no menu de contexto.

4. Adicione novas entidades de segurança para usuários e grupos.

5. Remova as entidades de segurança existentes para grupos proprietários, usuários proprietários e outros. Essas entidades de segurança não têm suporte para indexação de ACL durante a visualização pública.

Criar um índice de pesquisa para metadados de permissão

Crie um índice que contenha campos para metadados de conteúdo e permissão.

Lembre-se de usar a API REST de última versão prévia ou um SDK do Azure de pré-lançamento que forneça uma funcionalidade equivalente. As propriedades de filtro de permissão só estão disponíveis nas APIs de visualização.

Para fins de demonstração, o campo retrievable de permissão foi habilitado para que você possa verificar os valores do índice. Em um ambiente de produção, você deve desabilitar retrievable para evitar o vazamento de informações confidenciais.

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

Criar uma fonte de dados

Modifique a configuração da fonte de dados para especificar a ingestão de permissão do indexador e os tipos de metadados de permissão que você deseja indexar.

Uma fonte de dados precisa indexerPermissionOptions.

Neste tutorial, use uma identidade gerenciada atribuída pelo sistema para a conexão autenticada.

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

Criar e executar o indexador

A configuração do indexador para ingestão de permissão é principalmente sobre definir fieldMappings a partir de metadados de permissão.

{
  "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" }
    ]
  }
}

Após a criação do indexador e a execução imediata, o conteúdo do arquivo, juntamente com as informações de metadados de permissão, são indexados no índice.

Executar uma consulta para verificar os resultados

Agora que os documentos são carregados, você pode emitir consultas com eles usando Documentos – Postagem de Pesquisa (REST).

O URI é estendido para incluir uma entrada de consulta, que é especificada usando o /docs/search operador. O token de consulta é passado no cabeçalho da solicitação. Para obter mais informações, veja aplicação de ACL e RBAC em tempo de consulta.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-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"
}

Conteúdo relacionado

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