Pesquisar Documentos (API REST da Pesquisa de IA do Azure)

Artigo
11/13/2023

Um pedido de consulta destina-se à coleção de documentos de um único índice num serviço de pesquisa. Inclui parâmetros que definem os critérios de correspondência e os parâmetros que formam a resposta. A partir da versão da API 2021-04-30-Preview, também pode utilizar um alias de índice para direcionar um índice específico em vez de utilizar o próprio nome do índice.

Pode utilizar GET ou POST. Os parâmetros de consulta são especificados na cadeia de consulta para pedidos GET e no corpo do pedido para pedidos POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Se estiver a utilizar POST, adicione a ação "search" como um parâmetro URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Quando chamado com GET, o comprimento do URL do pedido não pode exceder os 8 KB. Normalmente, este comprimento é suficiente para a maioria das aplicações. No entanto, algumas aplicações produzem consultas grandes, especificamente quando são utilizadas expressões de filtro OData. Para estas aplicações, HTTP POST é uma escolha melhor porque permite filtros maiores do que GET.

Com POST, o número de cláusulas num filtro é o fator limitativo, não o tamanho da cadeia de filtro não processado, uma vez que o limite de tamanho do pedido para POST é de aproximadamente 16 MB. Embora o limite de tamanho do pedido POST seja grande, as expressões de filtro não podem ser arbitrariamente complexas. Para obter mais informações sobre as limitações de complexidade do filtro, veja Sintaxe de Expressão OData para a Pesquisa de IA do Azure.

Parâmetros do URI

Parâmetro	Description
[nome do serviço]	Obrigatório. Defina-o como o nome exclusivo definido pelo utilizador do seu serviço de pesquisa.
[nome do índice]/docs	Obrigatório. Especifica a coleção de documentos de um índice com nome.
[parâmetros de consulta]	Os parâmetros de consulta são especificados no URI para pedidos GET e no corpo do pedido para pedidos POST.
api-version	Obrigatório. A versão estável atual é `api-version=2020-06-30`. Veja Versões da API para obter mais versões. Para consultas, a versão da API é sempre especificada como um parâmetro de URI para GET e POST.

Recomendações de codificação de URL

Lembre-se de codificar parâmetros de consulta específicos de URL ao chamar diretamente a API REST GET. Para uma operação Pesquisar Documentos , a codificação de URL poderá ser necessária para os seguintes parâmetros de consulta:

pesquisar
$filter
faceta
highlightPreTag
highlightPostTag

A codificação de URL só é recomendada para parâmetros individuais. Se codificar inadvertidamente a cadeia de consulta inteira (tudo depois do ), os ?pedidos serão interrompidos.

Além disso, a codificação de URL só é necessária ao chamar a API REST diretamente com GET. Não é necessária codificação de URL ao utilizar POST ou ao utilizar a biblioteca de cliente .NET do Azure AI Search, que processa a codificação por si.

Cabeçalhos de Pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Campos	Description
Content-Type	Obrigatório. Defina esta opção como "application/json"
api-key	Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Uma chave de API é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. Os pedidos de consulta na coleção de documentos podem especificar uma chave de administrador ou uma chave de consulta como a chave de API. A chave de consulta é utilizada para operações só de leitura na coleção de documentos. Veja Connect to Azure AI Search using key authentication (Ligar à Pesquisa de IA do Azure com a autenticação de chaves ) para obter detalhes.

Campos

Description

Content-Type

Obrigatório. Defina esta opção como "application/json"

api-key

Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Uma chave de API é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. Os pedidos de consulta na coleção de documentos podem especificar uma chave de administrador ou uma chave de consulta como a chave de API. A chave de consulta é utilizada para operações só de leitura na coleção de documentos. Veja Connect to Azure AI Search using key authentication (Ligar à Pesquisa de IA do Azure com a autenticação de chaves ) para obter detalhes.

Corpo do Pedido

Para GET: Nenhum.

Para POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Continuação de Respostas de Pesquisa Parciais

Por vezes, o Azure AI Search não consegue devolver todos os resultados pedidos numa única resposta de Pesquisa. Isto pode acontecer por diferentes razões, como quando a consulta pede demasiados documentos ao não especificar $top ou especificar um valor para $top esse valor é demasiado grande. Nestes casos, a Pesquisa de IA do Azure inclui a @odata.nextLink anotação no corpo da resposta e também @search.nextPageParameters se foi um pedido POST. Pode utilizar os valores destas anotações para formular outro pedido de Pesquisa para obter a parte seguinte da resposta de pesquisa. Isto é denominado continuação do pedido de Pesquisa original e as anotações são geralmente denominadas tokens de continuação. Veja o exemplo em Resposta abaixo para obter detalhes sobre a sintaxe destas anotações e onde aparecem no corpo da resposta.

Os motivos pelos quais o Azure AI Search pode devolver tokens de continuação são específicos da implementação e estão sujeitos a alterações. Os clientes robustos devem estar sempre prontos para processar casos em que são devolvidos menos documentos do que o esperado e um token de continuação é incluído para continuar a obter documentos. Tenha também em atenção que tem de utilizar o mesmo método HTTP que o pedido original para continuar. Por exemplo, se enviou um pedido GET, todos os pedidos de continuação que enviar também têm de utilizar GET (e igualmente para POST).

Nota

O objetivo de @odata.nextLink e @search.nextPageParameters é proteger o serviço de consultas que pedem demasiados resultados, não para fornecer um mecanismo geral para paginação. Se quiser analisar os resultados, utilize $top e $skip junte-os. Por exemplo, se quiser páginas de tamanho 10, o primeiro pedido deve ter $top=10 e $skip=0, o segundo pedido deve ter $top=10 e $skip=10, o terceiro pedido deve ter $top=10 e $skip=20, etc.

Parâmetros de Consulta

Uma consulta aceita vários parâmetros no URL quando é chamada com GET e como propriedades JSON no corpo do pedido quando chamada com POST. A sintaxe de alguns parâmetros é ligeiramente diferente entre GET e POST. Estas diferenças são indicadas conforme aplicável abaixo.

Nome	Tipo	Description
api-version	string	Obrigatório. Versão da API REST utilizada para o pedido. Para obter uma lista das versões suportadas, veja Versões da API. Para esta operação, a versão da api é especificada como um parâmetro URI, independentemente de chamar Documentos de Pesquisa com GET ou POST.
`$count`	boolean	Opcional. Os valores válidos são "true" ou "false". A predefinição é "false". Quando chamado com POST, este parâmetro tem o nome count em vez de `$count`. Especifica se pretende obter a contagem total de resultados. Esta é a contagem de todos os documentos que correspondem aos parâmetros de pesquisa e $filter, ignorando `$top` e `$skip`. Definir este valor como "verdadeiro" pode degradar o desempenho. A contagem é precisa se o índice for estável, mas irá sub ou sobre-reportar quaisquer documentos que sejam adicionados, atualizados ou eliminados ativamente. Se quiser obter apenas a contagem sem documentos, pode utilizar `$top`=0.
facetas ou facetas	string	Opcional. Um campo pelo qual a faceta é atribuída, em que o campo é atribuído como "facetável". Quando chamado com GET, `facet` é um campo (`facet: field1`). Quando chamado com POST, este parâmetro é nomeado `facets` em vez de `facet` e é especificado como uma matriz (`facets: [field1, field2, field3]`). A cadeia pode conter parâmetros para personalizar a faceta, expressa como pares nome-valor separados por vírgulas. Os parâmetros válidos são "count", "sort", "values", "interval" e "timeoffset". "count" é o número máximo de termos de facetas; predefinição é 10. Não existe um limite superior no número de termos, mas os valores mais elevados degradam o desempenho, especialmente se o campo facetado contiver um grande número de termos exclusivos. Por exemplo, "facet=category,count:5" obtém as cinco principais categorias nos resultados de facetas. Se o parâmetro de contagem for inferior ao número de termos exclusivos, os resultados poderão não ser exatos. Isto deve-se à forma como as consultas de faceta são distribuídas entre partições horizontais. Pode definir a contagem para zero ou para um valor maior ou igual ao número de valores exclusivos no campo de tabela facial para obter uma contagem precisa em todas as partições horizontais. A desvantagem é o aumento da latência. "sort" pode ser definido como "count", "-count", "value", "-value". Utilize a contagem para ordenar por contagem. Utilize -count para ordenar ascendente por contagem. Utilize o valor para ordenar ascendente por valor. Utilize -value para ordenar por valor descendente (por exemplo, "facet=category,count:3,sort:count" obtém as três principais categorias em facetas resulta em ordem descendente pelo número de documentos com cada nome de cidade). Se as três principais categorias são Orçamento, Motel e Luxo, e Orçamento tem 5 sucessos, Motel tem 6, e Luxury tem 4, então os baldes estão na ordem Motel, Orçamento, Luxo. Para -value, "facet=rating,sort:-value" produz registos para todas as classificações possíveis, por ordem descendente por valor (por exemplo, se as classificações forem de 1 a 5, os registos são ordenados 5, 4, 3, 2, 1, independentemente do número de documentos que correspondam a cada classificação). Os "valores" podem ser definidos para valores numéricos delimitados por pipe ou Edm.DateTimeOffset, especificando um conjunto dinâmico de valores de entrada de facetas (por exemplo, "facet=baseRate,values:10 \| 20" produz três registos: um para a taxa base 0 até, mas não incluindo 10, um para 10 até, mas não incluindo 20, e um para 20 e mais). Uma cadeia "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produz dois baldes: um para hotéis renovados antes de fevereiro de 2010 e outro para hotéis renovados a 1 de fevereiro de 2010 ou posterior. Os valores têm de ser listados por ordem sequencial e ascendente para obter os resultados esperados. "interval" é um intervalo inteiro superior a 0 para números, ou minuto, hora, dia, semana, mês, trimestre, ano para valores de data/hora. Por exemplo, "facet=baseRate,interval:100" produz registos com base em intervalos de taxa base de tamanho 100. Se as tarifas base estiverem entre $60 e $600, haverá registos para 0-100, 100-200, 200-300, 300-400, 400-500 e 500-600. A cadeia "facet=lastRenovationDate,interval:year" produz um registo para cada ano em que os hotéis foram renovados. "timeoffset" pode ser definido como ([+-]hh:mm, [+-]hhmm ou [+-]hh). Se utilizado, o parâmetro timeoffset tem de ser combinado com a opção de intervalo e apenas quando aplicado a um campo do tipo Edm.DateTimeOffset. O valor especifica o desvio de tempo UTC para contabilizar na definição de limites de tempo. Por exemplo: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" utiliza o limite de dia que começa às 01:00:00 UTC (meia-noite no fuso horário de destino). A contagem e ordenação podem ser combinadas com a mesma especificação de facetas, mas não podem ser combinadas com intervalos ou valores e o intervalo e os valores não podem ser combinados em conjunto. As facetas de intervalo na data/hora são calculadas com base na hora UTC, se o timeoffset não for especificado. Por exemplo: para "facet=lastRenovationDate,interval:day", o limite do dia começa às 00:00:00 UTC.
$filter	string	Opcional. Uma expressão de pesquisa estruturada na sintaxe OData padrão. Apenas os campos filtráveis podem ser utilizados num filtro. Ao chamar com POST, este parâmetro tem o nome filter em vez de $filter. Veja Sintaxe da Expressão OData para a Pesquisa de IA do Azure para obter detalhes sobre o subconjunto da gramática da expressão OData suportada pelo Azure AI Search.
realçar	string	Opcional. Um conjunto de nomes de campos separados por vírgulas utilizado para os destaques de acesso. Apenas os campos pesquisáveis podem ser utilizados para o realce de resultados. Por predefinição, a Pesquisa de IA do Azure devolve até 5 destaques por campo. O limite é configurável por campo ao acrescentar "-<max # de destaques>" seguindo o nome do campo. Por exemplo, "highlight=title-3,description-10" devolve até 3 acessos realçados do campo de título e até 10 acessos do campo de descrição. O número máximo de destaques tem de ser um número inteiro entre 1 e 1000 inclusive.
highlightPostTag	string	Opcional. A predefinição é `"</em>"`. Uma etiqueta de cadeia que acrescenta ao termo realçado. Tem de ser definido com highlightPreTag. Os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
highlightPreTag	string	Opcional. A predefinição é `"</em>"`. Uma etiqueta de cadeia que se prepara para o termo realçado. Tem de ser definido com highlightPostTag. Os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
minimumCoverage	número inteiro	Opcional. Os valores válidos são um número entre 0 e 100, que indica a percentagem do índice que tem de estar disponível para servir a consulta antes de poder ser reportado como um êxito. A predefinição é "100". 100% de cobertura significa que todas as partições horizontais responderam ao pedido (nem os problemas de saúde do serviço nem as atividades de manutenção reduziram a cobertura). Na predefinição, a cobertura inferior à total devolve o código de estado HTTP 503. A redução de minimumCoverage pode ser útil se estiverem a ocorrer erros 503 e quiser aumentar a probabilidade de êxito da consulta, especialmente para serviços configurados para uma réplica. Se definir minimumCoverage e Search com êxito, devolve HTTP 200 e inclui um @search.coverage valor na resposta que indica a percentagem do índice incluído na consulta. Neste cenário, nem todos os documentos correspondentes estão presentes nos resultados da pesquisa, mas se a disponibilidade da pesquisa for mais importante do que a revocação, a redução da cobertura pode ser uma estratégia de mitigação viável.
$orderby	string	Opcional. Uma lista de expressões separadas por vírgulas para ordenar os resultados. Quando chamado com POST, este parâmetro é denominado orderby em vez de $orderby. Cada expressão pode ser um nome de campo ou uma chamada para a função geo.distance(). Cada expressão pode ser seguida por "asc" para indicar ascendente e "desc" para indicar descendente. Se existirem valores nulos no campo de ordenação, os valores nulos aparecem primeiro por ordem ascendente e os últimos por ordem descendente. A predefinição é ordem ascendente. Os empates serão quebrados pelas pontuações de correspondência de documentos. Se não for especificada nenhuma $orderby, a sequência de ordenação predefinida é descendente por classificação de correspondência do documento. Há um limite de 32 cláusulas para $orderby.
queryType	string	Opcional. Os valores válidos são "simples" ou "completos". A predefinição é "simples". "simples" interpreta as cadeias de consulta com a sintaxe de consulta simples que permite símbolos como `+`, `*` e `""`. As consultas são avaliadas em todos os campos pesquisáveis (ou campos indicados em searchFields) em cada documento por predefinição. "full" interpreta as cadeias de consulta com a sintaxe de consulta Lucene completa que permite pesquisas específicas e ponderadas do campo. A pesquisa de intervalos na linguagem de consulta Lucene não é suportada a favor de $filter, que oferece funcionalidades semelhantes.
scoreParameter	string	Opcional. Indica os valores para cada parâmetro definido numa função de classificação (como referencePointParameter) com o formato "name-value1,value2,..." Quando chamado com POST, este parâmetro é denominado scoreParameters em vez de scoreParameter. Além disso, especifique-a como uma matriz JSON de cadeias em que cada cadeia é um par de nomes-valores separado. Para perfis de classificação que incluem uma função, separe a função da lista de entrada com um `-` caráter. Por exemplo, uma função chamada `"mylocation"` seria "&scoreParameter=mylocation--122.2,44.8". O primeiro traço separa o nome da função da lista de valores, enquanto o segundo traço faz parte do primeiro valor (longitude neste exemplo). Para parâmetros de classificação, como para o aumento de etiquetas que podem conter vírgulas, pode escapar a esses valores na lista com plicas. Se os próprios valores contiverem plicas, pode escapar-lhes duplicando. Suponha que tem um parâmetro de aumento de etiquetas chamado `"mytag"` e pretende aumentar os valores da etiqueta "Hello, O'Brien" e "Smith", a opção de cadeia de consulta seria então "&scoreParameter=mytag-'Hello, O'Brien',Smith". As aspas só são necessárias para valores que contenham vírgulas.
scoreProfile	string	Opcional. O nome de um perfil de classificação para avaliar pontuações de correspondência para documentos correspondentes para ordenar os resultados.
scoreStatistics	string	Opcional. Os valores válidos são "local" ou "global". A predefinição é "local". Especifique se pretende calcular estatísticas de classificação, como a frequência do documento, globalmente (em todas as partições horizontais) para uma classificação mais consistente ou localmente (na partição horizontal atual) para uma menor latência. Veja Estatísticas de Classificação na Pesquisa de IA do Azure. As estatísticas de classificação serão sempre calculadas localmente para termos que utilizam a pesquisa difusa ('~').
pesquisar	string	Opcional. O texto a procurar. Todos os campos pesquisáveis são procurados por predefinição, a menos que searchFields seja especificado. No índice, o texto num campo pesquisável é token, pelo que vários termos podem ser separados por espaço em branco (por exemplo: "search=hello world"). Para corresponder a qualquer termo, utilize `` (isto pode ser útil para consultas de filtro booleano). Omitir este parâmetro tem o mesmo efeito que defini-lo como ``. Veja Sintaxe de consulta simples para obter detalhes sobre a sintaxe de pesquisa. Por vezes, os resultados podem ser surpreendentes ao consultar campos pesquisáveis. O tokenizer inclui lógica para processar casos comuns ao texto em inglês, como apóstrofos, vírgulas em números, etc. Por exemplo, "search=123,456" corresponderá a um único termo "123.456" em vez dos termos individuais "123" e "456", uma vez que as vírgulas são utilizadas como separadores de milhares para números grandes em inglês. Por este motivo, recomendamos a utilização de espaço em branco em vez de pontuação para separar termos no parâmetro de pesquisa.
searchMode	string	Opcional. Os valores válidos são "qualquer" ou "todos" Predefinições para "qualquer". Especifica se algum ou todos os termos de pesquisa têm de ser correspondidos para contar o documento como uma correspondência.
campos de pesquisa	string	Opcional. A lista de nomes de campos separados por vírgulas para procurar o texto especificado. Os campos de destino têm de ser marcados como pesquisáveis no esquema de índice.
$select	string	Opcional. Uma lista de campos separados por vírgulas a incluir no conjunto de resultados. Apenas os campos marcados como recuperáveis podem ser incluídos nesta cláusula. Se não for especificado ou definido como `*`, todos os campos marcados como recuperáveis no esquema serão incluídos na projeção. Quando chamado com POST, este parâmetro tem o nome select em vez de $select.
sessionId	string	Opcional. A utilização de sessionId ajuda a melhorar a consistência da classificação de relevância dos serviços de pesquisa com várias réplicas. Nas configurações de várias réplicas, podem existir ligeiras diferenças entre classificações de relevância de documentos individuais para a mesma consulta. Quando é fornecido um ID de sessão, o serviço faz o melhor esforço para encaminhar um determinado pedido para a mesma réplica para essa sessão. Tenha em atenção que reutilizar repetidamente os mesmos valores de ID de sessão pode interferir com o balanceamento de carga dos pedidos entre réplicas e afetar negativamente o desempenho do serviço de pesquisa. O valor utilizado como sessionId não pode começar com um caráter "_". Se um serviço não tiver réplicas, este parâmetro não tem qualquer efeito no desempenho ou na consistência da classificação.
$skip	número inteiro	Opcional. O número de resultados da pesquisa a ignorar. Quando chamado com POST, este parâmetro tem o nome skip em vez de `$skip`. Este valor não pode ser superior a 100 000. Se precisar de analisar documentos em sequência, mas não puder utilizar `$skip` devido a esta limitação, considere utilizar $orderby num campo que tenha valores exclusivos para cada documento no índice (como a chave do documento, por exemplo) e, em vez disso, $filter com uma consulta de intervalo.
$top	número inteiro	Opcional. O número de resultados da pesquisa a obter. Esta predefinição é 50. Quando chamado com POST, este parâmetro tem o nome top em vez de `$top`. Se especificar um valor superior a 1000 e existirem mais de 1000 resultados, apenas serão devolvidos os primeiros 1000 resultados, juntamente com uma ligação para a página seguinte de resultados (veja @odata.nextLink no exemplo abaixo). O Azure AI Search utiliza paginação do lado do servidor para impedir que as consultas recuperem demasiados documentos ao mesmo tempo. O tamanho de página predefinido é 50, enquanto o tamanho máximo da página é 1000. Isto significa que, por predefinição, os Documentos de Pesquisa devolvem, no máximo, 50 resultados se não especificar `$top`. Se existirem mais de 50 resultados, a resposta inclui informações para obter a página seguinte de, no máximo, 50 resultados (veja "@odata.nextLink" e "@search.nextPageParameters" nos Exemplos abaixo. Da mesma forma, se especificar um valor superior a 1000 para `$top` e existirem mais de 1000 resultados, apenas são devolvidos os primeiros 1000 resultados, juntamente com informações para obter a página seguinte de, no máximo, 1000 resultados.

Resposta

Código de Estado: 200 OK é devolvido para uma resposta com êxito.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Exemplos

Pode encontrar mais exemplos na Sintaxe de Expressão OData para a Pesquisa de IA do Azure.

Pesquise o Índice ordenado por data descendente:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Numa pesquisa por facetas, pesquise o índice e obtenha facetas para categorias, classificações, etiquetas e itens com baseRate em intervalos específicos.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
Repare que a última faceta está num subcampo. As facetas contam o documento principal (Hotéis) e não os subdocumentos intermédios (Salas), pelo que a resposta determina o número de hotéis que têm quartos em cada registo de preço.

Com um filtro, reduza o resultado da consulta facetada anterior depois de o utilizador selecionar Classificação 3 e categoria "Motel".

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Numa pesquisa por facetas, defina um limite superior em termos exclusivos devolvidos numa consulta. A predefinição é 10, mas pode aumentar ou diminuir este valor com o parâmetro count no atributo facet. Este exemplo devolve facetas para a cidade, limitadas a 5.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Procure o Índice em campos específicos (por exemplo, um campo de idioma):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Pesquise o Índice em vários campos. Por exemplo, pode armazenar e consultar campos pesquisáveis em vários idiomas, todos no mesmo índice. Se as descrições em inglês e francês coexistirem no mesmo documento, pode devolver qualquer ou todos os resultados da consulta:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Só pode consultar o índice de cada vez. Não crie vários índices para cada idioma, a menos que planeie consultar um de cada vez.

Paginação – obter a primeira página de itens (o tamanho da página é 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Paginação – obter a segunda página de itens (o tamanho da página é 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Obter um conjunto específico de campos:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Obter documentos que correspondam a uma expressão de filtro específica:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Pesquise o índice e devolva fragmentos com destaques de acerto:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Pesquise o índice e devolva documentos ordenados de mais perto para mais longe de uma localização de referência:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Pesquise o índice partindo do princípio de que existe um perfil de classificação chamado "geo" com duas funções de classificação de distância, uma a definir um parâmetro chamado "currentLocation" e outra a definir um parâmetro chamado "lastLocation". No exemplo seguinte, "currentLocation" tem um delimitador de um único traço (-). É seguido por coordenadas de longitude e latitude, em que a longitude é um valor negativo.
```
GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
Encontre documentos no índice com a sintaxe de consulta simples. Esta consulta devolve hotéis onde os campos pesquisáveis contêm os termos "conforto" e "localização", mas não "motel":
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Dica

A utilização de searchMode=all substitui a predefinição de searchMode=any, garantindo que -motel significa "E NÃO" em vez de "OU NÃO". Sem searchMode=allo , obtém "OU NÃO", que se expande em vez de restringir os resultados da pesquisa, o que pode ser contra-intuitivo para alguns utilizadores.
Encontre documentos no índice com a sintaxe de consulta Lucene. Esta consulta devolve hotéis onde o campo de categoria contém o termo "orçamento" e todos os campos pesquisáveis que contêm a expressão "recentemente renovado". Os documentos que contêm a expressão "recentemente renovado" são classificados mais alto como resultado do valor de aumento do termo (3)
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
Encontre documentos no índice ao mesmo tempo que favorece a classificação consistente em vez da latência mais baixa. Esta consulta calcula as frequências dos documentos em todo o índice e faz o melhor esforço para direcionar a mesma réplica para todas as consultas na mesma "sessão", o que ajuda a gerar uma classificação estável e reproduzível.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```