Início Rápido: Conectar sem chaves

Artigo
12/20/2024

Configure a Pesquisa de IA do Azure para usar a autenticação do Microsoft Entra ID e o RBAC (controle de acesso baseado em função) para que você possa se conectar do sistema local sem chaves de API, usando notebooks Jupyter ou um cliente REST para interagir com seu serviço de pesquisa.

Se você seguiu outros guias de início rápido que se conectam usando chaves de API, este início rápido mostra como mudar para a autenticação baseada em identidade para que você possa evitar chaves inseridas no código no seu exemplo de código.

Pré-requisitos

Uma assinatura do Azure. Crie um gratuitamente.
A Pesquisa de IA do Azure inclui qualquer região ou nível, mas você precisa dos níveis Básico ou superior para configurar uma identidade gerenciada para a Pesquisa de IA do Azure.
Uma ferramenta de linha de comando, como PowerShell ou Bash, e a CLI do Azure.

Etapa 1: obter sua assinatura e IDs de locatário do Azure

Essa etapa será necessária se você tiver mais de uma assinatura ou locatário.

Obtenha a assinatura e o locatário do Azure para o seu serviço de pesquisa:
1. Entre no portal do Azure e navegue para o seu serviço de pesquisa.
2. Veja qual é a ID e o nome da assinatura em Visão Geral>Itens Essenciais.
3. Agora, selecione o nome da assinatura para mostrar o grupo de gerenciamento pai (ID do locatário) na próxima página.
Agora você sabe em qual assinatura e locatário está a Pesquisa de IA do Azure. Troque para seu dispositivo loca e um prompt de comando e identifique a assinatura e o locatário ativos do Azure no seu dispositivo local:
```
az account show
```
Se a assinatura ativa e o locatário forem diferentes das informações obtidas na etapa anterior, altere a ID da assinatura. Em seguida, entre no Azure usando a ID do locatário encontrada na etapa anterior:
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

Etapa 2: configurar a Pesquisa de IA do Azure para RBAC

Entre no portal do Azure e navegue até seu serviço da Pesquisa de IA do Azure.
Habilite o controle de acesso baseado em função (RBAC):
1. Vá para Configurações>Chaves.
2. Escolha Controle baseado em função ou Ambos se precisar de tempo para fazer a transição de clientes para o controle de acesso baseado em função.
  
  Se você escolher Controle baseado em função, atribua a si mesmo todas as funções nomeadas na próxima instrução ou não poderá concluir tarefas no portal do Azure ou por meio de um cliente local.
Atribua funções no portal do Azure:
1. Navegue até seu serviço de pesquisa.
2. Selecione Controle de Acesso (IAM) no painel de navegação à esquerda.
3. Selecione +Adicionar>Adicionar atribuição de função.
4. Escolha uma função (Colaborador do Serviço de Pesquisa, Colaborador de Dados do Índice de Pesquisa, Leitor de Dados de Índice de Pesquisa) e a atribua à identidade do seu usuário ou grupo no Microsoft Entra.
  
  Repita para cada função.
  
  Você precisa do Colaborador do Serviço de Pesquisa mais Colaborador de Dados do Índice de Pesquisa para criar, carregar e consultar objetos na Pesquisa de IA do Azure. Para obter mais informações, confira Conectar usando funções.

Dica

Posteriormente, se você receber erros de falha de autenticação, verifique novamente as configurações nesta seção. Pode haver políticas no nível de assinatura ou grupo de recursos que substituam as configurações de API que você especificar.

Etapa 3: Conectar-se a partir do seu sistema local

Se você ainda não entrou no Azure:

az login

Usando Python e notebooks do Jupyter

Instale as bibliotecas de Identidade do Azure e Pesquisa do Azure:
```
pip install azure-identity azure-search-documents
```

Autentique-se e se conecte à Pesquisa de IA do Azure:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

Usando um cliente REST

Vários guias de início rápido e tutoriais usam um cliente REST, como o Visual Studio Code com a extensão REST. Veja como fazer para se conectar à Pesquisa de IA do Azure a partir do Visual Studio Code.

Você deve ter um arquivo .rest ou .http, semelhante ao descrito em Início Rápido: busca em vetores.

Gerar um token de acesso.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Na parte superior do arquivo, defina variáveis usadas para a conexão, colando o ponto de extremidade de serviço de pesquisa completo e o token de acesso que você obteve na etapa anterior. As suas variáveis devem ser semelhantes ao exemplo a seguir. Observe que os valores não estão entre aspas.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

Especifique o token de portador da autorização em uma chamada REST:

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

Solucionar erros 401

Verifique a assinatura ativa e o locatário (az account show) e certifique-se de que são válidos para seu serviço de pesquisa.
Verifique o serviço de pesquisa Configurações>Chaves opções no portal do Azure e confirme se o serviço está configurado para Ambos" ou Controle de acesso baseado em função.
Somente para o cliente REST: verifique o token e o ponto de extremidade especificados no seu arquivo e certifique-se de que não haja aspas ou espaços extras.

Se tudo mais falhar, reinicie o dispositivo para remover todos os tokens armazenados em cache e repita as etapas desta seção, começando com az login.

Configuração adicional

Configure uma identidade gerenciada para conexões de saída:

Configure uma identidade gerenciada atribuída pelo sistema ou pelo usuário para o seu serviço de pesquisa.
Use atribuições de função para autorizar o acesso a outros recursos do Azure.

Configuração de acesso à rede:

Defina regras de entrada para aceitar ou rejeitar solicitações à Pesquisa de IA do Azure com base no endereço IP.

Compartilhar via