Início Rápido: Conectar-se a um serviço de pesquisa

Neste início rápido, você usará o RBAC (controle de acesso baseado em função) e a ID do Microsoft Entra para estabelecer uma conexão sem chave com seu serviço do Azure AI Search. Em seguida, você usa o Python no Visual Studio Code para interagir com seu serviço.

Conexões sem chave fornecem segurança aprimorada por meio de permissões granulares e autenticação baseada em identidade. Não recomendamos chaves de API codificadas, mas, se preferir, consulte Conectar-se ao Azure AI Search usando chaves.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Um serviço do Azure AI Search em qualquer região ou camada.

• A CLI do Azure para autenticação sem uso de chave com a Microsoft Entra ID.

• Visual Studio Code com a extensão python e o pacote Jupyter.

Configurar o acesso baseado em função

Nesta seção, você habilitará o RBAC em seu serviço do Azure AI Search e atribuirá as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para obter mais informações sobre essas etapas, consulte Conectar-se ao Azure AI Search usando funções.

Para configurar o acesso:

1. Entre no portal do Azure e selecione seu serviço de pesquisa.

2. No painel esquerdo, selecione Chaves de Configurações>.

3. Selecione Controle de Acesso Baseado em Funções (RBAC) ou Ambos se precisar de tempo para fazer a transição dos clientes para o Controle de Acesso Baseado em Funções (RBAC).

   

4. No painel esquerdo, selecione Controle de acesso (IAM).

5. Selecione Adicionar>Adicionar atribuição de função.

   

6. Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.

7. Repita a atribuição de função para o Colaborador de Dados do Índice de Pesquisa.

Obter informações de serviço

Nesta seção, você irá recuperar a ID de assinatura e o endpoint do seu serviço Azure AI Search. Se você tiver apenas uma assinatura, ignore a ID da assinatura e recupere apenas o ponto de extremidade. Você usará esses valores nas seções restantes deste início rápido.

Para obter suas informações de serviço:

1. Entre no portal do Azure e selecione seu serviço de pesquisa.

2. No painel esquerdo, selecione Visão geral.

3. Anote o ID da assinatura e o endpoint.

   

Entrar no Azure

Antes de se conectar ao seu serviço de Pesquisa de IA do Azure, use a CLI do Azure para entrar na assinatura que contém o serviço. Esta etapa estabelece sua identidade do Microsoft Entra, que DefaultAzureCredential usa para autenticar solicitações na próxima seção.

Para entrar:

1. No sistema local, abra uma ferramenta de linha de comando.

2. Verifique a assinatura e o locatário ativos no seu ambiente local.

   az account show
   

3. Se a assinatura e o locatário ativos não forem válidos para o seu serviço de pesquisa, execute os seguintes comandos para atualizar seus valores. Você pode encontrar a ID da assinatura na página visão geral do serviço de pesquisa no portal do Azure. Para encontrar a ID do locatário, selecione o nome da sua assinatura na página Visão geral e localize o valor Grupo de gerenciamento pai.

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Conectar-se ao Azure AI Search

Você pode usar notebooks Python no Visual Studio Code para enviar solicitações para seu serviço de Pesquisa de IA do Azure. Para autenticação de solicitação, use a DefaultAzureCredential classe da biblioteca de Identidade do Azure.

Para se conectar usando o Python:

1. No seu sistema local, abra o Visual Studio Code.

2. Crie um arquivo do .ipynb .

3. Crie uma célula de código para instalar as bibliotecas azure-identity e azure-search-documents.

   pip install azure-identity azure-search-documents
   

4. Crie outra célula de código para autenticar e conectar-se ao serviço de pesquisa.

   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent = 2))
   

5. Defina service_endpoint como o valor obtido em Obter informações de serviço.

6. Selecione Executar Tudo para executar ambas as células de código.

   A saída deve listar os índices existentes (se houver) em seu serviço de pesquisa, indicando uma conexão bem-sucedida.

Solucionar erros 401

Se você encontrar um erro 401, siga estas etapas de solução de problemas:

• Revise Configurar acesso baseado em função. Seu serviço de pesquisa deve ter controle de acesso baseado em funções ou ambos os controles habilitados. Políticas no nível de assinatura ou de grupo de recursos podem substituir suas atribuições de função.

• Revise Entrar no Azure. Você deve entrar na assinatura que contém o serviço de pesquisa.

• Verifique se a variável de endpoint está com aspas ao redor.

• Se tudo falhar, reinicie o dispositivo para remover tokens armazenados em cache e repita as etapas neste início rápido, começando com a entrada no Azure.

Neste início rápido, você usará o RBAC (controle de acesso baseado em função) e a ID do Microsoft Entra para estabelecer uma conexão sem chave com seu serviço do Azure AI Search. Em seguida, use REST no Visual Studio Code para interagir com seu serviço.

Conexões sem chave fornecem segurança aprimorada por meio de permissões granulares e autenticação baseada em identidade. Não recomendamos chaves de API codificadas, mas, se preferir, consulte Conectar-se ao Azure AI Search usando chaves.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Um serviço do Azure AI Search em qualquer região ou camada.

• A CLI do Azure para autenticação sem uso de chave com a Microsoft Entra ID.

• Visual Studio Code com a extensão cliente REST.

Configurar o acesso baseado em função

Nesta seção, você habilitará o RBAC em seu serviço do Azure AI Search e atribuirá as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para obter mais informações sobre essas etapas, consulte Conectar-se ao Azure AI Search usando funções.

Para configurar o acesso:

1. Entre no portal do Azure e selecione seu serviço de pesquisa.

2. No painel esquerdo, selecione Chaves de Configurações>.

3. Selecione Controle de Acesso Baseado em Funções (RBAC) ou Ambos se precisar de tempo para fazer a transição dos clientes para o Controle de Acesso Baseado em Funções (RBAC).

   

4. No painel esquerdo, selecione Controle de acesso (IAM).

5. Selecione Adicionar>Adicionar atribuição de função.

   

6. Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.

7. Repita a atribuição de função para o Colaborador de Dados do Índice de Pesquisa.

Obter informações de serviço

Nesta seção, você irá recuperar a ID de assinatura e o endpoint do seu serviço Azure AI Search. Se você tiver apenas uma assinatura, ignore a ID da assinatura e recupere apenas o ponto de extremidade. Você usará esses valores nas seções restantes deste início rápido.

Para obter suas informações de serviço:

1. Entre no portal do Azure e selecione seu serviço de pesquisa.

2. No painel esquerdo, selecione Visão geral.

3. Anote o ID da assinatura e o endpoint.

   

Entrar no Azure

Antes de se conectar ao seu serviço de Pesquisa de IA do Azure, use a CLI do Azure para entrar na assinatura que contém o serviço.

Para entrar:

1. No sistema local, abra uma ferramenta de linha de comando.

2. Verifique a assinatura e o locatário ativos no seu ambiente local.

   az account show
   

3. Se a assinatura e o locatário ativos não forem válidos para o seu serviço de pesquisa, execute os seguintes comandos para atualizar seus valores. Você pode encontrar a ID da assinatura na página visão geral do serviço de pesquisa no portal do Azure. Para encontrar a ID do locatário, selecione o nome da sua assinatura na página Visão geral e localize o valor Grupo de gerenciamento pai.

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Obter o token

As chamadas à API REST exigem a inclusão de um token de ID do Microsoft Entra. Use esse token para autenticar solicitações na próxima seção.

Para obter seu token:

1. Usando a mesma ferramenta de linha de comando, gere um token de acesso.

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

2. Anote a saída do token.

Conectar-se ao Azure AI Search

Você pode usar a extensão cliente REST no Visual Studio Code para enviar solicitações para o serviço do Azure AI Search. Para autenticação de solicitação, inclua um cabeçalho Authorization com o token do Microsoft Entra ID gerado anteriormente.

Para se conectar usando REST:

1. No seu sistema local, abra o Visual Studio Code.

2. Criar um arquivo em .rest ou .http.

3. Cole as variáveis e a requisição a seguir no arquivo.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. Defina @baseUrl como o valor obtido em Obter informações de serviço.

5. Defina @token como o valor obtido no token Get.

6. Em , ### List existing indexesselecione Enviar Solicitação.

   Você deve receber uma HTTP/1.1 200 OK resposta, indicando uma conexão bem-sucedida com seu serviço de pesquisa.

Solucionar erros 401

Se você encontrar um erro 401, siga estas etapas de solução de problemas:

• Revise Configurar acesso baseado em função. Seu serviço de pesquisa deve ter controle de acesso baseado em funções ou ambos os controles habilitados. As políticas no nível de subscrição ou grupo de recursos podem suplantar suas atribuições de função.

• Revise Entrar no Azure. Você deve entrar na assinatura que contém o serviço de pesquisa.

• Verifique se as variáveis de endpoint e token não têm aspas ou espaços extras em volta.

• Verifique se o token não tem o @ símbolo no cabeçalho da solicitação. Por exemplo, se a variável for @token, a referência na solicitação deverá ser {{token}}.

• Se tudo falhar, reinicie o dispositivo para remover tokens armazenados em cache e repita as etapas neste início rápido, começando com a entrada no Azure.