Guia de início rápido: pesquisa por palavra-chave 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. As instruções podem ser encontradas em Download de 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.

Obter um ponto de extremidade de serviço de pesquisa

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

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

  2. Na página inicial Visão geral , localize o URL. Um ponto final de exemplo poderá ser parecido com https://mydemo.search.windows.net.

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

Você está colando esse ponto de extremidade no .rest arquivo ou .http em uma etapa posterior.

Configurar o acesso

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

Para uma conexão baseada em função, as instruções a seguir fazem com que você se conecte ao Azure AI Search sob sua identidade, não a identidade de um aplicativo cliente.

Opção 1: Usar teclas

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. Para obter mais informações, consulte Conectar-se ao Azure AI Search usando autenticação de chave.

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

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

Opção 2: Usar funções

Verifique se o serviço de pesquisa está configurado para acesso baseado em função. Você deve ter atribuições de função pré-configuradas para acesso de desenvolvedor. Suas atribuições de função devem 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. Iniciar sessão na CLI do Azure.

    az login

  2. Obtenha o seu token de identidade pessoal.

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

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

Nota

Esta seção pressupõe que você esteja usando um cliente local que se conecta ao Azure AI Search 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 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 se estiver usando chaves de API. Substitua os @baseUrl espaços reservados e @apiKey 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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

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

    @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 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=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 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=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 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=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. 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 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

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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  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=2024-07-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