Início Rápido: Pesquisa de texto 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. Para obter mais informações, consulte Baixando 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.

Copiar uma chave de serviço de pesquisa e uma URL

As chamadas REST exigem o ponto de extremidade do serviço de pesquisa e uma chave de API em cada solicitação. Você pode obter esses valores no portal do Azure.

  1. Entre no portal do Azure. Em seguida, vá para a página Visão geral do serviço de pesquisa e copie a URL. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.

  2. 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.

    Captura de tela mostrado a URL e as chaves de API no portal do Microsoft Azure.

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. Substitua a URL base e a chave de API pelos valores copiados anteriormente.

    @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=2023-11-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. 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.

    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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Secret Point Motel",
        "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": "Twin Dome Motel",
        "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": "Triple 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 Cliff Hotel",
        "Description": "Sublime Cliff 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 Cliff 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=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "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 Cliff Hotel",
      "Description": "Sublime Cliff 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 Cliff 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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

  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. Você pode 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 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=2023-11-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