Conectar-se à Pesquisa de IA do Azure usando funções

O Azure fornece uma autenticação global e controle de acesso baseado em função por meio do Microsoft Entra ID para todos os serviços em execução na plataforma. Neste artigo, saiba quais funções fornecem acesso ao conteúdo de pesquisa e à administração na Pesquisa de IA do Azure.

Na Pesquisa de IA do Azure, você poderá atribuir funções do Azure em:

• Administração do serviço
• Desenvolvimento ou acesso de gravação a um serviço de pesquisa
• Acesso somente leitura para consultas
• Acesso com escopo a apenas um índice

Não há suporte para o acesso por usuário aos resultados da pesquisa (às vezes chamado de segurança em nível de linha ou segurança em nível de documento) por meio de atribuições de função. Como solução alternativa, crie filtros de segurança que cortam os resultados por identidade do usuário, removendo os documentos aos quais o solicitante não deve ter acesso. Confira esta Amostra de chat corporativo usando o RAG para uma demonstração.

As atribuições de função são cumulativas e disseminadas em todas as ferramentas e bibliotecas de clientes. Você pode atribuir funções usando uma das abordagens com suporte descritas na documentação do controle de acesso baseado em função do Azure.

O acesso baseado em função é opcional, mas recomendado. A alternativa é a autenticação baseada em chave, que é o padrão.

Pré-requisitos

• Um serviço de pesquisa em qualquer região, em qualquer nível, habilitado para acesso baseado em função.

• Proprietário, Administrador de Acesso do Usuário, Administrador de Controle de Acesso baseado em Função ou uma função personalizada com permissões Microsoft.Authorization/roleAssignments/write.

Como atribuir funções no portal

As etapas a seguir funcionam para todas as atribuições de função.

1. Entre no portal do Azure.

2. Navegue até seu serviço de pesquisa.

3. Habilitar o acesso baseado em função.

4. Selecione Controle de Acesso (IAM) no painel de navegação à esquerda.

5. Selecione + Adicionar>Adicionar atribuição de função para iniciar o assistente Adicionar atribuição de função.

   

6. Selecionar uma função. Você pode atribuir várias entidades de segurança, sejam usuários ou identidades gerenciadas a uma função em uma passagem pelo assistente, mas precisa repetir essas etapas para definição de cada função.

7. Na guia Membros, selecione a identidade do usuário ou do grupo do Microsoft Entra. Se você estiver configurando permissões para outro serviço do Azure, selecione um sistema ou uma identidade gerenciada pelo usuário.

8. Na guia Examinar + atribuir, selecione Examinar + atribuir para atribuir a função.

Funções internas usadas na pesquisa

Plano de dados se refere a operações no ponto de extremidade do serviço de pesquisa, como indexação ou consultas, ou qualquer outra operação especificada nas APIs REST do Serviço Pesquisa ou bibliotecas de cliente do SDK do Azure equivalentes.

Painel de controle se refere ao gerenciamento de recursos do Azure, como criar ou configurar um serviço de pesquisa.

As funções a seguir são internas. Se essas funções forem insuficientes, crie uma função personalizada.

Função	Plano	Descrição
Proprietário	Controle e dados	Acesso completo ao painel de controle do recurso de pesquisa, incluindo a capacidade de atribuir funções do Azure. Somente a função Proprietário pode habilitar ou desabilitar opções de autenticação ou gerenciar funções de outros usuários. Os administradores de assinatura são membros por padrão. No plano de dados, essa função tem o mesmo acesso que a função Colaborador do Serviço de Pesquisa. Ela inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Colaborador	Controle e dados	Mesmo nível de acesso ao plano de controle que o Proprietário, menos a capacidade de atribuir funções ou alterar opções de autenticação. No plano de dados, essa função tem o mesmo acesso que a função Colaborador do Serviço de Pesquisa. Ela inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Leitor	Controle e dados	Acesso de leitura em todo o serviço, incluindo métricas de pesquisa, métricas de conteúdo (armazenamento consumido, número de objetos) e definições de objeto de recursos do plano de dados (índices, indexadores e assim por diante). No entanto, ele não pode ler chaves de API ou conteúdo em índices.
Colaborador do Serviço de Pesquisa	Controle e dados	Acesso de leitura e gravação a definições de objetos (índices, aliases, mapas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades). Essa função é para desenvolvedores que criam objetos e para administradores que gerenciam um serviço de pesquisa e seus objetos, mas sem acesso ao conteúdo do índice. Use essa função para criar, excluir e listar índices, obter definições de índices, obter informações de serviço (estatísticas e cotas), testar analisadores, criar e gerenciar mapas de sinônimos, indexadores, fontes de dados e conjuntos de habilidades. Confira Microsoft.Search/searchServices/* para obter a lista de permissões.
Colaborador de dados de índice de pesquisa	Dados	Acesso de leitura e gravação ao conteúdo dos índices. Essa função é para desenvolvedores ou proprietários de índice que precisam importar, atualizar ou consultar a coleção de documentos de um índice. Essa função não dá suporte à criação ou ao gerenciamento de índices. Por padrão, essa função é para todos os índices em um serviço de pesquisa. Consulte Conceder acesso a um único índice para restringir o escopo.
Leitor de dados de índice de pesquisa	Dados	Acesso somente leitura para a consulta de índices de pesquisa. Essa função é para os usuários que executam consultas em um índice. Essa função não dá suporte ao acesso de leitura às definições de objeto. Por exemplo, você não pode ler uma definição de índice de pesquisa nem obter estatísticas do serviço de pesquisa. Por padrão, essa função é para todos os índices em um serviço de pesquisa. Consulte Conceder acesso a um único índice para restringir o escopo.

Agrupe essas funções para obter permissões suficientes para o seu caso de uso.

Observação

Se você desabilitar o acesso baseado em função do Azure, as funções internas do plano de controle (Proprietário, Colaborador, Leitor) continuarão disponíveis. A desativação do acesso baseado em função remove apenas as permissões relacionadas a dados associadas a essas funções. Se as funções do plano de dados estiverem desabilitadas, o Colaborador do serviço de pesquisa será equivalente ao Colaborador do plano de controle.

Resumo

Permissões	Leitor de dados de índice de pesquisa	Colaborador de dados de índice de pesquisa	Colaborador do Serviço de Pesquisa	Proprietário/Colaborador	Leitor
Exibir o recurso no portal do Azure	❌	❌	✅	✅	✅
Exibir propriedades/métricas/ponto de extremidade do recurso	❌	❌	✅	✅	✅
Listar todos os objetos no recurso	❌	❌	✅	✅	✅
Cotas de acesso e estatísticas de serviço	❌	❌	✅	✅	❌
Ler/consultar um índice	✅	❌	❌	❌	❌
Carregar dados para indexação	❌	✅	❌	❌	❌
Criar ou editar índices/aliases	❌	❌	✅	✅	❌
Criar, editar e executar indexadores/fontes de dados/conjuntos de habilidades	❌	❌	✅	✅	❌
Criar ou editar mapas de sinônimos	❌	❌	✅	✅	❌
Criar ou editar sessões de depuração	❌	❌	✅	✅	❌
Criar ou gerenciar implantações	❌	❌	✅	✅	❌
Criar ou configurar recursos da Pesquisa de IA do Azure	❌	❌	✅	✅	❌
Exibir/Copiar/Regenerar chaves em Chaves	❌	❌	✅	✅	❌
Exibir funções/políticas/definições	❌	❌	✅	✅	❌
Definir opções de autenticação	❌	❌	✅	✅	❌
Configurar conexões privadas	❌	❌	✅	✅	❌
Configurar a segurança de rede	❌	❌	✅	✅	❌

Proprietários e Colaboradores concedem as mesmas permissões, exceto que somente os Proprietários podem atribuir funções.

Proprietários e Colaboradores podem criar, ler, atualizar e excluir objetos no portal do Azure se as chaves de API estiverem habilitadas. O portal usa chaves em chamadas internas para APIs do plano de dados. Se você configurar posteriormente a Pesquisa de IA do Azure para usar "somente funções", então o Proprietário e o Colaborador não poderão gerenciar objetos no portal usando apenas essas atribuições de função. A solução é atribuir mais funções, como Leitor de Dados de Índice de Pesquisa, Colaborador de Dados de Índice de Pesquisa e Colaborador do Serviço de Pesquisa.

Atribuir funções

Nesta seção, atribua funções para:

• Administração do serviço
• Desenvolvimento ou acesso de gravação a um serviço de pesquisa
• Acesso somente leitura para consultas

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

Como administrador de serviços, é possível criar e configurar um serviço de pesquisa e executar todas as operações de plano de controle descritas na API REST de Gerenciamento ou bibliotecas de clientes equivalentes. Se você for um Proprietário ou Colaborador, também poderá executar a maioria das tarefas da API REST de Pesquisa do plano de dados no portal do Azure.

Função	ID
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure portal

1. Entre no portal do Azure.

2. Atribuir essas funções a:

   • Proprietário (acesso total a todas as operações do plano de dados e do plano de controle, exceto para permissões de consulta)
   • Colaborador (igual ao Proprietário, exceto pelas permissões para atribuir funções)
   • Leitor (aceitável para monitorar e exibir métricas)

PowerShell

Ao usar o PowerShell para atribuir funções, chame New-AzRoleAssignment, fornecendo o nome do usuário ou do grupo do Azure e o escopo da atribuição.

Este exemplo cria uma atribuição de função com um serviço de pesquisa como escopo:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Atribuir funções para desenvolvimento

As atribuições de função são globais em todo o serviço de pesquisa. Para definir o escopo de permissões para um único índice, use o PowerShell ou a CLI do Azure para criar uma função personalizada.

Tarefa	Função	ID
Operações CRUD	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Carregar documentos, executar trabalhos de indexação	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Consultar um índice	Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

Outra combinação de funções que fornece acesso completo é Colaborador ou Proprietário, além do Leitor de Dados do Índice de Pesquisa.

Importante

Caso configure o acesso baseado em função para um serviço ou índice e também forneça uma chave de API na solicitação, o serviço de pesquisa usará a chave de API para autenticar.

Azure portal

1. Entre no portal do Azure.

2. Atribuir essas funções a:

   • Colaborador do Serviço de Pesquisa (operações de criação-leitura-atualização-exclusão em índices, indexadores, conjuntos de habilidades e outros objetos de nível superior)
   • Colaborador de Dados de Índice de Pesquisa (carregar documentos e executar trabalhos de indexação)
   • Leitor de Dados de Índice de Pesquisa (consultar um índice)

PowerShell

Ao usar o PowerShell para atribuir funções, chame New-AzRoleAssignment, fornecendo o nome do usuário ou do grupo do Azure e o escopo da atribuição.

Este exemplo cria uma atribuição de função com um serviço de pesquisa como escopo:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Este exemplo cria uma atribuição de função com um índice específico como escopo:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Atribuir funções para consultas somente leitura

Use a função Leitor de Dados de Índice de Pesquisa para aplicativos e processos que só precisam de acesso de leitura a um índice.

Função	ID
Search Index Data Reader Com o PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

Essa é uma função muito específica. Ele concede acesso ao GET ou POST à coleção de documentos de um índice de pesquisa para pesquisa, preenchimento automático e sugestões. Ele não dá suporte a operações GET ou LIST em um índice ou outros objetos de nível superior ou estatísticas de serviço GET.

Esta seção fornece etapas básicas para configurar a atribuição de função e está aqui para fins de integridade, mas recomendamos usar a Pesquisa de IA do Azure sem chaves para obter instruções abrangentes sobre como configurar seu aplicativo para acesso baseado em função.

Azure portal

1. Entre no portal do Azure.

2. Atribuir a função Leitor de Dados de Índice de Pesquisa.

PowerShell

Quando usar o PowerShell para atribuir funções, chame New-AzRoleAssignment, fornecendo o nome do usuário ou do grupo do Azure e o escopo da atribuição.

1. Obtenha a ID da assinatura, o grupo de recursos do serviço de pesquisa e o nome do serviço de pesquisa.

2. Obtenha o identificador de objeto do serviço do Azure, como o OpenAI do Azure.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Obtenha a definição de função e examine as permissões para verificar se essa é a função desejada.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Crie a atribuição de função, substituindo valores válidos para os espaços reservados.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Aqui está um exemplo de uma atribuição de função com escopo para um índice específico:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

Testar atribuições de função

Use um cliente para testar atribuições de função. Lembre-se de que elas são cumulativas e as herdadas com escopo no nível da assinatura ou do grupo de recursos não podem ser excluídas nem negadas no nível do recurso (serviço de pesquisa).

Configure seu aplicativo para conexões sem chave e tenha atribuições de função em vigor antes do teste.

Portal do Azure

1. Entre no portal do Azure.

2. Navegue até seu serviço de pesquisa.

3. Na página Visão geral, selecione a guia Índices:

   • Os colaboradores do Serviço de Pesquisa podem exibir e criar qualquer objeto, mas não podem carregar documentos nem consultar um índice. Para verificar as permissões, crie um índice de pesquisa.

   • Os Colaboradores de Dados de Índice de Pesquisa podem carregar documentos. Não há nenhuma opção de carregar documentos no portal fora do assistente de Importação de dados, mas é possível redefinir e executar um indexador para confirmar as permissões de carregamento do documento.

   • Os Leitores de Dados do Índice de Pesquisa podem consultar o índice. Para verificar as permissões, use Gerenciador de Pesquisa. Você poderá enviar consultas e exibir resultados, mas não poderá exibir a definição do índice ou criar uma.

REST API

Essa abordagem pressupõe que o Visual Studio Code tem uma extensão de cliente REST.

1. Abra um shell de comando para a CLI do Azure e entre em sua assinatura do Azure.

   az login
   

2. Obter a ID de locatário e a ID de assinatura. A ID é usada como uma variável em uma etapa futura.

   az account show
   

3. Obtenha um token de acesso.

   az account get-access-token --query accessToken --output tsv
   

4. Cole estas variáveis em um novo arquivo de texto no Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Cole e envie uma solicitação que use as variáveis especificadas. Para a função “Leitor de Dados de Índice de Pesquisa”, você pode enviar uma consulta. Você pode usar qualquer versão de API com suporte.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Para obter mais informações sobre como adquirir um token para um ambiente específico, confira Gerenciar um serviço de Pesquisa de IA do Azure com APIs REST e Bibliotecas de autenticação da plataforma de identidade da Microsoft.

.NET

1. Use o pacote Azure.Search.Documents.

2. Use o Azure.Identity para .NET na autenticação de token. A Microsoft recomenda DefaultAzureCredential() para a maioria dos cenários.

3. Aqui está um exemplo de uma conexão de cliente com o uso de DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Aqui está outro exemplo de como usar a credencial de segredo do cliente:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Use azure.search.documents (SDK do Azure para Python).

2. Use Azure.Identity para Python na autenticação com token.

3. Use DefaultAzureCredential se o cliente Python for um aplicativo executado no lado do servidor. Habilite a autenticação interativa se o aplicativo for executado em um navegador.

4. Veja um exemplo:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Use azure/search-documents (SDK do Azure para JavaScript) versão 11.3.

2. Use Azure.Identity para JavaScript na autenticação por token.

3. Se você estiver usando React, use InteractiveBrowserCredential na autenticação do Microsoft Entra no Search. Veja Quando usar @azure/identity para obter detalhes.

Java

1. Use azure-search-documents (SDK do Azure para Java).

2. Use Azure.Identity para Java na autenticação por token.

3. A Microsoft recomenda DefaultAzureCredential para aplicativos executados no Azure.

Testar como usuário atual

Se você já for um Colaborador ou Proprietário do serviço de pesquisa, poderá apresentar um token de portador como identidade de usuário para autenticação no Azure AI Search.

1. Obtenha um token ao portador para o usuário atual usando a CLI do Azure:

   az account get-access-token --scope https://search.azure.com/.default
   

   Ou usando o PowerShell:

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. Em um novo arquivo de texto no Visual Studio Code, cole as variáveis a seguir.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. Cole e envie uma solicitação para confirmar o acesso. Veja um que consulta o índice hotels-quickstart

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Conceder acesso a apenas um índice

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

No momento, o portal não dá suporte as atribuições de função nesse nível de granularidade, mas elas podem ser feitas com o PowerShell ou a CLI do Azure.

No PowerShell, use New-AzRoleAssignment, fornecendo o usuário ou nome de grupo do Azure e o escopo da atribuição.

1. Carregue os módulos Azure e AzureAD e conecte-se à sua conta do Azure:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Adicione uma atribuição de função com escopo em um índice individual:

   New-AzRoleAssignment -ObjectId <objectId> `
       -RoleDefinitionName "Search Index Data Contributor" `
       -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
   

Criar uma função personalizada

Se funções internas não fornecerem a combinação certa de permissões, será possível criar uma função personalizada para dar suporte às operações necessárias.

Este exemplo clona o Leitor de dados do índice de pesquisa e, em seguida, adiciona a capacidade de listar índices por nome. Normalmente, listar os índices em um serviço de pesquisa é considerado um direito administrativo.

Azure portal

Essas etapas são derivadas de Criar ou atualizar funções personalizadas do Azure usando o portal do Azure. Há suporte para clonagem de uma função existente em uma página de serviço de pesquisa.

Essas etapas criam uma função personalizada que aumenta os direitos de consulta de pesquisa para incluir índices de listagem por nome. Normalmente, a listagem de índices é considerada uma função de administrador.

1. No portal do Azure, navegue até o serviço de pesquisa.

2. No painel de navegação à esquerda, selecione Controle de Acesso (IAM).

3. Na barra de ações, selecione Funções.

4. Clique com o botão direito do mouse no Leitor de dados do índice de pesquisa (ou outra função) e selecione Clonar para abrir o assistente Criar uma função personalizada.

5. Na guia Informações básicas, forneça um nome para a função personalizada, como "Gerenciador de Dados de Índice de Pesquisa" e clique em Avançar.

6. Na guia Permissões, clique em Adicionar permissões.

7. Na guia Adicionar permissões, pesquise e selecione o bloco Pesquisa da Microsoft.

8. Defina as permissões para sua função personalizada. Na parte superior da página, usando a seleção de Ações padrão:

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

9. Na mesma página, alterne para Ações de dados e, em Microsoft.Search/searchServices/indexes/documents, selecione Ler: Ler Documentos.

   A definição JSON se parece com o seguinte exemplo:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Selecione Examinar + criar para criar o serviço. Agora você pode atribuir usuários e grupos à função.

PowerShell do Azure

O exemplo do PowerShell mostra a sintaxe JSON para criar uma função personalizada que é um clone do Leitor de dados do índice de pesquisa, mas com capacidade de listar todos os índices por nome.

1. Revise a lista de permissões atômicas para determinar de quais você precisa. Para este exemplo, você precisará do seguinte:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Configure uma sessão do PowerShell para criar a função personalizada. Para obter instruções detalhadas, confira Azure PowerShell

3. Forneça a definição de função como um documento JSON. O exemplo a seguir mostra a sintaxe para criar uma função personalizada com o PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Observação

Se o escopo atribuível estiver no nível do índice, a ação de dados deverá ser "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Revise a lista de permissões atômicas para determinar de quais você precisa.

2. Confira Criar ou atualizar as funções personalizadas do Azure usando a API REST para ver as etapas.

3. Copie ou crie uma função ou use JSON para especificar a função personalizada (confira a guia PowerShell para sintaxe JSON).

CLI do Azure

1. Revise a lista de permissões atômicas para determinar de quais você precisa.

2. Confira Criar ou atualizar as funções personalizadas do Azure usando a CLI do Azure para ver as etapas.

3. Consulte a guia do PowerShell para sintaxe JSON.

Acesso Condicional

Recomendamos o Acesso Condicional do Microsoft Entra se você precisar aplicar políticas organizacionais, como a autenticação multifator.

Para habilitar uma política de Acesso Condicional para a Pesquisa de IA do Azure, siga estas etapas:

1. Entre no portal do Azure.

2. Pesquise Acesso Condicional do Microsoft Entra.

3. Selecione Políticas.

4. Selecione Nova política.

5. Na seção Aplicativos ou ações de nuvem da política, adicione Azure AI Search como um aplicativo de nuvem, dependendo de como você deseja configurar sua política.

6. Atualize os parâmetros restantes da política. Por exemplo, especifique a quais usuários e grupos essa política se aplica.

7. Salve a política.

Importante

Se o serviço de pesquisa tiver uma identidade gerenciada atribuída a ele, o serviço de pesquisa específico aparecerá como um aplicativo de nuvem que pode ser incluído ou excluído como parte da política de Acesso Condicional. As políticas de acesso condicional não podem ser impostas em um serviço de pesquisa específico. Em vez disso, selecione o aplicativo de nuvem Azure AI Search geral.

Limitações

• O controle de acesso baseado em função pode aumentar a latência de algumas solicitações. Cada combinação exclusiva de recurso de serviço (índice, indexador, etc.) e a entidade de serviço dispara uma verificação de autorização. Essas verificações de autorização podem adicionar até 200 milissegundos de latência por solicitação.

• Em casos raros em que as solicitações se originam de um grande número de entidades de serviço diferentes, todas as que visam recursos de serviço diferentes (índices, indexadores etc.), é possível que as verificações de autorização resultem em uma limitação. A limitação só ocorreria se centenas de combinações exclusivas de recurso de serviço de pesquisa e entidade de serviço fossem usadas em um segundo.

Solucionar problemas do controle de acesso baseado em função

Ao desenvolver aplicativos que usam o controle de acesso baseado em função para autenticação, alguns problemas comuns podem ocorrer:

• Se o token de autorização for proveniente de uma identidade gerenciada e as permissões apropriadas foram atribuídas recentemente, pode levar várias horas para que essas atribuições de permissões entrem em vigor.

• A configuração padrão de um serviço de pesquisa é autenticação baseada em chave. Se você não alterou a configuração de chave padrão para Ambos ou para Controle de acesso baseado em função, todas as solicitações que usam a autenticação baseada em função serão negadas automaticamente, independentemente das permissões subjacentes.