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

1. Entre no portal do Azure.

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

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

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

5. Selecione uma função aplicável:

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

6. Na guia Membros, selecione a identidade do usuário ou do grupo do Microsoft Entra.

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

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. Navegue até seu serviço de pesquisa.

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

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

   

5. Selecione uma função:

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

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

6. Na guia Membros, selecione a identidade do usuário ou do grupo do Microsoft Entra.

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

8. Repita para as outras funções. A maioria dos desenvolvedores precisa dos três.

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. Navegue até seu serviço de pesquisa.

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

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

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

6. Na guia Membros, selecione a identidade do usuário ou do grupo do Microsoft Entra. Caso esteja configurando permissões para outro serviço, poderá estar usando um sistema ou uma identidade gerenciada pelo usuário. Escolha essa opção se a atribuição de função for para uma identidade de serviço.

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

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
   

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.

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.

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

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)
   

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.

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.

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.

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

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