Compartilhar via

Início Rápido: Pesquisa de palavras-chave usando REST

  • Artigo

As APIs REST na Pesquisa de IA do Azure fornecem acesso programático a todos os seus recursos, incluindo recursos de versão prévia, e são uma maneira fácil de aprender como os recursos funcionam. Neste início rápido, saiba como chamar as APIs REST de Pesquisa para criar, carregar e consultar um índice de pesquisa na Pesquisa de IA do Azure.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Baixar arquivos

Baixe uma amostra REST do GitHub para enviar as solicitações nesse início rápido. As instruções podem ser encontradas em Baixar arquivos do GitHub.

Você também pode iniciar um novo arquivo em seu sistema local e criar solicitações manualmente usando as instruções nesse artigo.

Obter um ponto de extremidade do serviço de pesquisa

Você pode encontrar o ponto de extremidade de serviço de pesquisa no portal do Azure.

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

  2. Na página inicial Visão Geral, encontre a URL. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.

    Captura de tela de propriedades de URL na página de visão geral.

Você vai colar esse ponto de extremidade no arquivo .rest ou .http em uma etapa posterior.

Configurar o acesso

As solicitações para o ponto de extremidade de pesquisa precisam ser autenticadas e autorizadas. Você pode usar funções ou chaves de API para essa tarefa. É mais fácil usar as chaves para começar, mas as funções são mais seguras.

Para uma conexão baseada em função, as instruções a seguir solicitam que você se conecte à Pesquisa de IA do Azure na sua identidade, não na identidade de um aplicativo de cliente.

Opção 1: Usar chaves

Selecione Configurações>Chaves e copie uma chave de administração. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Há duas chaves de administrador intercambiáveis. Copie uma delas. Para obter mais informações, confira Conectar-se à Pesquisa de IA do Azure usando a autenticação por chave.

Captura de tela mostrando as chaves de API no portal do Azure.

Você estará colando essa chave no arquivo .rest ou .http em uma etapa posterior.

Opção 2: Usar funções

Certifique-se de que o serviço de pesquisa esteja configurado para o acesso baseado em função. Você precisa ter atribuições de função para o acesso de desenvolvedor pré-configuradas. Suas atribuições de função precisam conceder permissão para criar, carregar e consultar um índice de pesquisa.

Nesta seção, obtenha seu token de identidade pessoal usando a CLI do Azure, o Azure PowerShell ou o portal do Azure.

  1. Entrar na CLI do Azure.

    az login

  2. Obtenha seu token de identidade pessoal.

    az account get-access-token --scope https://search.azure.com/.default

Você estará colando seu token de identidade pessoal no arquivo .rest ou .http em uma etapa posterior.

Observação

Esta seção pressupõe que você esteja usando um cliente local que se conecta à Pesquisa de IA do Azure em seu nome. Uma abordagem alternativa é obter um token para o aplicativo cliente, supondo que seu aplicativo esteja registrado com o Microsoft Entra ID.

Configurar o Visual Studio Code

Se você não estiver familiarizado com o cliente REST para Visual Studio Code, esta seção incluirá a instalação para que você possa concluir as tarefas neste início rápido.

  1. Inicie o Visual Studio Code e selecione o bloco Extensões.

  2. Pesquise o cliente REST e selecione Instalar.

    Captura de tela que mostra o botão Instalar cliente REST.

  3. Abra ou crie um novo arquivo nomeado com uma extensão de arquivo .rest ou .http.

  4. Cole o exemplo a seguir se estiver usando chaves de API. Substitua os espaços reservados @baseUrl e @apiKey pelos valores copiados anteriormente, sem aspas.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. Ou cole este exemplo se estiver usando funções. Substitua os espaços reservados @baseUrl e @token pelos valores copiados anteriormente, sem aspas.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  6. Selecione Enviar solicitação. Uma resposta deve aparecer em um painel adjacente. Se você tiver índices existentes, eles serão listados. Caso contrário, a lista estará vazia. Se o código HTTP for 200 OK, você estará pronto para as próximas etapas.

    Captura de tela que mostra um cliente REST configurado para uma solicitação de serviço de pesquisa.

    Se você receber WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation.", remova as aspas ao redor do token, salve o arquivo e repita sua solicitação.

    Pontos principais:

    • Os parâmetros são especificados usando um prefixo @.
    • ### designa uma chamada REST. A próxima linha contém a solicitação, que deve incluir HTTP/1.1.
    • Send request deve aparecer acima da solicitação.

Crie um índice

Adicione uma segunda solicitação ao arquivo .rest. Criar índice (REST) cria um índice de pesquisa e configura as estruturas de dados físicos em seu serviço de pesquisa.

  1. Cole o exemplo a seguir para criar o índice hotels-quickstart em seu serviço de pesquisa.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "name": "hotels-quickstart",  
        "fields": [
            {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
            {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
            {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
            {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
            {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
            {"name": "Address", "type": "Edm.ComplexType", 
                "fields": [
                {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
                {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
                {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
                ]
            }
        ]
    }

  2. Selecione Enviar solicitação. Você deve ter uma resposta HTTP/1.1 201 Created e o corpo da resposta deve incluir a representação JSON do esquema de índice.

    Se você receber um erro Header name must be a valid HTTP token ["{"], verifique se há uma linha vazia entre api-key e o corpo da solicitação e o corpo. Se obtiver o HTTP 504, verifique se a URL especifica HTTPS. Caso veja HTTP 400 ou 404, confira o corpo da solicitação para verificar se não houve erros ao copiar e colar. Um HTTP 403 normalmente indica um problema com a chave de API. Ela é uma chave inválida ou há um problema de sintaxe com a forma como a chave de API é especificada.

    Agora você tem várias solicitações no arquivo. Lembre-se de que ### inicia uma nova solicitação e cada solicitação é executada de maneira independente.

    Captura de tela que mostra o cliente REST com várias solicitações.

Sobre a definição de índice

Dentro do esquema de índice, a coleção de campos define a estrutura do documento. Cada documento carregado precisa ter esses campos. Cada campo precisa ser atribuído a um tipo de dados EDM (Modelo de Dados de Entidade). Os campos de cadeia de caracteres são usados na pesquisa de texto completo. Se você quiser que os dados numéricos sejam pesquisáveis, verifique se o tipo de dados é Edm.String. Outros tipos de dados, como Edm.Int32, são filtres, classificáveis, facetáveis e recuperáveis, mas não pesquisáveis em texto completo.

Os atributos no campo determinam as ações permitidas. As APIs REST permitem muitas ações por padrão. Por exemplo, todas as cadeias de caracteres são pesquisáveis e recuperáveis por padrão. Para APIs REST, talvez você só precise de atributos se precisar desativar um comportamento.

{
    "name": "hotels-quickstart",  
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
        {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
        {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
        {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Address", "type": "Edm.ComplexType", 
        "fields": [
        {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
        {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
        ]
     }
  ]
}

Carregue os documentos

Criar e carregar o índice são etapas separadas. Na Pesquisa de IA do Azure, o índice contém todos os dados pesquisáveis e as consultas executadas no serviço de pesquisa. Para chamadas REST, os dados são fornecidos como documentos JSON. Use Documentos - Índice REST API para esta tarefa.

O URI é estendido para incluir as coleções docs e a operação index.

  1. Cole o exemplo a seguir para carregar documentos JSON no índice de pesquisa.

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
        "Category": "Boutique",
        "Tags": [ "pool", "air conditioning", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1970-01-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "677 5th Ave",
            "City": "New York",
            "StateProvince": "NY",
            "PostalCode": "10022",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "2",
        "HotelName": "Old Century Hotel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1979-02-18T00:00:00Z",
        "Rating": 3.60,
        "Address": 
            {
            "StreetAddress": "140 University Town Center Dr",
            "City": "Sarasota",
            "StateProvince": "FL",
            "PostalCode": "34243",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "3",
        "HotelName": "Gastronomic Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa",
        "Tags": [ "air conditioning", "bar", "continental breakfast" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "2015-09-20T00:00:00Z",
        "Rating": 4.80,
        "Address": 
            {
            "StreetAddress": "3393 Peachtree Rd",
            "City": "Atlanta",
            "StateProvince": "GA",
            "PostalCode": "30326",
            "Country": "USA"
            } 
        },
        {
        "@search.action": "upload",
        "HotelId": "4",
        "HotelName": "Sublime Palace Hotel",
        "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
        "Category": "Boutique",
        "Tags": [ "concierge", "view", "24-hour front desk service" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "1960-02-06T00:00:00Z",
        "Rating": 4.60,
        "Address": 
            {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216",
            "Country": "USA"
            }
        }
      ]
    }

  2. Selecione Enviar solicitação. Em alguns segundos, você deverá ver uma resposta HTTP 201 no painel adjacente.

    Se você obtiver um 207, houve falha no carregamento de pelo menos um documento. Se você obtiver um 404, há um erro de sintaxe no cabeçalho ou no corpo da solicitação. Verifique se você alterou o ponto de extremidade para incluir /docs/index.

Executar consultas

Agora que os documentos são carregados, você pode emitir consultas com eles usando Documentos – Postagem de Pesquisa (REST).

O URI é estendido para incluir uma expressão de consulta, especificada usando o operador /docs/search.

  1. Cole o exemplo a seguir para consultar o índice de pesquisa. Em seguida, selecione Enviar solicitação. Uma solicitação de pesquisa de texto sempre inclui um parâmetro search. Este exemplo inclui um parâmetro opcional searchFields que restringe a pesquisa de texto a campos específicos.

    ### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "search": "lake view",
      "select": "HotelId, HotelName, Tags, Description",
      "searchFields": "Description, Tags",
      "count": true
  }

  2. Examine a resposta no painel adjacente. Você deve ter uma contagem que indica o número de correspondências encontradas no índice, uma pontuação de pesquisa indicando relevância e valores para cada campo listado na instrução select.

    {
  "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.6189728,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.",
      "Tags": [
        "concierge",
        "view",
        "24-hour front desk service"
      ]
    }
  ]
}

Obter propriedades de índice

Use também Obter Estatísticas para consultar as contagens dos documentos e o tamanho do índice.

  1. Cole o exemplo a seguir para consultar o índice de pesquisa. Em seguida, selecione Enviar solicitação.

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  2. Revise a resposta. Essa operação é uma maneira fácil de obter detalhes sobre o armazenamento de índice.

    {
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, é uma boa ideia identificar, no final de um projeto, se você ainda precisa dos recursos criados. Recursos deixados em execução podem custar dinheiro. É possível excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no portal do Azure usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

Você também pode experimentar este comando DELETE:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Próxima etapa

Agora que você está familiarizado com o cliente REST e fazendo chamadas REST para a Pesquisa de IA do Azure, tente outro início rápido que demonstre suporte a vetores.

Início Rápido: busca em vetores usando REST