Compartilhar via

Usar um indexador de Blob para ingerir metadados de escopos RBAC

Note

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

O Armazenamento do Azure permite acesso baseado em função em contêineres no armazenamento de blobs, em que funções como Leitor de Dados de Blob de Armazenamento ou Colaborador de Dados de Blob de Armazenamento determinam se alguém tem acesso ao conteúdo. A partir de 2025-05-01-preview, você poderá incluir o escopo RBAC juntamente com a ingestão de documentos no Azure AI Search e usar essas permissões para controlar o acesso aos resultados da pesquisa. Se você tiver direitos ao conteúdo, poderá vê-lo nos resultados da pesquisa. Se você não tiver direitos (ou mais especificamente, uma atribuição de função no contêiner de blobs), não poderá ver esses resultados, mesmo que tenha pessoalmente uma atribuição de Leitor de Dados do Índice de Pesquisano índice.

O escopo RBAC é definido no nível do contêiner e flui para todos os blobs (documentos) por meio da herança de permissão. O escopo do RBAC é capturado durante a indexação como metadados de permissão. Você pode usar as APIs de push para carregar e indexar manualmente o conteúdo e os metadados de permissão (confira Permissões de Indexação usando a API REST de push) ou usar um indexador para automatizar a ingestão de dados. Este artigo se concentra na abordagem do indexador.

No momento da consulta, a identidade do chamador é incluída no cabeçalho da solicitação por meio do x-ms-query-source-authorization parâmetro. A identidade deve corresponder aos metadados de permissão em documentos se o usuário quiser ver os resultados da pesquisa.

A abordagem do indexador baseia-se nessa base:

Prerequisites

  • Autenticação e autorização do Microsoft Entra ID. Serviços e aplicativos devem estar no mesmo locatário. Os usuários podem estar em locatários diferentes, desde que todos os locatários sejam do Microsoft Entra ID. As atribuições de função são usadas para cada conexão autenticada.

  • Pesquisa de IA do Azure, qualquer região, mas é necessário ter uma camada faturável (básica ou superior) para dar suporte à identidade gerenciada. O serviço de pesquisa deve ser configurado para acesso baseado em função e deve ter uma identidade gerenciada (sistema ou usuário).

  • Armazenamento do Microsoft Azure, desempenho Standard (propósito geral v2), nos níveis de acesso frequente, esporádico e frio, com contêineres ou blobs protegidos por RBAC.

  • Você deve entender como os indexadores funcionam e como criar um índice. Este artigo explica as definições de configuração para a fonte de dados e o indexador, mas não fornece etapas para criar o índice. Para obter mais informações sobre índices projetados para filtros de permissão, confira Criar um índice com campos de filtro de permissão.

  • No momento, essa funcionalidade não tem suporte no portal do Azure, incluindo filtros de permissão criados por meio dos assistentes de Importação. Use uma abordagem programática para criar ou modificar objetos existentes para acesso no nível do documento.

Configurar armazenamento de blobs

Verifique se o contêiner de blob usa acesso baseado em função.

  1. Entre no portal do Azure e localize sua conta de armazenamento.

  2. Expanda contêineres e selecione o contêiner que tem os blobs que você deseja indexar.

  3. Selecione Controle de Acesso (IAM) para verificar as atribuições de função. Usuários e grupos com Leitor de Dados de Blob de Armazenamento ou Colaborador de Dados de Blob de Armazenamento poderão pesquisar documentos no índice depois que o contêiner for indexado.

Authorization

Para a execução do indexador, a identidade do serviço de pesquisa deve ter permissão de Leitor de Dados de Armazenamento de Blobs. Para obter mais informações, consulte Conectar-se ao Armazenamento do Azure usando uma identidade gerenciada.

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

Authorization

Para a execução do indexador, o cliente que emite a chamada à API deve ter permissão de Colaborador do Serviço de Pesquisa para criar objetos, permissão de Colaborador de Dados de Índice de Pesquisa para executar a importação de dados e permissão de Leitor de Dados de Índice de Pesquisa para consultar um índice; consulte Conectar-se ao Azure AI Search usando funções.

Configurar a indexação

No Azure AI Search, configure um indexador, uma fonte de dados e um índice para extrair metadados de permissão de blobs.

Criar a fonte de dados

  • O tipo de fonte de dados deve ser azureblob.

  • O modo de análise da fonte de dados deve ser o padrão.

  • A fonte de dados deve ter indexerPermissionOptions com rbacScope.

Exemplo de JSON com identidade gerenciada do sistema e indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

Exemplo de esquema JSON com uma identidade gerenciada pelo usuário na cadeia de conexão:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "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ão no índice

No Azure AI Search, verifique se o índice contém definições de campo para os metadados de permissão. Os metadados de permissão podem ser indexados quando indexerPermissionOptions é especificado na definição da fonte de dados.

Atributos de esquema recomendados - Escopo RBAC:

  • Campo de escopo RBAC com valor permissionFilter rbacScope.
  • Propriedade permissionFilterOption para habilitar a filtragem no momento da consulta.
  • Usar campos de string para metadados de permissão
  • Definido filterable como true em todos os campos.

Observe que retrievable é falso. Você pode defini-lo como verdadeiro durante o desenvolvimento para verificar se as permissões estão presentes, mas lembre-se de voltar a falso antes de implantar em um ambiente de produção para que as identidades de entidades de segurança não fiquem visíveis nos resultados.

Exemplo de esquema JSON:

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Configurar o indexador

Os mapeamentos de campo em um indexador determinam o caminho dos dados para os campos em um índice. Campos de alvo e destino que variam por nome ou tipo de dados exigem um mapeamento de campo explícito. Os seguintes campos de metadados no Armazenamento de Blobs do Azure poderão precisar de mapeamentos de campo se você variar o nome do campo:

  • metadata_rbac_scope (Edm.String) – o escopo RBAC do contêiner.

Especifique fieldMappings no indexador para rotear os metadados de permissão para os campos de destino durante a indexação.

Exemplo de esquema JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Executar o indexador

Depois que o indexador, a fonte de dados e o índice estiverem configurados, execute o indexador para iniciar o processo. Se houver um problema de configuração ou permissões, esses problemas aparecerão nesta etapa.

Por padrão, um indexador é executado assim que você o posta em um serviço de pesquisa, mas se a configuração do indexador incluir disabled definido como verdadeiro, o indexador será postado em um estado desabilitado para que você possa executá-lo manualmente.

Recomendamos executar o indexador no portal do Azure para que você possa monitorar o status e as mensagens.

Se não houver erros, o índice agora está populado e você pode prosseguir com consultas e testes.

Acompanhamento de exclusão

Para gerenciar efetivamente a exclusão de blobs, verifique se o acompanhamento de exclusão está habilitado antes que o indexador seja executado pela primeira vez. Esse recurso permite que o sistema detecte blobs excluídos da sua origem e exclua o conteúdo correspondente do índice.

Consulte também

  • Last updated on