Partilhar via


Guia de início rápido: conectar-se a um serviço de pesquisa

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

As 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 à Pesquisa de IA do Azure usando chaves.

Pré-requisitos

Configurar acesso baseado em função

Nesta seção, você habilita o RBAC em seu serviço Azure AI Search e atribui as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para obter mais informações sobre essas etapas, consulte Conectar-se à Pesquisa de IA do Azure 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 Teclas de configurações>.

  3. Selecione Controle de acesso baseado em função ou Ambos se precisar de tempo para fazer a transição de clientes para o RBAC.

    Captura de ecrã das opções de controlo de acesso no portal do Azure.

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

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

    Captura de ecrã do menu suspenso para adicionar uma atribuição de função no portal do Azure.

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

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

Obter informações de serviço

Nesta seção, você recupera a ID de subscrição e o ponto de extremidade do seu serviço Azure AI Search. Se tiver apenas uma subscrição, ignore o ID da subscrição e recupere apenas o endpoint. Utilize estes valores nas secções restantes deste guia de início rápido.

Para obter as informações do seu 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 de subscrição e o endpoint.

    Captura de ecrã do ID da subscrição e do ponto de extremidade no portal do Azure.

Iniciar sessão no Azure

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

Para iniciar sessão:

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

  2. Inicie sessão no Azure. Se tiver várias subscrições, selecione aquela cujo ID obteve em Obter informações de serviço.

    az login
    

Observação

Esta seção ilustra o padrão Python básico para conexões sem chave. Para obter orientações abrangentes, consulte um guia de início rápido ou tutorial específico, como Guia de início rápido: executar recuperação agentic no Azure AI Search.

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

Para se conectar usando Python:

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

  2. Crie um ficheiro .ipynb.

  3. Crie uma célula de código para instalar as azure-identity bibliotecas 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 seu 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 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) no seu serviço de pesquisa, indicando uma conexão bem-sucedida.

Solucionar problemas de erros 401

Se encontrar um erro 401, siga estes passos de resolução de problemas:

  • Revisite Configurar acesso baseado em função. Seu serviço de pesquisa deve ter o controle de acesso baseado em função ou ambos habilitados. As políticas a nível de subscrição ou do grupo de recursos também podem substituir suas atribuições de funções.

  • Volte a Entrar no Azure. Tem de iniciar sessão na subscrição que contém o seu serviço de pesquisa.

  • Certifique-se de que a sua variável de ponto de extremidade tenha 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 Entrar no Azure.

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

As 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 à Pesquisa de IA do Azure usando chaves.

Pré-requisitos

Configurar acesso baseado em função

Nesta seção, você habilita o RBAC em seu serviço Azure AI Search e atribui as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para obter mais informações sobre essas etapas, consulte Conectar-se à Pesquisa de IA do Azure 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 Teclas de configurações>.

  3. Selecione Controle de acesso baseado em função ou Ambos se precisar de tempo para fazer a transição de clientes para o RBAC.

    Captura de ecrã das opções de controlo de acesso no portal do Azure.

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

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

    Captura de ecrã do menu suspenso para adicionar uma atribuição de função no portal do Azure.

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

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

Obter informações de serviço

Nesta seção, você recupera a ID de subscrição e o ponto de extremidade do seu serviço Azure AI Search. Se tiver apenas uma subscrição, ignore o ID da subscrição e recupere apenas o endpoint. Utilize estes valores nas secções restantes deste guia de início rápido.

Para obter as informações do seu 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 de subscrição e o endpoint.

    Captura de ecrã do ID da subscrição e do ponto de extremidade no portal do Azure.

Obter token

Antes de se conectar ao seu serviço Azure AI Search, use a CLI do Azure para entrar na assinatura que contém seu serviço e gerar um token de ID do Microsoft Entra. Você usa esse token para autenticar solicitações na próxima seção.

Para obter o seu token:

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

  2. Inicie sessão no Azure. Se tiver várias subscrições, selecione aquela cujo ID obteve em Obter informações de serviço.

    az login
    
  3. Gere um token de acesso.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    
  4. Anote a saída do token.

Observação

Esta seção ilustra o padrão REST básico para conexões sem chave. Para obter orientações abrangentes, consulte um guia de início rápido ou tutorial específico, como Guia de início rápido: executar recuperação agentic no Azure AI Search.

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

Para se conectar usando REST:

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

  2. Crie um .rest ou .http arquivo.

  3. Cole os seguintes espaços reservados e solicite no arquivo.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
    @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
    
    ### List existing indexes
    GET {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
       Content-Type: application/json
       Authorization: Bearer {{token}}
    
  4. Substitua @baseUrl pelo valor obtido em Obter informações de serviço.

  5. Substitua @token pelo valor obtido em Obter token.

  6. Em ### List existing indexes, selecione Enviar solicitação.

    Deverá receber uma HTTP/1.1 200 OK resposta, indicando uma ligação bem-sucedida ao seu serviço de pesquisa.

Solucionar problemas de erros 401

Se encontrar um erro 401, siga estes passos de resolução de problemas:

  • Revisite Configurar acesso baseado em função. Seu serviço de pesquisa deve ter o controle de acesso baseado em função ou ambos habilitados. As políticas a nível de subscrição ou do grupo de recursos também podem substituir suas atribuições de funções.

  • Revisite Obter token. Tem de iniciar sessão na subscrição que contém o seu serviço de pesquisa.

  • Certifique-se de que as suas variáveis de ponto de extremidade e de token não tenham aspas ao redor nem espaços extra.

  • 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 deve ser {{token}}.

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