Guia de início rápido: conectar sem teclas

Artigo
12/20/2024

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

Se você passou por outros inícios rápidos que se conectam usando chaves de API, este guia de início rápido mostra como alternar para a autenticação baseada em identidade para que você possa evitar chaves codificadas em seu código de exemplo.

Pré-requisitos

Uma subscrição do Azure. Crie um gratuitamente.
Azure AI Search, qualquer região ou camada, mas você precisa de Basic ou superior para configurar uma identidade gerenciada para o Azure AI Search.
Uma ferramenta de linha de comando, como PowerShell ou Bash, e a CLI do Azure.

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

Você precisará desta etapa se tiver mais de uma assinatura ou locatário.

Obtenha a subscrição e o inquilino do Azure para o seu serviço de pesquisa:
1. Entre no portal do Azure e navegue até seu serviço de pesquisa.
2. Observe o nome e o ID da assinatura em Visão geral>do Essentials.
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 o Azure AI Search está. Mude para o seu dispositivo local e para uma linha de comandos e identifique a subscrição ativa do Azure e o inquilino no seu dispositivo:
```
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 de locatário que você encontrou 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é o serviço Azure AI Search.
Habilite o controle de acesso baseado em função (RBAC):
1. Vá para Teclas de configurações>.
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 escolher o controlo baseado em funções, certifique-se de que atribui a si próprio todas as funções nomeadas na próxima instrução ou não conseguirá concluir tarefas no portal do Azure ou através de um cliente local.
Atribua funções no portal do Azure:
1. Navegue até o serviço de pesquisa.
2. Selecione Controle de acesso (IAM) no painel de navegação esquerdo.
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 do Índice de Pesquisa) e atribua-a à sua identidade de usuário ou grupo do Microsoft Entra.
  
  Repita para cada função.
  
  Você precisa do Colaborador do Serviço de Pesquisa mais do Colaborador de Dados do Índice de Pesquisa para criar, carregar e consultar objetos no Azure AI Search. Para obter mais informações, consulte Conectar-se usando funções.

Gorjeta

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

Passo 3: Ligar a partir do seu sistema local

Se ainda não iniciou sessão no Azure:

az login

Usando notebooks Python e Jupyter

Instale as bibliotecas Azure Identity e Azure Search:
```
pip install azure-identity azure-search-documents
```

Autentique e conecte-se ao Azure AI Search:

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 você se conecta ao Azure AI Search a partir do Visual Studio Code.

Você deve ter um .rest arquivo ou .http semelhante ao descrito em Guia de início rápido: pesquisa vetorial.

Gere 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 as variáveis usadas para a conexão, colando o ponto de extremidade completo do serviço de pesquisa e o token de acesso obtido na etapa anterior. 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 de 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 problemas de erros 401

Verifique a subscrição ativa e o inquilino (az account show) e certifique-se de que é válido para o seu serviço de pesquisa.
Verifique as opções de Chaves de Configurações>do serviço de pesquisa no portal do Azure e confirme se o serviço está configurado para controle de acesso baseado em função ou Ambos.
Somente para o cliente REST: verifique o token e o ponto de extremidade especificados em seu arquivo e certifique-se de que não há aspas ao redor ou espaços extras.

Se tudo falhar, reinicie o dispositivo para remover quaisquer tokens armazenados em cache e repita as etapas nesta 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 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 para o Azure AI Search com base no endereço IP.

Partilhar via