Início Rápido: Explorar as APIs REST do Azure Search usando o PostmanQuickstart: Explore Azure Search REST APIs using Postman

Uma das maneiras mais fáceis de explorar as APIs REST do Azure Search é usar o Postman ou outra ferramenta de teste da Web para formular solicitações HTTP e inspecionar as respostas.One of the easiest ways to explore the Azure Search REST APIs is using Postman or another web testing tool to formulate HTTP requests and inspect the responses. Com as ferramentas certas e essas instruções, você pode enviar pedidos e exibir respostas antes de escrever qualquer código.With the right tools and these instructions, you can send requests and view responses before writing any code.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar e, em seguida, inscreva-se no Azure Search.If you don't have an Azure subscription, create a free account before you begin and then sign up for Azure Search.

Pré-requisitosPrerequisites

Os serviços e as ferramentas a seguir são usados neste Início Rápido.The following services and tools are used in this quickstart.

Obter uma chave e uma URLGet a key and URL

As chamadas REST exigem a URL do serviço e uma chave de acesso em cada solicitação.REST calls require the service URL and an access key on every request. Um serviço de pesquisa é criado com ambos, portanto, se você adicionou o Azure Search à sua assinatura, siga estas etapas para obter as informações necessárias:A search service is created with both, so if you added Azure Search to your subscription, follow these steps to get the necessary information:

  1. Entre no portal do Azure e, na página Visão Geral do serviço de pesquisa, obtenha a URL.Sign in to the Azure portal, and in your search service Overview page, get the URL. Um ponto de extremidade de exemplo pode parecer com https://mydemo.search.windows.net.An example endpoint might look like https://mydemo.search.windows.net.

  2. Em Configurações > Chaves, obtenha uma chave de administração para adquirir todos os direitos sobre o serviço.In Settings > Keys, get an admin key for full rights on the service. Há duas chaves de administração intercambiáveis, fornecidas para a continuidade dos negócios, caso seja necessário sobrepor uma.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. É possível usar a chave primária ou secundária em solicitações para adicionar, modificar e excluir objetos.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

Obter um ponto de extremidade HTTP e uma chave de acessoGet an HTTP endpoint and access key

Todas as solicitações requerem uma chave de api em cada pedido enviado ao serviço.All requests require an api-key on every request sent to your service. Ter uma chave válida estabelece a relação de confiança, para cada solicitação, entre o aplicativo que envia a solicitação e o serviço que lida com ela.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

Nesta seção, use a sua ferramenta de escolha da web para configurar as conexões para o Azure Search.In this section, use your web tool of choice to set up connections to Azure Search. Cada ferramenta mantém as informações do cabeçalho de solicitação para a sessão, o que significa que você só precisa inserir a chave da API e o tipo de conteúdo uma vez.Each tool persists request header information for the session, which means you only have to enter the api-key and Content-Type once.

Para qualquer uma dessas ferramentas, você precisa escolher um comando (GET, POST, PUT e assim por diante) fornecer um ponto de extremidade de URL e para algumas tarefas, fornecer o JSON no corpo da solicitação.For either tool, you need to choose a command (GET, POST, PUT, and so forth), provide a URL endpoint, and for some tasks, provide JSON in the body of the request. Substitua o nome do serviço de pesquisa (YOUR-SEARCH-SERVICE-NAME) por um valor válido.Replace the search service name (YOUR-SEARCH-SERVICE-NAME) with a valid value.

https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2019-05-06

Observe o prefixo HTTPS, o nome do serviço, o nome de um objeto (nesse caso, a coleção de índices) e a versão da API.Notice the HTTPS prefix, the name of the service, the name of an object (in this case, the indexes collection), and the api-version. A versão da API é uma cadeia de caracteres em minúsculas obrigatória especificada como ?api-version=2019-05-06 para a versão atual.The api-version is a required, lowercase string specified as ?api-version=2019-05-06 for the current version. As versões de API são atualizadas regularmente.API versions are updated regularly. Incluir a versão de API em cada solicitação lhe dá controle total sobre qual é usada.Including the api-version on each request gives you full control over which one is used.

A composição de cabeçalho de solicitação inclui dois elementos, o tipo de conteúdo e a chave de API usada para autenticar a Azure Search.Request header composition includes two elements, content type, plus the api-key used to authenticate to Azure Search. Substitua a chave de API de administração (YOUR-ADMIN-API-KEY) por um valor válido.Replace the admin API key (YOUR-ADMIN-API-KEY) with a valid value.

api-key: <YOUR-ADMIN-API-KEY>
Content-Type: application/json

No Postman, formule uma solicitação semelhante à captura de tela a seguir.In Postman, formulate a request that looks like the following screenshot. Escolha GET como o verbo, forneça a URL e clique em Enviar.Choose GET as the verb, provide the URL, and click Send. Esse comando conecta ao Azure Search, lê a coleção de índices e retorna o código de status HTTP 200 em uma conexão bem-sucedida.This command connects to Azure Search, reads the indexes collection, and returns HTTP status code 200 on a successful connection. Se o serviço já tiver índices, a resposta também incluirá as definições de índice.If your service has indexes already, the response will also include index definitions.

Cabeçalho da solicitação do Postman

1 - Criar um índice1 - Create an index

No Azure Search, você normalmente cria o índice antes de carregá-lo com dados.In Azure Search, you usually create the index before loading it with data. A API REST Criar Índice é usada para essa tarefa.The Create Index REST API is used for this task.

A URL é estendida para incluir o nome do índice hotels.The URL is extended to include the hotels index name.

Para fazer isso no Postman:To do this in Postman:

  1. Altere o verbo para PUT.Change the verb to PUT.

  2. Copie nesta URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels?api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels?api-version=2019-05-06.

  3. Indique a definição de índice (mostrada abaixo) no corpo da solicitação.Provide the index definition (shown below) in the body of the request.

  4. Clique em Enviar.Click Send.

Corpo da solicitação do Postman

Definição do índiceIndex definition

A coleção de campos define a estrutura do documento.The fields collection defines document structure. Cada documento deve ter esses campos, e cada campo deve ter um tipo de dados.Each document must have these fields, and each field must have a data type. Os campos de cadeia de caracteres são usados na pesquisa de texto completo, portanto, talvez você queira converter dados numéricos como cadeias de caracteres, se você precisa que esse conteúdo seja pesquisável.String fields are used in full text search, so you might want to cast numeric data as strings if you need that content to be searchable.

Os atributos no campo determinam a ação repetida.Attributes on the field determine allowed action. As APIs REST permitem muitas ações por padrão.The REST APIs allow many actions by default. Por exemplo, todas as cadeias de caracteres são pesquisáveis, recuperáveis, podem ser filtradas e podem possuir faceta por padrão.For example, all strings are searchable, retrievable, filterable, and facetable by default. Geralmente, você só precisa definir atributos quando você precisa desabilitar um comportamento.Often, you only have to set attributes when you need to turn off a behavior.

      {
     "name": "hotels",  
     "fields": [
       {"name": "hotelId", "type": "Edm.String", "key":true, "searchable": false},
       {"name": "baseRate", "type": "Edm.Double"},
       {"name": "description", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false},
       {"name": "description_fr", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene"},
       {"name": "hotelName", "type": "Edm.String"},
       {"name": "category", "type": "Edm.String"},
       {"name": "tags", "type": "Collection(Edm.String)"},
       {"name": "parkingIncluded", "type": "Edm.Boolean"},
       {"name": "smokingAllowed", "type": "Edm.Boolean"},
       {"name": "lastRenovationDate", "type": "Edm.DateTimeOffset"},
       {"name": "rating", "type": "Edm.Int32"},
       {"name": "location", "type": "Edm.GeographyPoint"}
      ]
     }

Quando você enviar esta solicitação, você deve obter uma resposta HTTP 201, indicando que o índice foi criado com sucesso.When you submit this request, you should get an HTTP 201 response, indicating the index was created successfully. Você pode verificar essa ação no portal, mas observe que a página do portal possui intervalos de atualização, portanto, pode levar um minuto ou dois para que ela seja atualizada.You can verify this action in the portal, but note that the portal page has refresh intervals so it could take a minute or two to catch up.

Dica

Se obtiver o HTTP 504, veja 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 (uma chave inválida ou um problema de sintaxe com o modo que a chave de API está especificada).

2 - Carregar documentos2 - Load documents

Criar o índice e popular o índice são etapas separadas.Creating the index and populating the index are separate steps. No Azure Search, o índice contém todos os dados pesquisáveis, os quais você pode fornecer como documentos JSON.In Azure Search, the index contains all searchable data, which you can provide as JSON documents. A API REST Adicionar, Atualizar ou Excluir Documentos é usada para essa tarefa.The Add, Update, or Delete Documents REST API is used for this task.

A URL é estendida para incluir as coleções docs e a operação index.The URL is extended to include the docs collections and index operation.

Para fazer isso no Postman:To do this in Postman:

  1. Altere o verbo para POST.Change the verb to POST.

  2. Copie nesta URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/docs/index?api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/docs/index?api-version=2019-05-06.

  3. Indique os documentos JSON (mostrados abaixo) no corpo da solicitação.Provide the JSON documents (shown below) in the body of the request.

  4. Clique em Enviar.Click Send.

Conteúdo da solicitação do Postman

Documentos JSON para carregar em um índiceJSON documents to load into the index

O Corpo da solicitação contém quatro documentos a serem adicionados ao índice de hotéis.The Request Body contains four documents to be added to the hotels index.

     {
     "value": [
     {
         "@search.action": "upload",
         "hotelId": "1",
         "baseRate": 199.0,
         "description": "Best hotel in town",
         "description_fr": "Meilleur hôtel en ville",
         "hotelName": "Fancy Stay",
         "category": "Luxury",
         "tags": ["pool", "view", "wifi", "concierge"],
         "parkingIncluded": false,
         "smokingAllowed": false,
         "lastRenovationDate": "2010-06-27T00:00:00Z",
         "rating": 5,
         "location": { "type": "Point", "coordinates": [-122.131577, 47.678581] }
       },
       {
         "@search.action": "upload",
         "hotelId": "2",
         "baseRate": 79.99,
         "description": "Cheapest hotel in town",
         "description_fr": "Hôtel le moins cher en ville",
         "hotelName": "Roach Motel",
         "category": "Budget",
         "tags": ["motel", "budget"],
         "parkingIncluded": true,
         "smokingAllowed": true,
         "lastRenovationDate": "1982-04-28T00:00:00Z",
         "rating": 1,
         "location": { "type": "Point", "coordinates": [-122.131577, 49.678581] }
       },
       {
         "@search.action": "upload",
         "hotelId": "3",
         "baseRate": 279.99,
         "description": "Surprisingly expensive",
         "hotelName": "Dew Drop Inn",
         "category": "Bed and Breakfast",
         "tags": ["charming", "quaint"],
         "parkingIncluded": true,
         "smokingAllowed": false,
         "lastRenovationDate": null,
         "rating": 4,
         "location": { "type": "Point", "coordinates": [-122.33207, 47.60621] }
       },
       {
         "@search.action": "upload",
         "hotelId": "4",
         "baseRate": 220.00,
         "description": "This could be the one",
         "hotelName": "A Hotel for Everyone",
         "category": "Basic hotel",
         "tags": ["pool", "wifi"],
         "parkingIncluded": true,
         "smokingAllowed": false,
         "lastRenovationDate": null,
         "rating": 4,
         "location": { "type": "Point", "coordinates": [-122.12151, 47.67399] }
       }
      ]
     }

Em alguns segundos, você verá uma resposta HTTP 200 na lista de sessões.In a few seconds, you should see an HTTP 200 response in the session list. Isso indica que os documentos foram criados com êxito.This indicates the documents were created successfully.

Se você obtiver um 207, houve falha no carregamento de pelo menos um documento.If you get a 207, at least one document failed to upload. 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.If you get a 404, you have a syntax error in either the header or body of the request: verify you changed the endpoint to include /docs/index.

Dica

Para fontes de dados selecionadas, você pode escolher a abordagem alternativa do indexador que simplifica e reduz a quantidade de código necessária para indexação. Para obter mais informações, confira Operações do indexador.

3 - Pesquisar um índice3 - Search an index

Como um índice e documentos foram carregados, agora é possível emitir consultas usando a API REST Pesquisar Documentos.Now that an index and documents are loaded, you can issue queries against them using Search Documents REST API.

A URL é estendida para incluir uma cadeia de caracteres de consulta, especificada usando o operador de pesquisa.The URL is extended to include a query string, specified using the search operator.

Para fazer isso no Postman:To do this in Postman:

  1. Altere o verbo para GET.Change the verb to GET.

  2. Copie nesta URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/docs?search=motel&$count=true&api-version=2019-05-06.

  3. Clique em Enviar.Click Send.

Essa consulta pesquisa o termo "hotel" e retorna uma contagem dos documentos nos resultados da pesquisa.This query searches on the term "motel" and returns a count of the documents in the search results. A solicitação e resposta devem ser semelhantes à captura de tela a seguir para Postman depois de clicar em Enviar.The request and response should look similar to the following screenshot for Postman after you click Send. O código de status deve ser 200.The status code should be 200.

Resposta da consulta do Postman

Obter propriedades de índiceGet index properties

Você também pode consultar as informações do sistema para obter contagens de documentos e consumo de armazenamento: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/stats?api-version=2019-05-06You can also query system information to get document counts and storage consumption: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels/stats?api-version=2019-05-06

No Postman, sua solicitação deve ser semelhante à seguinte, e a resposta inclui uma contagem de documentos e o espaço usado em bytes.In Postman, your request should look similar to the following, and the response includes a document count and space used in bytes.

Consulta do sistema Postman

Observe que a sintaxe de versão da API é diferente.Notice that the api-version syntax differs. Para esta solicitação, use ? para anexar a versão da API.For this request, use ? to append the api-version. ? separa o caminho da URL da cadeia de cadeia de consulta, enquanto & separa cada par 'nome=valor' na cadeia de consulta.The ? separates the URL path from the query string, while & separates each 'name=value' pair in the query string. Para essa consulta, a versão da API é o primeiro e único item na cadeia de consulta.For this query, api-version is the first and only item in the query string.

Para saber mais sobre esta API, confira API REST Obter Estatísticas do Índice.For more information about this API, see Get Index Statistics REST API.

Use o FiddlerUse Fiddler

Esta seção é equivalente a seções anteriores, apenas com o capturas de tela e instruções do FiddlerThis section is equivalent to previous sections, only with Fiddler screenshots and instructions

Formule uma solicitação semelhante à captura de tela a seguir.Formulate a request that looks like the following screenshot. Escolha GET como o verbo.Choose GET as the verb. O Fiddler adiciona User-Agent=Fiddler.Fiddler adds User-Agent=Fiddler. Você pode colar os dois cabeçalhos de solicitação adicionais em novas linhas abaixo dele.You can paste the two additional request headers on new lines below it. Inclua o tipo de conteúdo e a chave de API para seu serviço, usando a chave de acesso de administrador para seu serviço.Include the content type and api-key for your service, using the admin access key for your service.

Para o destino, copie em uma versão modificada desta URL: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2019-05-06For the target, copy in a modified version of this URL: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2019-05-06

Cabeçalho da solicitação do Fiddler

Dica

Desative o tráfego da Web para ocultar atividade HTTP não relacionada e incorreta. No menu Arquivo do Fiddler, desative Capturar Tráfego.

1 - Criar um índice1 - Create an index

Altere o verbo para PUT.Change the verb to PUT. Copie em uma versão modificada da URL: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels?api-version=2019-05-06.Copy in a modified version of this URL: https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels?api-version=2019-05-06. Copie a definição de índice fornecida acima para o corpo da solicitação.Copy the index definition provided above to the request body. Esta página deve ser semelhante à seguinte captura de tela.Your page should look similar to the following screenshot. Clique em Executar no canto superior direito para enviar a solicitação concluída.Click Execute on the top right to send the completed request.

Corpo da solicitação do Fiddler

2 - Carregar documentos2 - Load documents

Altere o verbo para POST.Change the verb to POST. Altere a URL para incluir /docs/index.Change the URL to include /docs/index. Copie os documentos para o corpo da solicitação, semelhante à captura de tela a seguir e, em seguida, execute a solicitação.Copy the documents into the request body, similar to the following screenshot, and then execute the request.

Conteúdo da solicitação do Fiddler

Dicas para executar os exemplos de consulta em FiddlerTips for running our sample queries in Fiddler

O exemplo de consulta a seguir é do artigo API REST Pesquisar Documentos.The following example query is from the Search Documents REST API article. Muitos dos exemplos de consulta deste artigo incluem espaços, que não são permitidos no Fiddler.Many of the example queries in this article include spaces, which are not allowed in Fiddler. Substitua cada espaço por um caractere + antes de colar na cadeia de consulta e tentar realizar a consulta no Fiddler.Replace each space with a + character before pasting in the query string before attempting the query in Fiddler.

Os espaços à frente são substituídos (em lastRenovationDate desc):Before spaces are replaced (in lastRenovationDate desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2019-05-06

Os espaços no final são substituídos por + (em lastRenovationDate+desc):After spaces are replaced with + (in lastRenovationDate+desc):

    GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate+desc&api-version=2019-05-06

Dicas para exibir estatísticas de índice no FiddlerTips for viewing index statistic in Fiddler

No Fiddler, clique na guia Inspetores, clique na guia Cabeçalhos e, em seguida, selecione o formato JSON.In Fiddler, click the Inspectors tab, click the Headers tab, and then select the JSON format. Você deverá ver a contagem de documentos e o tamanho do armazenamento (em KB).You should see the document count and storage size (in KB).

Próximas etapasNext steps

Os clientes REST são imprescindíveis para uma exploração improvisada, mas agora que você sabe como funcionam as APIs REST, você pode continuar com o código.REST clients are invaluable for impromptu exploration, but now that you know how the REST APIs work, you can move forward with code. Para as próximas etapas, confira os links a seguir:For your next steps, see the following links: