Conectar-se à Pesquisa de IA do Azure usando perfis

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)

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

1. Inicie sessão no portal do Azure.

2. Atribua estas funções:

   • Search Service Contributor (criar, ler, atualizar e eliminar índices, indexadores, conjuntos de competências 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)

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

1. Inicie sessão no portal do Azure.

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

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
   

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 do Azure 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.

Esta abordagem assume Código Visual Studio com uma extensão 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. Use o ID como variável numa 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 depois envie um pedido que use as variáveis que especificar. 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=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, consulte Gerenciar um serviço Azure AI Search com APIs REST e bibliotecas de autenticação de plataforma de identidade da Microsoft.

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 ligação ao cliente que utiliza 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 utilização da 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 para autenticação de token.

3. Use DefaultAzureCredential se o cliente Python for uma aplicação que é executada no 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)
   

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

2. Utilize Azure.Identity para JavaScript para autenticação de token.

3. Se estiver a usar o React, utilize InteractiveBrowserCredential para a autenticação do Microsoft Entra no Search. Consulte Quando usar @azure/identity para obter detalhes.

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

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

3. Utilize DefaultAzureCredential para aplicações que executam 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 suporta clonagem a partir de uma função existente.

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 Azure, aceda ao seu 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 rato em Leitor de Dados de Índice de Pesquisa (ou outra função) e selecione Clonar para abrir o assistente de criação de 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 tile Microsoft Search.

8. Defina as permissões para sua função personalizada. No topo da página, use a seleção padrão de Ações :

   • Em Microsoft.Search/operations, selecione Ler : Listar todas as operações disponíveis.
   • 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 Revisão e criação para criar o papel. Agora você pode atribuir usuários e grupos à função.

O exemplo do PowerShell mostra a sintaxe JSON para criar um papel personalizado que é um clone do Search Index Data Reader, mas com a 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, 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 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}"
  ]
}

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

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.