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

O Azure fornece uma autenticação global e um controlo de acesso baseado na função através 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 no Azure AI Search.

No Azure AI Search, você pode atribuir funções do Azure para:

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

O acesso por usuário nos resultados da pesquisa (às vezes chamado de segurança em nível de linha ou segurança em nível de documento) não é suportado 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 documentos aos quais o solicitante não deve ter acesso. Veja este exemplo de bate-papo corporativo usando o RAG para obter uma demonstração.

As atribuições de função são cumulativas e generalizadas em todas as ferramentas e bibliotecas de clientes. Você pode atribuir funções usando qualquer uma das abordagens com suporte descritas na documentação de 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 camada, habilitado para acesso baseado em função.

• Proprietário, Administrador de Acesso de 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. Inicie sessão no portal do Azure.

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

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

4. Selecione Controle de acesso (IAM) no painel de navegação esquerdo.

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

   

6. Selecione 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 cada função definida.

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

8. No separador Rever + atribuir, selecione Rever + atribuir para atribuir a função.

Funções incorporadas utilizadas na pesquisa

O plano de dados refere-se 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 de Pesquisa ou bibliotecas de cliente equivalentes do SDK do Azure.

O plano de controle refere-se ao gerenciamento de recursos do Azure, como a criação ou configuração de um serviço de pesquisa.

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

Role	Avião	Description
Proprietário	Controlo & Dados	Acesso total ao plano 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 para outros usuários. Os administradores de subscrição são membros por predefinição. No plano de dados, essa função tem o mesmo acesso que a função de Colaborador do Serviço de Pesquisa. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Contribuinte	Controlo & 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 de Colaborador do Serviço de Pesquisa. Inclui acesso a todas as ações do plano de dados, exceto a capacidade de consultar ou indexar documentos.
Leitor	Controlo & 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 as 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 ler conteúdo dentro de índices.
Colaborador do Serviço de Pesquisa	Controlo & Dados	Acesso de leitura-gravação a definições de objeto (í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 de índice. Use essa função para criar, excluir e listar índices, obter definições de índice, 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. Consulte Microsoft.Search/searchServices/* a lista de permissões.
Contribuidor de dados do índice de pesquisa	Dados	Acesso de leitura-gravação ao conteúdo em í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. Esta função não suporta a criação ou gestão 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 consultar índices de pesquisa. Essa função é para aplicativos e usuários que executam consultas. Esta função não suporta acesso de leitura a definições de objeto. Por exemplo, não é possível ler uma definição de índice de pesquisa ou 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.

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

Nota

Se você desabilitar o acesso baseado em função do Azure, as funções internas para o 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	Contribuidor de dados do í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	❌	❌	✅	✅	✅
Aceder a quotas e estatísticas de serviços	❌	❌	✅	✅	❌
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 do Azure AI Search	❌	❌	✅	✅	❌
Ver/Copiar/Regenerar chaves em Chaves	❌	❌	✅	✅	❌
Ver 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 apenas Proprietários podem atribuir funções.

Os 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 de plano de dados. Ao configurar posteriormente a Pesquisa do Azure AI para usar "somente funções", 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 de Serviço de Pesquisa.

Atribuir funções

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

• Administração de serviços
• 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ços

Como administrador de serviço, você pode criar e configurar um serviço de pesquisa e executar todas as operações do plano de controle descritas na API REST de gerenciamento ou bibliotecas de cliente 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.

Role	ID
Owner	8E3AF657-A8FF-443C-A75C-2FE8C4BCB635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Atribua estas funções:

   • Proprietário (acesso total a todas as operações do plano de dados e do plano de controle, exceto permissões de consulta)
   • Colaborador (o mesmo que Proprietário, exceto para permissões para atribuir funções)
   • Leitor (aceitável para monitoramento e visualização de métricas)

PowerShell

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

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

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.

Task	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 total é Colaborador ou Proprietário, além de Leitor de Dados de Índice de Pesquisa.

Importante

Se você configurar o acesso baseado em função para um serviço ou índice e também fornecer uma chave de API na solicitação, o serviço de pesquisa usará a chave de API para autenticar.

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Atribua estas funções:

   • Colaborador do Serviço de Pesquisa (operações create-read-update-delete em índices, indexadores, conjuntos de habilidades e outros objetos de nível superior)
   • Search Index Data Contributor (carregar documentos e executar trabalhos de indexação)
   • Leitor de dados de índice de pesquisa (consultar um índice)

PowerShell

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

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

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 escopo para um índice específico:

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.

Role	ID
Search Index Data Readercom o PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

Trata-se de um papel muito específico. Ele concede acesso GET ou POST à coleção de documentos de um índice de pesquisa para pesquisa, preenchimento automático e sugestões. Ele não suporta 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 ser completa, 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.

Portal do Azure

1. Inicie sessão no portal do Azure.

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

PowerShell

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

1. Obtenha o 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 seu serviço do Azure, como o Azure OpenAI.

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

3. Obtenha a definição de função e reveja as permissões para se certificar de que esta é a função que pretende.

   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
   

Atribuições de função de teste

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

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

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Navegue até o 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 ou consultar um índice. Para verificar as permissões, crie um índice de pesquisa.

   • Os contribuidores de dados do índice de pesquisa podem carregar documentos. Não há nenhuma opção de carregamento de documentos no portal fora do assistente Importar dados, mas você pode redefinir e executar um indexador para confirmar as permissões de carregamento de documentos.

   • Os leitores de dados do índice de pesquisa podem consultar o índice. Para verificar as permissões, use o Gerenciador de pesquisa. Você deve ser capaz de enviar consultas e exibir resultados, mas não deve ser capaz de visualizar a definição de índice ou criar uma.

API REST

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

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

   az login
   

2. Obtenha o seu ID de inquilino e ID de subscrição. O ID é usado 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 essas 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 suportada.

   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, consulte Gerenciar um serviço Azure AI Search com APIs REST e bibliotecas de autenticação de plataforma de identidade da Microsoft.

.NET

1. Use o pacote Azure.Search.Documents .

2. Use Azure.Identity para .NET para 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 usando DefaultAzureCredential()o .

   // 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 uso da 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 para autenticação de token.

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

4. Eis 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 para autenticação de token.

3. Se você estiver usando o React, use InteractiveBrowserCredential a autenticação do Microsoft Entra para pesquisar. Consulte Quando usar @azure/identity para obter detalhes.

Java

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

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

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

Testar como usuário atual

Se já for um Colaborador ou Proprietário do seu serviço de pesquisa, pode apresentar um token de portador para a sua identidade de utilizador para autenticação no Azure AI Search.

1. Obtenha um token de 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. Cole essas 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
   

3. Cole e envie uma solicitação para confirmar o acesso. Aqui está um que consulta o índice de início rápido de hotéis

   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 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 não oferece suporte a atribuições de função nesse nível de granularidade, mas pode ser feito com o PowerShell ou a CLI do Azure.

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

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

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

2. Adicione uma atribuição de função com escopo a 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 as funções internas não fornecerem a combinação correta de permissões, você poderá criar uma função personalizada para dar suporte às operações necessárias.

Este exemplo clona o Search Index Data Reader e, em seguida, adiciona a capacidade de listar índices por nome. Normalmente, a listagem dos índices num serviço de pesquisa é considerada um direito administrativo.

Portal do Azure

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

Estas etapas criam uma função personalizada que aumenta os direitos de consulta de pesquisa para incluir índices de listagem por nome. Normalmente, listar índices é considerado uma função de administração.

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

2. No painel de navegação esquerdo, selecione Controle de acesso (IAM).

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

4. Clique com o botão direito do mouse em Leitor de Dados de Índice de Pesquisa (ou outra função) e selecione Clonar para abrir o assistente Criar uma função personalizada.

5. Na guia Noções básicas, forneça um nome para a função personalizada, como "Search Index Data Explorer" e selecione Avançar.

6. Na guia Permissões, selecione Adicionar permissão.

7. Na guia Adicionar permissões, procure 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 padrão Ações :

   • Em Microsoft.Search/operations, selecione Read : List all available operations.
   • Em Microsoft.Search/searchServices/indexes, selecione Ler : 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 exemplo a seguir:

   {
    "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 Rever + criar para criar a função. Agora você pode atribuir usuários e grupos à função.

Azure PowerShell

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

1. Revise a lista de permissões atômicas para determinar 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, consulte 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}"
  ]
}

Nota

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

API REST

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

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

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

CLI do Azure

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

2. Consulte Criar ou atualizar funções personalizadas do Azure usando a CLI do Azure para obter etapas.

3. Consulte a guia PowerShell para obter a sintaxe JSON.

Acesso Condicional

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

Para habilitar uma política de Acesso Condicional para o Azure AI Search, siga estas etapas:

1. Inicie sessão no portal do Azure.

2. Procure acesso condicional do Microsoft Entra.

3. Selecione Políticas.

4. Selecione Nova política.

5. Na seção Aplicativos ou ações na nuvem da política, adicione o Azure AI Search como um aplicativo na 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. Guardar a política.

Importante

Se o seu serviço de pesquisa tiver uma identidade gerenciada atribuída a ele, o serviço de pesquisa específico aparecerá como um aplicativo na 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 aplicadas a um serviço de pesquisa específico. Em vez disso, certifique-se de selecionar o aplicativo de nuvem geral do Azure AI Search .

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 entidade de serviço aciona 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 direcionadas a recursos de serviço diferentes (índices, indexadores, etc.), é possível que as verificações de autorização resultem em limitação. A limitação só aconteceria se centenas de combinações exclusivas de recurso de serviço de pesquisa e entidade de serviço fossem usadas em um segundo.

Solução de problemas de controle de acesso baseado em função

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

• Se o token de autorização veio 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 para um serviço de pesquisa é a autenticação baseada em chave. Se você não alterou a configuração de chave padrão para Ambos ou Controle de acesso baseado em função, todas as solicitações que usam autenticação baseada em função serão negadas automaticamente, independentemente das permissões subjacentes.