Use um indexador ADLS Gen2 para ingerir metadados de permissões e filtrar os resultados da pesquisa com base nos direitos de acesso dos utilizadores (pré-visualização)

Azure Data Lake Storage (ADLS) Gen2 suporta acesso por utilizador a diretórios e ficheiros através de listas controlo de acesso (ACLs) e controlo de acesso baseado em funções (Azure RBAC). (Azure ABAC) não é suportado.

O Pesquisa de IA do Azure pode ingerir estes metadados de permissões (pré-visualização) juntamente com o conteúdo do documento, utilizando uma API REST de pré-visualização. Os utilizadores que não têm acesso a um diretório ou ficheiro armazenado não veem os documentos correspondentes nos resultados de pesquisa. Esta é uma das várias estratégias para controlo de acesso ao nível de documento em Pesquisa de IA do Azure.

Este artigo explica como configurar um indexador ADLS Gen2 ou uma fonte de dados do tipo blob ADLS Gen2 para extrair automaticamente metadados de permissões para um índice de pesquisa. Complementa os dados do Índice do ADLS Gen2 e cria uma fonte de conhecimento em blob para o ADLS Gen2 com informação específica para a ingestão de permissões. Para enviar manualmente os metadados de permissões, consulte ACLs de documentos de índice usando a API push.

Diagrama de arquitetura

Pré-requisitos

• Microsoft Entra ID autenticação e autorização. Os serviços e as aplicações devem estar no mesmo inquilino. Os utilizadores podem estar em diferentes tenants, desde que todos os tenants utilizem o Microsoft Entra ID. Atribuições de funções são usadas para cada ligação autenticada.

• Pesquisa de IA do Azure num nível faturável (Básico ou superior) em qualquer região. O serviço de pesquisa deve ter acesso baseado em funções ativado e uma identidade gerida atribuída pelo sistema ou pelo utilizador.

• Blobs ADLS Gen2 num espaço de nomes hierárquico, com permissões de utilizador concedidas através de ACLs ou roles.

• API REST versão 2025-05-01-preview ou posterior para ingestão de permissões do indexador. API REST versão 2025-11-01-preview ou posterior para suporte de origens de conhecimento. Use a API REST de pré-visualização mais recente ou um pacote de SDK de pré-visualização que suporte filtros de permissões.

Limitações

• O portal do Azure não suporta esta funcionalidade.

• Aplicam-se limites ADLS Gen2 para atribuições de funções e entradas ACL .

• As owning usersowning groups , Other, e all () não são suportadas durante a pré-visualização. Use named users e named groups atribuições ao invés.

• As seguintes funcionalidades do indexador não suportam herança de permissões em documentos indexados originários do ADLS Gen2. Se usar alguma destas funcionalidades num conjunto de competências ou indexador, as permissões ao nível do documento não estão incluídas no conteúdo indexado.

  • Funcionalidade de API Web Personalizada

  • Repositório de conhecimento, incluindo o armazenamento de ativos necessário para a disponibilização de imagens (pré-visualização) na recuperação agentiva. Portanto, o fornecimento de imagens não é suportado para fontes de conhecimento que ingerem ACLs ou âmbitos de RBAC.

  • Cache de enriquecimento do indexador

  • Sessões de depuração

Suporte ao modelo de permissões

Esta secção compara as funcionalidades de controlo de acesso ao nível do documento entre o ADLS Gen2 e o Pesquisa de IA do Azure. Explica quais os mecanismos de controlo de acesso do Azure Data Lake Storage (ADLS) Gen2 que a AI Search suporta ou mapeia. Isto ajuda-o a perceber como as permissões são aplicadas ao nível do documento.

No momento da consulta, o Pesquisa de IA do Azure avalia primeiro o RBAC ao nível do contentor e depois verifica as entradas ACL ao nível do documento. O acesso é concedido se algum mecanismo o permitir.

Sobre as permissões hierárquicas da ACL

Indexadores e fontes de conhecimento podem recuperar atribuições ACL do contentor especificado e de todos os diretórios que conduzem a cada ficheiro, seguindo o fluxo de avaliação hierárquica de acesso ADLS Gen2. As listas finais de acesso efetivo para cada ficheiro são calculadas e as diferentes categorias de acesso são indexadas nos campos de índice correspondentes.

Por exemplo, em ADLS Gen2, cenários comuns relacionados com permissões como o caminho do ficheiro /Oregon/Portland/Data.txt.

O indexador ou fonte de conhecimento recolhe ACLs de cada contentor e diretório. Depois determina o acesso efetivo em níveis inferiores e continua até resolver as permissões para cada ficheiro.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Configurar ADLS Gen2

Um indexador ou fonte de conhecimento pode recuperar ACLs numa conta de armazenamento se forem cumpridos os seguintes critérios. Para mais informações sobre atribuições ACL, consulte atribuições ACL Gen2 da ADLS.

Autorização

Para a indexação, a identidade do seu serviço de pesquisa deve ter a permissão de Leitor de Dados de Blob de Armazenamento.

Se estiveres a testar localmente, também deves ter uma atribuição de função de Leitor de Dados de Blob de Armazenamento . Para mais informações, veja Connect to Armazenamento do Azure usando uma identidade gerida.

Permissões de contentores raiz:

1. Atribuir todos os conjuntos Group e User (princípios de segurança) no contentor raiz / com permissões Read e Execute.

2. Garanta que ambos Read e Execute são adicionados como "Permissões Padrão" para que se propaguem automaticamente para ficheiros e diretórios recém-criados.

Propagar permissões para baixo na hierarquia de ficheiros

Embora novos diretórios e ficheiros herdem permissões, os diretórios e ficheiros existentes não herdam automaticamente estas atribuições.

Use a ferramenta ADLS Gen2 para aplicar ACLs recursivamente para propagação de atribuições em conteúdo existente. Esta ferramenta propaga as atribuições de ACL do contentor raiz para todos os diretórios e ficheiros subjacentes.

Remover permissões em excesso

Depois de aplicar ACLs recursivamente, reveja as permissões de cada diretório e ficheiro.

Remova quaisquer conjuntos de Group ou User que não devam ter acesso a diretórios ou ficheiros específicos. Por exemplo, remove User2 na pasta Portland/, e para a pasta Idaho remove Group2 e User2 das suas atribuições, e assim por diante.

Estrutura de atribuições ACL de exemplo

Aqui está um diagrama da estrutura de atribuição ACL para a hierarquia fictícia de diretórios na documentação ADLS Gen2.

Atualizando atribuições de ACL ao longo do tempo

Com o tempo, à medida que novas atribuições de ACL são adicionadas ou modificadas, repita os passos anteriores para garantir a propagação correta e o alinhamento das permissões. Permissões atualizadas no ADLS Gen2 são atualizadas no índice de pesquisa quando se reingesta o conteúdo usando o indexador ou a fonte de conhecimento.

Configurar a Pesquisa de IA do Azure

Lembre-se que o serviço de pesquisa deve ter:

• Acesso baseado em funções ativado
• Identidade gerida está configurada

Autorização

Para a indexação, o cliente que emite a chamada API deve ter permissão do Contribuidor do Serviço de Pesquisa para criar objetos, permissão do Contribuidor de Dados do Índice de Pesquisa para realizar a importação de dados e Leitor de Dados do Índice de Pesquisa para consultar um índice (Search Index Data Reader).

Se estiveres a fazer testes localmente, deves ter as mesmas atribuições de funções. Para mais informações, consulte Ligar-se a Pesquisa de IA do Azure usando funções.

Configurar uma fonte de conhecimento

Se estiver a usar uma fonte de conhecimento, as definições na fonte de conhecimento são usadas para gerar um pipeline completo de indexação (indexador, fonte de dados e índice). As atribuições de ACL são detetadas e automaticamente incluídas no índice gerado. Não há necessidade de modificar nenhum dos objetos gerados se pretender herança de permissões no seu conteúdo indexado.

Pontos-chave sobre a configuração que a fazem funcionar para este cenário:

• isADLSGen2 é definido como verdadeiro, cumprindo o requisito da fonte de dados para este cenário.
• ingestionPermissionOptions especifica IDs de utilizador e de grupo.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Configurar indexação baseada em indexador

Se estiveres a usar um indexador, configura-o, a fonte de dados e o índice para extrair metadados de permissão de blobs ADLS Gen2.

Criar a fonte de dados

Esta secção complementa os dados Index do ADLS Gen2 com informações específicas sobre a ingestão de permissões, juntamente com o conteúdo do documento, num índice Pesquisa de IA do Azure.

• O tipo de fonte de dados deve ser adlsgen2.

• A fonte de dados deve ter indexerPermissionOptions com userIds, groupIds, e/ou rbacScope.

  • Para rbacScope, configure a cadeia de conexão com o formato de identidade gerida.

  • Para strings de ligação que usam uma identidade gerida atribuída pelo utilizador, também deve especificar a propriedade identity.

Exemplo de JSON com identidade gerida por sistema:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Exemplo de esquema JSON com uma identidade gerida pelo utilizador na cadeia de ligação:

{
    "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": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Criar campos de permissões no índice

No Pesquisa de IA do Azure, certifique-se de que o seu índice contém definições de campos para os metadados de permissões. Os metadados de permissão podem ser indexados quando indexerPermissionOptions estiver especificado na definição da fonte de dados.

Atributos de esquema recomendados para ACL (UserIds, GroupIds) e Âmbito do RBAC:

• Campo de identificador de utilizador (ID) com userIds valor de permissionFilter.
• Campo de IDs de Grupo com groupIds valor de permissionFilter.
• Campo de âmbito RBAC com valor de filtro de permissão rbacScope.
• Propriedade permissionFilterOption para permitir filtragem no momento da consulta.
• Use campos de cadeia para metadados de permissão
• Defina o filterable para true em todos os campos.

Repare que retrievable é falso. Podes defini-lo como true durante o desenvolvimento para verificar se as permissões estão presentes, mas lembra-te de voltar a false antes de implementar num ambiente de produção.

Exemplo de esquema JSON:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Configurar o indexador

Os mapeamentos de campos dentro de um indexador definem o caminho dos dados para campos num índice. Os campos de alvo e destino que variam por nome ou tipo de dados requerem um mapeamento explícito entre os campos. Os seguintes campos de metadados na ADLS Gen2 podem necessitar de mapeamentos de campo se variar o nome do campo:

• metadata_user_ids (Collection(Edm.String)) - a lista de IDs de utilizador ACL.
• metadata_group_ids (Collection(Edm.String)) - a lista de IDs de grupos ACL.
• metadata_rbac_scope (Edm.String) - o âmbito RBAC do container.

Especifique fieldMappings no indexador para encaminhar os metadados de permissão para os campos-alvo durante a indexação.

Exemplo de esquema JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Recomendações e melhores práticas

• Planeie cuidadosamente a estrutura de pastas do ADLS Gen2 antes de criar qualquer pasta.

• Organizar as identidades em grupos e usar grupos sempre que possível, em vez de conceder acesso direto a utilizadores individuais. Adicionar continuamente utilizadores individuais em vez de aplicar grupos aumenta o número de entradas de controlo de acesso que devem ser acompanhadas e avaliadas. Não seguir esta melhor prática pode levar a atualizações mais frequentes de metadados de segurança no índice à medida que estes metadados mudam, causando atrasos e ineficiências crescentes no processo de atualização.

Sincronizar permissões entre conteúdos indexados e de origem

Ativar o enriquecimento ACL ou RBAC num indexador funciona automaticamente apenas em duas situações:

• A primeira execução completa do indexador / rastreamento de dados: todos os metadados de permissões existentes naquele momento para cada documento são capturados.

• Documentos novos adicionados após o suporte ACL/RBAC ter sido ativado: as informações ACL/RBAC são processadas juntamente com o seu conteúdo.

Se alterar permissões de documentos, como adicionar um utilizador a uma ACL ou atualizar uma atribuição de funções, a alteração não aparece no índice de pesquisa a menos que peça ao indexador para rastrear novamente os metadados de permissões do documento.

Escolha um dos seguintes mecanismos, dependendo de quantos itens foram alterados:

Exemplo da API Resetdocs (pré-visualização):

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Exemplo de API de Resincronização (pré-visualização):

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Rastreio de eliminação

Para gerir eficazmente a eliminação de blobs, certifique-se de que o rastreamento de eliminação está ativado antes de o seu indexador ser executado pela primeira vez. Esta funcionalidade permite ao sistema detetar blobs eliminados na sua fonte e removê-los do índice.

Conteúdo relacionado

• Liga-te a Pesquisa de IA do Azure usando roles
• Aplicação da ACL e RBAC no tempo de consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API