Guia de início rápido: pesquisa de texto usando REST

  • Artigo

As APIs REST no Azure AI Search fornecem acesso programático a todos os seus recursos, incluindo recursos de visualização, 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 no Azure AI Search.

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

Pré-requisitos

Transferir ficheiros

Baixe um exemplo REST do GitHub para enviar as solicitações neste 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 neste artigo.

Copiar uma chave de serviço de pesquisa e 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. Inicie sessão no portal do Azure. Em seguida, vá para a página Visão geral do serviço de pesquisa e copie o URL. Um ponto final de exemplo poderá ser parecido com https://mydemo.search.windows.net.

  2. Selecione Configurações>Chaves e copie uma chave de administrador. As chaves de administrador são usadas para adicionar, modificar e excluir objetos. Existem duas chaves de administração intercambiáveis. Copie qualquer uma delas.

    Captura de ecrã que mostra o URL e as chaves de API no portal do Azure.

Configurar o Visual Studio Code

Se você não estiver familiarizado com o cliente REST para Visual Studio Code, esta seção inclui 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. Procure o cliente REST e selecione Instalar.

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

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

  4. Cole no exemplo a seguir. Substitua a URL base e a chave da 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 pedido. 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ê está 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 do pedido.

Criar um índice

Adicione um segundo pedido ao seu .rest ficheiro. Criar índice (REST) cria um índice de pesquisa e configura as estruturas de dados físicos no seu serviço de pesquisa.

  1. Cole no exemplo a seguir para criar o hotels-quickstart índice 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 pedido. Você deve ter uma HTTP/1.1 201 Created resposta e o corpo da resposta deve incluir a representação JSON do esquema de índice.

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

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

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

Sobre a definição do índice

Dentro do esquema de índice, a coleção fields define a estrutura do documento. Cada documento carregado deve ter estes campos. Cada campo deve ser atribuído a um tipo de dados EDM (Entity Data Model). Os campos de cadeia de caracteres são usados na pesquisa de texto completo. Se pretender que os dados numéricos possam ser pesquisados, certifique-se de que o tipo de dados é Edm.String. Outros tipos de dados, como Edm.Int32 são filtráveis, classificáveis, compatí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, você só pode ter 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}
        ]
     }
  ]
}

Carregar documentos

Criar e carregar o índice são etapas separadas. No Azure AI Search, o índice contém todos os dados pesquisáveis e consultas executadas no serviço de pesquisa. Para chamadas REST, os dados são fornecidos como documentos JSON. Use Documents- Index REST API para esta tarefa.

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

  1. Cole no 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 pedido. Em alguns segundos, você verá uma resposta HTTP 201 no painel adjacente.

    Se obtiver um 207, pelo menos um documento falhou ao carregar. Se obtiver um 404, tem um erro de sintaxe no cabeçalho ou no corpo do pedido. Verifique se você alterou o ponto de extremidade para incluir /docs/index.

Executar consultas

Agora que os documentos estão carregados, você pode emitir consultas contra eles usando Documents - Search Post (REST).

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

  1. Cole no 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 search parâmetro. 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. Analise a resposta no painel adjacente. Você deve ter uma contagem que indique o número de correspondências encontradas no índice, uma pontuação de pesquisa que indique relevância e valores para cada campo listado select na instrução.

    {
  "@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

Você também pode usar Obter Estatísticas para consultar contagens de documentos e tamanho do índice.

  1. Cole no 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. Veja a resposta. Esta 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
}

Clean up resources (Limpar recursos)

Ao trabalhar na sua própria subscrição, recomendamos que verifique, depois de concluir um projeto, se ainda vai precisar dos recursos que criou. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal usando o link Todos os recursos ou Grupos de recursos no painel mais à esquerda.

Você também pode tentar este DELETE comando:

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

Próximo passo

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

Guia de início rápido: pesquisa vetorial usando REST