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

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)

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>"

1. Entre no portal do Azure.

2. Atribuir essas funções a:

   • Colaborador do Serviço de Pesquisa (criar, ler, atualizar e excluir operações 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)

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>"

1. Entre no portal do Azure.

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

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 seu serviço do Azure, por exemplo, Azure OpenAI.

    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 os espaços reservados por valores válidos.

   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
   

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 existe nenhuma opção de carregar documentos no portal do Azure fora do assistente de Importação de dados, mas você pode 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.

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 em sua assinatura do Azure.

   az login
   

2. Obtenha a ID do locatário e a ID da assinatura. Use a ID 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=2025-09-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.

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 usando 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);
   

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 uma aplicação que roda 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)
   

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

2. Use Azure.Identity em JavaScript para 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.

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

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

3. Use DefaultAzureCredential para aplicativos executados no Azure.

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

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, vá para 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, use 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 Revisar + criar para criar o papel. Agora você pode atribuir usuários e grupos à função.

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 a 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ê precisa das seguintes permissões:

   "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 o 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}"
  ]
}

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).

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 aba do PowerShell para sintaxe JSON.