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

Este tutorial demonstra a ingestão de metadados de permissões do Azure Data Lake Storage (ADLS) Gen2 (pré-visualização), na qual um indexador do Pesquisa de IA do Azure adiciona o âmbito de listas de controlo de acesso (ACLs) e de controlo de acesso baseado em funções (RBAC) a um índice de pesquisa.

Também mostra como estruturar uma consulta que respeite as permissões de acesso dos utilizadores. Um resultado bem-sucedido da consulta confirma a transferência de permissão que ocorreu durante a indexação.

Para mais informações sobre indexação de ACLs, veja Usar um indexador ADLS Gen2 para ingerir metadados de permissões.

Neste tutorial, aprende como:

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

Pré-requisitos

• Uma conta no Azure com uma subscrição ativa. Cria uma conta gratuitamente.

• Autenticação e autorização do Microsoft Entra ID. Os serviços e as aplicações devem estar no mesmo inquilino. Atribuições de funções são usadas para cada ligação autenticada. Utilizadores e grupos devem estar no mesmo locatário. Deves ter utilizadores e grupos para trabalhar. Criar inquilinos e princípios de segurança está fora do âmbito deste tutorial.

• ADLS Gen2 com um namespace hierárquico.

• Ficheiros numa estrutura hierárquica de pastas. Este tutorial assume a demonstração ADLS Gen2 da estrutura de pastas para ficheiros /Oregon/Portland/Data.txt. Este tutorial guia-o através da atribuição de ACL em pastas e ficheiros para que possa completar o exercício com sucesso.

• Pesquisa de IA do Azure, qualquer região. É necessário um nível básico ou superior para suporte de identidade gerida.

• Visual Studio Code com a extensão REST Client.

Preparar dados de amostra

Carregue a amostra de dados dos parques estaduais para um contentor na ADLS Gen2. O nome do contentor deve ser "parques" e deve ter duas pastas: "Oregon" e "Washington".

Verificar configuração do serviço de pesquisa

O seu serviço de pesquisa deve estar configurado para autenticação e autorização do Microsoft Entra ID. Revise esta lista de verificação para garantir que está preparado.

• Permitir o acesso baseado em funções

• Configure uma identidade gerida atribuída automaticamente pelo sistema.

Obtenha um token de identidade pessoal para testes locais

Este tutorial assume um cliente REST num sistema local, a ligar-se ao Azure através de uma ligação pública à internet.

Siga estes passos para adquirir um token de identidade pessoal e configurar Visual Studio Code para ligações locais aos seus recursos de Azure.

Definir permissões no ADLS Gen2

Como boa prática, utilize Group conjuntos em vez de atribuir diretamente os User conjuntos.

1. Conceda ao serviço de pesquisa acesso de leitura ao contentor. O indexador liga-se ao Armazenamento do Azure sob a identidade do serviço de pesquisa. O serviço de pesquisa deve ter permissões de Storage Blob Data Reader para recuperar dados.

2. Conceda permissões por grupo ou utilizador na hierarquia de ficheiros. Na hierarquia de ficheiros, identifique todos os conjuntos Group e User que são atribuídos a contentores, diretórios e ficheiros.

3. Pode usar o portal do Azure para gerir ACLs. No Storage Browser, selecione o diretório Oregon e depois selecione Gerir ACL no menu contextual.

4. Adicionar novos princípios de segurança para utilizadores e grupos.

5. Remover princípios existentes para possuir grupos, possuir utilizadores e outros. Estes princípios não são suportados para indexação ACL durante a pré-visualização.

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

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

Certifique-se de usar a API REST mais recente ou um pacote de SDK do Azure de pré-visualização que forneça funcionalidades equivalentes. As propriedades do filtro de permissões estão disponíveis apenas nas APIs de pré-visualização.

Para efeitos de demonstração, o campo de permissões está retrievable ativado para que possas verificar os valores do índice. Num ambiente de produção, deve desativar retrievable para evitar divulgar informações sensíveis.

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

Modificar a configuração da fonte de dados para especificar a ingestão de permissões do indexador e os tipos de metadados de permissões que pretende indexar.

Uma fonte de dados precisa de indexerPermissionOptions.

Neste tutorial, use uma identidade gerida atribuída pelo sistema para a ligaçã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 a ingestão de permissões baseia-se principalmente na definição de fieldMappings a partir de .

{
  "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 execução imediata, o conteúdo do ficheiro, juntamente com a informação dos metadados de permissões, é indexado no índice.

Execute uma consulta para verificar os resultados

Agora que os documentos estão carregados, pode realizar consultas sobre eles usando Documents - Search Post (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 do pedido. Para mais informações, consulte Aplicação de ACL e RBAC em tempo de consulta.

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