Usar um indexador de blobs ou uma fonte de conhecimento para ingerir metadados dos escopos de RBAC (versão prévia)

Nota

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

Armazenamento do Azure permite o acesso baseado em função em contêineres no armazenamento de blobs, em que funções como Storage Blob Data Reader ou Storage Blob Data Contributor determinam se alguém tem acesso ao conteúdo. Pesquisa de IA do Azure  dá suporte à ingestão de permissões de usuário (versão prévia) juntamente com a ingestão de documentos para que você possa usar essas permissões para controlar o acesso aos resultados da pesquisa. Se um usuário não tiver permissões em um diretório ou arquivo específico no Armazenamento do Azure, esse usuário não terá acesso aos documentos correspondentes nos resultados do Pesquisa de IA do Azure , mesmo que você tenha pessoalmente uma atribuição Search Index Data Readerno índice.

  • A partir de 2025-05-01-preview, e em versões posteriores, os metadados de escopos RBAC podem ser ingeridos usando o indexador de Blob.
  • A versão prévia 2025-11-01 e posteriores fornecem suporte equivalente para fontes de conhecimento de blobs no Armazenamento do Azure.

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 push para carregar e indexar metadados de conteúdo e permissão manualmente (consulte Permissões de indexação usando a API REST por push) ou pode usar um indexador ou fonte de conhecimento para automatizar a ingestão de dados. Este artigo se concentra na automação de indexação.

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.

Este artigo se concentra nas abordagens de automação de indexação, criadas nesta base:

Pré-requisitos

  • 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 você deve ter uma camada faturável (básica e superior) para 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 e fontes de conhecimento funcionam e como criar um índice. Este artigo explica as configurações da fonte de dados e do indexador, mas não fornece etapas para criar o índice. Para obter mais informações sobre índices projetados para filtros de permissão, consulte Criar um índice com campos de filtro de permissão.

Limitações

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 terão acesso a documentos de pesquisa no índice depois que o contêiner for indexado.

Autorização

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 para Armazenamento do Azure usando uma identidade gerenciada.

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

Autorização

Para a execução do indexador, o cliente que emite a chamada à API deve ter permissão Search Service Contributor para criar objetos, Search Index Data Contributor permissão para executar a importação de dados e Search Index Data Reader para consultar um índice consulte Conectar para Pesquisa de IA do Azure  usando funções.

Configurar uma fonte de conhecimento

Se você estiver usando uma fonte de conhecimento, as definições na fonte de conhecimento serão usadas para gerar um pipeline de indexação completo (indexador, fonte de dados e índice). O escopo RBAC é detectado e incluído automaticamente no índice gerado. Não é necessário modificar nenhum dos objetos gerados se você quiser que as permissões sejam herdadas no conteúdo indexado.

Principais pontos sobre a configuração que o fazem funcionar para este cenário:

  • isADLSGen2 é definido como false, o que significa que a fonte de dados é no Armazenamento de Blobs do Azure.
  • ingestionPermissionOptions especifica rbacScope.
# 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": false,
        "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": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Reference:Create or Update Knowledge Source (API REST)

Configurar indexação baseada em indexador

Se você estiver usando um indexador, além de configurá-lo, configure também a fonte de dados e o índice para obter metadados de permissão dos 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 pelo 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 no 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

Em Pesquisa de IA do Azure , 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 para o escopo RBAC:

  • Campo de escopo RBAC com valor de 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 configurá-lo para verdadeiro durante o desenvolvimento para verificar se as permissões estão presentes, mas lembre-se de defini-lo novamente como falso antes de implantar no ambiente de produção para que as identidades principais 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 definem o caminho dos dados para os campos em um índice. Campos de origem e destino que variam por nome ou tipo de dados exigem um mapeamento de campo explícito. Os seguintes campos de metadados em 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 forem configurados, execute o indexador para definir o processo em movimento. Se houver um problema com a configuração ou as 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 true, o indexador será postado em um estado desabilitado para que você possa executar o indexador manualmente.

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

Supondo que não haja erros, o índice agora é preenchido e você pode avançar com consultas e testes.

Acompanhamento de exclusão

Para gerenciar efetivamente a exclusão de blobs, certifique-se de ter habilitado o controle de exclusão antes do indexador ser executado pela primeira vez. Esse recurso permite que o sistema detecte blobs excluídos de sua origem e exclua o conteúdo correspondente do índice.

Consulte também

  • Last updated on