Tutorial: Indexar metadados de permissão do ADLS Gen2 e consultar com resultados filtrados por permissão (prévia)

Este tutorial demonstra a ingestão de metadados de permissão do Azure Data Lake Storage (ADLS) Gen2 (versão prévia), na qual um indexador Pesquisa de IA do Azure  adiciona ACLs (listas de controle de acesso) e o escopo do RBAC (controle de acesso baseado em função) a um índice de pesquisa.

Ele também mostra como estruturar uma consulta que respeita as permissões de acesso do usuário. Um resultado de consulta bem-sucedido confirma a transferência de permissão que ocorreu 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á a:

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

Pré-requisitos

• Uma conta 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 tenants 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.

• Pesquisa de IA do Azure , qualquer região. A camada básica ou superior é necessária para o suporte à identidade gerenciada.

• Visual Studio Code com a extensão do cliente REST.

Preparar 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 a Azure por meio de uma conexão de Internet pública.

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

Definir permissões no ADLS Gen2

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

1. Conceda à identidade do serviço de pesquisa acesso de leitura ao contêiner. O indexador se conecta ao Armazenamento do Azure com a identidade do serviço de pesquisa. 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 Azure para gerenciar ACLs. No Navegador de Armazenamento, selecione o diretório oregon e, em seguida, selecione Gerenciar ACL no menu de contexto.

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

5. Remover entidades existentes para grupos proprietários, usuários proprietários e outros. Essas entidades não são compatíveis com a indexação de ACL durante a versão preliminar.

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

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

Certifique-se de usar a API REST mais recente em visualização ou uma versão prévia de um pacote SDK do Azure que forneça 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ões consiste principalmente em definir metadados de permissão fieldMappings a partir de permissões.

{
  "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, confira ACL em tempo de consulta e imposição de RBAC.

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

Conteúdo relacionado

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