Ligue-se ao Pesquisa de IA do Azure usando roles

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.

Pesquisa de IA do Azure suporta controlo de acesso baseado em funções através do Microsoft Entra ID. O acesso baseado em funções é opcional, mas recomendado. A alternativa é a autenticação baseada em chave, que é o padrão.

Se atribuir múltiplos papéis a um principal de segurança, as permissões são combinadas. As atribuições de funções aplicam-se a todas as ferramentas e bibliotecas de clientes.

Este artigo explica como atribuir funções incorporadas para administração de serviços, desenvolvimento e acesso de consulta e recuperação apenas de leitura. Também fornece passos para criar papéis personalizados e testar atribuições de funções.

Sugestão

Pré-requisitos

Funções incorporadas

As funções são um conjunto de permissões que afetam o plano de controlo ou o plano de dados.

  • Plano de controlo: Operações para provisionamento de serviços, configuração e administração. As operações do plano de controlo incluem criar ou eliminar serviços de pesquisa, listar chaves API e gerir definições de rede e autenticação. Disponível através das APIs REST Azure Resource Manager, APIs REST de Gestão de Pesquisa e bibliotecas equivalentes do cliente SDK do Azure.

  • Plano de dados: Operações contra o endpoint do serviço de pesquisa. As operações no plano de dados dividem-se em duas categorias: gestão de objetos e acesso ao conteúdo. Disponível através das APIs REST do Search Service e das bibliotecas de cliente do SDK do Azure equivalentes.

Descrições de funções

Os seguintes funções predefinidas concedem permissões ao Pesquisa de IA do Azure. Os papéis no plano de controlo estão sempre disponíveis, enquanto os papéis no plano de dados exigem acesso baseado em funções para estar ativado no seu serviço de pesquisa. Pode combinar funções incorporadas para um acesso mais amplo ou criar uma função personalizada com as permissões específicas de que precisa.

Funções Avião Descrição
Proprietário Controlo
  • Acesso total ao plano de controlo, incluindo a capacidade de atribuir papéis e alterar as definições de autenticação.
  • Os administradores de subscrição têm esta função por defeito.
  • Consegue gerir chaves API.
  • Não é possível criar objetos de pesquisa, carregar documentos, consultar índices ou recuperar de bases de conhecimento.
Contribuinte Controlo
  • Mesmo nível de acesso ao plano de controlo que o Proprietário, menos a possibilidade de atribuir funções.
Leitor Controlo
  • Acesso de leitura ao plano de controlo.
  • Pode visualizar métricas de serviço e definições de objetos.
  • Não consigo visualizar ou gerir chaves de API, carregar documentos, consultar índices ou recuperar de bases de conhecimento.
Colaborador do Serviço de Pesquisa Controlo & Dados
  • Acesso total ao plano de controlo. O acesso à camada de dados está limitado à gestão de objetos.
  • Pode criar índices, indexadores, conjuntos de competências, bases de conhecimento e outros objetos de pesquisa.
  • Permite recuperar chaves de API de administração e de consulta através de operações do plano de controlo.
  • Não é possível carregar documentos, consultar índices ou recuperar diretamente de bases de conhecimento através de acesso baseado em funções.
  • Para a lista completa de permissões, veja Microsoft.Search/searchServices/*.
Contribuidor de dados do índice de pesquisa Dados
  • Acesso a conteúdos de leitura e escrita.
  • Pode carregar documentos, consultar índices e recuperar a partir de bases de conhecimento.
  • Não é possível modificar definições de objetos nem recuperar chaves de administração.
Leitor de dados de índice de pesquisa Dados
  • Acesso a conteúdos apenas de leitura.
  • Pode consultar índices e recuperar de bases de conhecimento.
  • Não é possível carregar documentos, modificar definições de objetos ou recuperar chaves de administração.

Importante

  • Proprietário, Contribuidor e Contribuidor do Serviço de Pesquisa podem obter chaves de administração, que fornecem acesso total de leitura e escrita ao plano de dados. Conceda estes papéis apenas a utilizadores de confiança.
  • Por defeito, as funções da camada de dados aplicam-se a todos os índices do serviço de pesquisa. Para englobar o Contribuidor de Dados do Índice de Pesquisa ou Leitor de Dados do Índice de Pesquisa a um único índice, veja Conceder acesso a um único índice.

Resumo das permissões

Use a tabela seguinte para encontrar rapidamente qual a função que oferece as permissões de que precisa.

Permissões Proprietário/Colaborador Leitor Colaborador do Serviço de Pesquisa Contribuidor de dados do índice de pesquisa Leitor de dados de índice de pesquisa
Criar e configurar serviços Pesquisa de IA do Azure ✅ ❌ ✅ ❌ ❌
Aceder ao serviço no portal Azure ✅ ✅ ✅ ❌ ❌
Ver as propriedades do serviço, métricas e ponto de extremidade ✅ ✅ ✅ ❌ ❌
Liste todos os objetos no serviço ✅ ✅ ✅ ❌ ❌
Aceder a quotas e estatísticas de serviços ✅ ❌ ✅ ❌ ❌
Visualizar, copiar e regenerar chaves ✅ ❌ ✅ ❌ ❌
Definir opções de autenticação ✅ ❌ ✅ ❌ ❌
Ver funções, políticas e definições ✅ ✅ ✅ ❌ ❌
Configurar a segurança da rede e as ligações privadas ✅ ❌ ✅ ❌ ❌
Criar, executar e gerir objetos de pesquisa 1 ❌ ❌ ✅ ❌ ❌
Carregar dados para indexação 2 ❌ ❌ ❌ ✅ ❌
Consultar um índice ❌ ❌ ❌ ✅ ✅
Recuperar a partir de uma base de conhecimento ❌ ❌ ❌ ✅ ✅
Ignorar filtros de permissões com leitura com privilégios elevados (pré-visualização) ❌ ❌ ❌ ✅ ❌

1 Inclui índices, indexadores, fontes de dados, conjuntos de competências, pseudónimos, mapas de sinónimos, sessões de depuração, bases de conhecimento e fontes de conhecimento. Os indexadores também suportam operações de execução e reset.

2 Um Proprietário ou Contribuinte pode executar o assistente Importar dados para criar e carregar índices, mesmo que não possa carregar documentos noutros clientes. De forma semelhante, os indexadores podem escrever para qualquer índice no serviço de pesquisa, independentemente das atribuições de funções por índice. Em ambos os casos, o serviço de pesquisa (não o utilizador) executa as ações do plano de dados usando as suas permissões Microsoft.Search/searchServices/indexes/documents/*.

Atribuir funções incorporadas

Nesta secção, atribui funções para:

Atribuir funções para administração de serviços

Os seguintes papéis permitem-lhe criar, configurar e gerir um serviço de pesquisa. Estas funções são hierárquicas, por isso escolhe uma com base no nível de acesso que precisas.

Funções ID
Proprietário 8E3AF657-A8FF-443C-A75C-2FE8C4BCB635
Contribuinte B24988AC-6180-42A0-AB88-20F7382DD24C
Leitor acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Vá ao seu serviço de pesquisa no portal Azure.

  2. No painel esquerdo, selecione Access control (IAM).

  3. Selecione + Adicionar>Adicionar atribuição de função.

    Captura de ecrã da página de controlo de acesso (IAM) para atribuição de funções de administração de serviços.

  4. Selecione uma função: Proprietário, Colaborador ou Leitor.

  5. No separador Members, selecione a identidade do utilizador ou grupo Microsoft Entra. Se estiver a configurar permissões para outro serviço Azure, selecione uma identidade gerida atribuída pelo sistema ou pelo utilizador.

  6. Na aba Rever + atribuir, selecione Rever + atribuir para atribuir a função.

Atribuir funções para desenvolvimento

Os seguintes papéis permitem-lhe criar objetos de pesquisa, carregar documentos, consultar índices e recuperar a partir de bases de conhecimento. Atribuir as três funções para cobrir toda a gama de tarefas de desenvolvimento.

Funções ID
Colaborador do Serviço de Pesquisa 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Contribuidor de dados do índice de pesquisa 8EBE5A00-799E-43F5-93AC-243D3DCE84A7
Leitor de dados de índice de pesquisa 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Vá ao seu serviço de pesquisa no portal Azure.

  2. No painel esquerdo, selecione Access control (IAM).

  3. Selecione + Adicionar>Adicionar atribuição de função.

    Captura de ecrã da página de controlo de acesso (IAM) para atribuição de funções de desenvolvimento.

  4. Selecione Contribuidor do Serviço de Pesquisa.

  5. No separador Members, selecione a identidade do utilizador ou grupo Microsoft Entra. Se estiver a configurar permissões para outro serviço Azure, selecione uma identidade gerida atribuída pelo sistema ou pelo utilizador.

  6. Na aba Rever + atribuir, selecione Rever + atribuir para atribuir a função.

  7. Repita estes passos para atribuir o Contribuidor de Dados do Índice de Pesquisa e o Leitor de Dados do Índice de Pesquisa.

Atribuir funções com acesso só de leitura

Use o seguinte papel para aplicações e processos que só precisam de acesso de leitura a índices e bases de conhecimento. As operações suportadas incluem pesquisa, pesquisa, autocompletar e sugestões de índices e recuperação para bases de conhecimento.

Funções ID
Leitor de dados de índice de pesquisa 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Vá ao seu serviço de pesquisa no portal Azure.

  2. No painel esquerdo, selecione Access control (IAM).

  3. Selecione + Adicionar>Adicionar atribuição de função.

    Captura de ecrã da página de controlo de acesso (IAM) para atribuir funções de acesso a dados apenas de leitura.

  4. Selecione a função de Leitor de Dados do Índice de Pesquisa .

  5. No separador Members, selecione a identidade do utilizador ou grupo Microsoft Entra. Se estiver a configurar permissões para outro serviço Azure, selecione uma identidade gerida atribuída pelo sistema ou pelo utilizador.

  6. Na aba Rever + atribuir, selecione Rever + atribuir para atribuir a função.

Teste de atribuições de função

Use um cliente para testar atribuições de função. Lembrem-se que as funções são cumulativas. Não podes eliminar ou negar funções herdadas que abrangem o nível de subscrição ou grupo de recursos ao nível do recurso (serviço de pesquisa).

Antes de avançar, configure a sua aplicação para ligações sem chave e tenha as atribuições de funções definidas.

  1. Vá ao seu serviço de pesquisa no portal Azure.

  2. No painel esquerdo, selecione Indexes de gestão> de pesquisa para testar permissões relacionadas com o índice:

    • Os Contribuintes do Serviço de Pesquisa podem criar, modificar e eliminar objetos de pesquisa, mas não podem carregar documentos nem executar consultas. Para verificar as permissões, crie um índice de pesquisa.

    • Os contribuidores de dados do índice de pesquisa podem carregar documentos. Não existe opção de carregar documentos no portal de Azure fora do assistente Importar dados, mas podes reset e correr um indexador para confirmar permissões de carregamento de documentos.

    • Os Leitores de Dados de Índice de Pesquisa podem consultar índices. Para verificar as permissões, use o Gerenciador de pesquisa. Deves conseguir enviar consultas e ver resultados, mas não deves conseguir ver definições de índices ou criar índices.

Conceder acesso a um único índice

Em alguns cenários, talvez você queira limitar o acesso de um aplicativo a um único recurso, como um índice.

Atualmente, o portal do Azure não suporta atribuições de funções ao nível do índice. Utilize a CLI do Azure, o PowerShell ou a API REST para atribuir funções com âmbito limitado a um único índice.

Operações de indexação e âmbito por índice

As atribuições de funções por índice aplicam-se apenas a operações diretas da API, como consultas ou uploads de documentos por utilizadores ou aplicações. Os indexadores não estão limitados por permissões por índice porque operam com credenciais de nível de serviço.

Um utilizador com o papel de Contribuidor do Serviço de Pesquisa pode criar indexadores que escrevem em qualquer índice do serviço de pesquisa, mesmo em índices onde esse utilizador não tem atribuição de função por índice.

Para isolamento rigoroso de dados entre índices, considere estas abordagens:

  • Use serviços de pesquisa separados para equipas ou utilizadores que necessitem de isolamento ao nível do índice.
  • Atribuir o Contribuidor de Serviço de Pesquisa apenas a administradores que gerem indexadores.
  • Use controlo de acesso ao nível do documento com filtros de segurança para restringir os resultados das consultas dentro de um índice partilhado.

Criar uma função personalizada

Se os papéis incorporados não fornecerem a combinação certa de permissões, pode criar um papel personalizado para apoiar as operações de que necessita.

Os exemplos seguintes clonam o Search Index Data Reader e depois adicionam a capacidade de listar índices por nome. Normalmente, a listagem dos índices num serviço de pesquisa é considerada um direito administrativo.

  1. Inicie sessão no portal Azure e navegue até ao seu serviço de pesquisa.

  2. No painel esquerdo, selecione Access control (IAM).

  3. No separador de funções Papéis, encontre Search Index Data Reader ou outra função, selecione o ícone de reticências (...) e depois selecione Clonar.

  4. No separador Basics, introduza um nome para a função personalizada, como "Search Index Data Explorer", e depois selecione Next.

  5. Na guia Permissões , selecione Adicionar permissões.

  6. No painel Add permissions, selecione o mosaico Microsoft Pesquisa.

  7. Com as Ações selecionadas no topo, defina as seguintes permissões:

    • Em Microsoft.Search/operations, selecione Read : Listar todas as operações disponíveis.
    • Em Microsoft.Search/searchServices/indexes, selecione Ler : Índice de Leitura.

  8. Mude para Ações de Dados no topo e, sob Microsoft.Search/searchServices/indexes/documents, selecione Leia : Ler Documentos.

    A definição JSON se parece com o exemplo a seguir:

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. Selecionar Adicionar para fechar o painel.

  10. Selecione Revisão e criação para criar o papel.

    Agora você pode atribuir usuários e grupos à função. Para mais informações sobre estes passos, consulte Criar ou atualizar Azure papéis personalizados usando o portal Azure.

Criar uma política de Acesso Condicional

Se precisar de aplicar políticas organizacionais, como autenticação multifator, use Acesso Condicional do Microsoft Entra.

Para criar uma política de Acesso Condicional para o Pesquisa de IA do Azure:

  1. Inicie sessão no portal Azure.

  2. Procure por Acesso Condicional do Microsoft Entra.

  3. Na página de Visão Geral , selecione Criar nova política.

  4. Em aplicações ou ações, adicione Pesquisa de IA do Azure como aplicação cloud, dependendo de como pretende configurar a sua política.

  5. Atualize os restantes parâmetros da sua apólice. Por exemplo, especifique a que utilizadores e grupos a política se aplica.

  6. Guardar a política.

Importante

Se o seu serviço de pesquisa tiver uma identidade gerida atribuída, o serviço de pesquisa específico aparece como uma aplicação na cloud. No entanto, selecionar esse serviço de pesquisa específico não faz cumprir a política. Em vez disso, selecione a aplicação geral na cloud Pesquisa de IA do Azure para aplicar políticas de Acesso Condicional ao seu serviço de pesquisa.

Troubleshooting

Quando desenvolve aplicações que utilizam controlo de acesso baseado em funções para autenticação, pode encontrar alguns problemas comuns:

  • A configuração padrão para um serviço de pesquisa é a autenticação baseada em chave. Caso não altere esta definição para Ambos ou Controlo de Acesso Baseado em Funções, todos os pedidos que utilizem autenticação baseada em funções são automaticamente recusados, independentemente das permissões subjacentes.

  • Se o seu pedido incluir uma chave API juntamente com credenciais baseadas em funções, o serviço autentica-se usando a chave. Remova a chave API dos cabeçalhos dos pedidos para usar autenticação baseada em funções.

  • Se o token de autorização provém de uma identidade gerida e recentemente atribuiu as permissões apropriadas, pode demorar várias horas até que as atribuições de permissões entrem em vigor.

  • Se as consultas com permissões ao nível do documento não devolverem os resultados esperados, use o Search Index Data Contributor ou crie um papel personalizado com permissões elevadas (pré-visualização) para investigar.

Próximo passo

Este artigo explica como atribuir funções para operações de controlo e planos de dados no Pesquisa de IA do Azure. Para instruções completas sobre como adicionar acesso baseado em funções ao código da sua aplicação:

Liga a tua aplicação à Pesquisa de IA do Azure usando identidades

  • Última atualização a