Sugestões (API REST do Azure AI Search)

Uma solicitação de Sugestões é uma consulta de pesquisa conforme o tipo que procura valores correspondentes em campos com reconhecimento de sugestão e retorna documentos que contêm uma correspondência. Por exemplo, se você habilitar sugestões em um campo da cidade , digitar "mar" produzirá documentos contendo "Seattle", "Sea Tac" e "Seaside" (todos os nomes reais da cidade) para esse campo.

A resposta é um conteúdo de um documento correspondente mais a chave do documento. Em contraste com o Preenchimento Automático, que retorna um termo ou frase concluído usado em uma consulta secundária, essa solicitação retorna informações que são resolvidas para documentos reais. Se os termos ou frases correspondentes forem idênticos entre documentos, o conteúdo correspondente será repetido. Para melhorar a estrutura de resultados, considere usar o $select filtro para retornar campos adicionais que fornecem mais diferenciação e contexto.

HTTPS é necessário para as solicitações de serviço. A solicitação Suggest pode ser construída usando os métodos GET ou POST.

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

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

Em contraste com uma solicitação pesquisar documentos , você pode associar uma chamada sugestões à entrada do teclado, enquanto uma chamada de Pesquisa pode estar associada a um evento de clique.

Quando chamado com GET, o comprimento da URL de solicitação não pode exceder 8 KB. Esse comprimento geralmente é suficiente para a maioria dos aplicativos. No entanto, alguns aplicativos produzem consultas muito grandes, especificamente quando expressões de filtro OData são usadas. Para esses aplicativos, HTTP POST é uma opção melhor porque permite filtros maiores que GET.

Com o POST, o número de cláusulas em um filtro é o fator limitante, não o tamanho da cadeia de caracteres de filtro não processada, uma vez que o limite de tamanho da solicitação POST é quase 16 MB. Embora o limite de tamanho da solicitação POST seja muito grande, expressões de filtro não podem ser arbitrariamente complexos. Para obter mais informações sobre limitações de complexidade de filtro, consulte Sintaxe de expressão OData para Azure AI Search.

Parâmetros de URI

Recomendações de codificação de URL

Lembre-se de codificar url parâmetros de consulta específicos ao chamar diretamente a API REST GET. Para as operações Sugestões , isso inclui:

• pequisa
• $filter
• highlightPreTag
• highlightPostTag

A codificação de URL só é recomendada para parâmetros individuais. Se você usar a codificação de URL inadvertidamente para a cadeia de caracteres de consulta inteira (tudo após o ?), as solicitações são interrompidas.

Além disso, a codificação de URL só é necessária ao se chamar a API REST diretamente usando GET. Nenhuma codificação de URL é necessária ao chamar Sugestões usando POST ou, ao usar a biblioteca de clientes do .NET do Azure AI Search , manipula a codificação de URL para você.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Corpo da solicitação

Para GET: Nenhum.

Para POST:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}  

Parâmetros de consulta

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

Resposta

Código de status: "200 OK" é retornado para uma resposta bem-sucedida.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}  

Se a opção de projeção for usada para recuperar campos, eles serão incluídos em cada elemento da matriz:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}  

Exemplos

Recupere 5 sugestões, onde a entrada de pesquisa parcial é “lux”:

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }  

Observe que suggesterName é necessário em uma operação sugestões.

Confira também

• Adicionar sugestores a um índice
• Adicionar sugestões ou preenchimento automático a um aplicativo
• Códigos de status HTTP