Utilize um indexador de blobs ou uma origem de conhecimento para ingerir os metadados dos âmbitos de RBAC (pré-visualização)

Nota

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Importante

Funcionalidades, capacidades ou propriedades assinaladas (pré-visualização) não são abrangidas por um acordo de nível de serviço, não são recomendadas para cargas de trabalho em produção e podem mudar ou ser limitadas antes de se tornarem geralmente disponíveis. Os termos de pré-visualização do Pesquisa de IA do Azure aplicam-se a todas as funcionalidades de pré-visualização, sejam independentes ou parte de uma funcionalidade geralmente disponível.

Armazenamento do Azure permite o acesso baseado em funções em contentores em armazenamento de blobs, onde funções como Storage Blob Data Reader ou Storage Blob Data Contributor determinam se alguém tem acesso ao conteúdo. O Pesquisa de IA do Azure suporta a ingestão de permissões de utilizador (pré-visualização) juntamente com a ingestão de documentos, para que possa usar essas permissões para controlar o acesso aos resultados de pesquisa. Se um utilizador não tiver permissões sobre um diretório ou ficheiro específico no Armazenamento do Azure, esse utilizador não tem acesso aos documentos correspondentes nos resultados Pesquisa de IA do Azure, mesmo que tenha pessoalmente uma atribuição Search Index Data Readerno índice.

  • 2025-05-01-preview e posteriores, os metadados dos escopos RBAC podem ser ingeridos usando o Blob indexer.
  • 2025-11-01-preview e versões posteriores fornece suporte equivalente para fontes de conhecimento de Blob no Armazenamento do Azure.

O âmbito do RBAC é definido ao nível do contêiner e propaga-se para todos os blobs (documentos) através da herança de permissões. O âmbito do RBAC é capturado durante a indexação como metadados de permissões. Pode usar as APIs push para carregar e indexar manualmente conteúdos e metadados de permissões (veja Permissões de Indexação usando a API REST push), ou pode usar um indexador ou fonte de conhecimento para automatizar a ingestão de dados. Este artigo foca-se na automação da indexação.

No momento da consulta, a identidade do chamador é incluída no cabeçalho do pedido através do x-ms-query-source-authorization parâmetro. A identidade deve corresponder aos metadados de permissão nos documentos para que o utilizador possa ver os resultados da pesquisa.

Este artigo foca-se nas abordagens de automação da indexação, baseadas nesta base:

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 locatários, desde que todos sejam Microsoft Entra ID. Atribuições de funções são usadas para cada ligação autenticada.

  • Pesquisa de IA do Azure, qualquer região, mas deve ter um nível faturável (básico ou superior) para suporte de identidade gerida. O serviço de pesquisa deve estar configurado para acesso baseado em funções e deve ter uma identidade gerida (seja do sistema ou do utilizador).

  • Armazenamento do Azure, desempenho padrão (v2 de uso geral), em camadas de acesso quente, fresco e frio, com contentores ou blobs protegidos por RBAC.

  • Deves compreender como funcionam os indexadores e as fontes de conhecimento 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 passos para criar o índice. Para mais informações sobre índices concebidos para filtros de permissões, veja Criar um índice com campos de filtro de permissões.

Limitações

Configurar Armazenamento de Blobs

Verifica se o teu contentor de blob usa acesso baseado em funções.

  1. Inicia sessão no portal do Azure e encontra a tua conta de armazenamento.

  2. Expande os contentores e seleciona o contentor que tem os blobs que queres indexar.

  3. Selecione Controlo de Acesso (IAM) para verificar as atribuições de funções. Utilizadores e grupos com Leitor de Dados de Blob de Armazenamento ou Contribuidor de Dados de Blob de Armazenamento podem aceder a documentos de pesquisa no índice após a indexação do contentor.

Autorização

Para a execução do indexador, a identidade do seu serviço de pesquisa deve ter permissão Leitor de Dados de Blob de Armazenamento. Para mais informações, veja Connect to Armazenamento do Azure usando uma identidade gerida.

Lembre-se 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, permissão Search Index Data Contributor para realizar a importação de dados, e Search Index Data Reader para consultar um índice, veja Connect to Pesquisa de IA do Azure using roles.

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). O âmbito do RBAC é detetado e automaticamente incluído 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 está definido como falso, o que significa que a fonte de dados é 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}}"
            }
        }
    }
}

Referência:Criar ou Atualizar Fonte de Conhecimento (API REST)

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 dos blobs.

Criar a fonte de dados

  • O tipo de fonte de dados deve ser azureblob.

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

  • A fonte de dados deve ter indexerPermissionOptions com rbacScope.

Exemplo JSON com identidade gerida 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 gerida pelo utilizador na cadeia de ligaçã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õ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 recomendados de esquema para o Âmbito RBAC:

  • 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-la como verdadeira durante o desenvolvimento para verificar se as permissões estão presentes, mas lembra-te de voltar a defini-la como falsa antes de implementar num 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 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 no Armazenamento de Blobs do Azure podem precisar de mapeamentos de campo se variar o nome do campo:

  • 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_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Execute o indexador

Depois de configurarem o seu indexador, fonte de dados e índice, execute o indexador para pôr o processo em movimento. Se houver um problema de configuração ou permissões, esses problemas surgem nesta etapa.

Por defeito, um indexador corre assim que o publica num serviço de pesquisa, mas se a configuração do indexador estiver disabled definida como verdadeira, o indexador é publicado num estado desativado para que possas executar manualmente o indexador.

Recomendamos executar o indexador a partir do portal Azure para que possa monitorizar o estado e as mensagens.

Assumindo que não há erros, o índice está agora preenchido e pode avançar com as consultas e os testes.

Rastreio de eliminação

Para gerir eficazmente a eliminação de blobs, certifique-se de que ativou o rastreamento de eliminação antes do indexador ser executado pela primeira vez. Esta funcionalidade permite ao sistema detetar blobs eliminados da sua fonte e eliminar o conteúdo correspondente do índice.

Ver também

  • Última atualização a