Sugestões (API REST do Azure AI Search)

Artigo
11/13/2023

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

Parâmetro	Descrição
[nome do serviço]	Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
[nome do índice]/docs	Obrigatórios. Especifica a coleção de documentos de um índice nomeado.
api-version	Obrigatórios. A versão estável atual é `api-version=2020-06-30`. Consulte Versões de 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 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

Campos Descrição

Tipo de conteúdo Obrigatórios. Defina-o como application/json

chave de API Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. As solicitações de consulta na coleção de documentos podem especificar uma chave de administrador ou chave de consulta como a chave de API. A chave de consulta é usada para operações somente leitura na coleção de documentos. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Campos	Descrição
Tipo de conteúdo	Obrigatórios. Defina-o como `application/json`
chave de API	Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. As solicitações de consulta na coleção de documentos podem especificar uma chave de administrador ou chave de consulta como a chave de API. A chave de consulta é usada para operações somente leitura na coleção de documentos. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

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.

Nome	Tipo	Descrição
api-version	string	Obrigatórios. Versão da API REST usada para a solicitação. Para obter uma lista de versões com suporte, consulte Versões da API. Para essa operação, a versão da api é especificada como um parâmetro de consulta na URL, independentemente de você chamar a API com GET ou POST.
$filter	string	Opcional. Uma expressão que filtra os documentos considerados para obter sugestões. Somente campos filtreáveis podem ser usados em um filtro. Não há suporte para expressões de filtro "search.ismatch" e "search.ismatchscoring*" na API de preenchimento automático. Quando chamado com POST, esse parâmetro é nomeado filtro em vez de $filter. Consulte Sintaxe de expressão OData para Azure AI Search para obter detalhes sobre o subconjunto da gramática de expressão OData compatível com o Azure AI Search.
difuso	booleano	Opcional. O padrão é false. Quando definida como true, essa API encontra sugestões mesmo se houver um caractere substituído ou ausente no texto de pesquisa. A distância de edição é 1 por cadeia de caracteres de consulta. Se a cadeia de caracteres de consulta for de vários termos, só poderá haver um caractere ausente, extra, substituído ou transposto em toda a cadeia de caracteres. Habilitar a correspondência difusa pode ser uma experiência melhor em alguns cenários, ela tem um custo de desempenho, pois as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag	string	Opcional. O padrão é uma cadeia de caracteres vazia. Uma marca de cadeia de caracteres que acrescenta ao termo realçado. Deve ser definido com highlightPreTag. Caracteres reservados na URL devem ser codificados por percentual (por exemplo, %23, em vez de #). Quando chamado usando GET, os caracteres reservados na URL devem ser codificados por porcentagem (por exemplo, %23 em vez de #).
highlightPreTag	string	Opcional. O padrão é uma cadeia de caracteres vazia. Uma marca de cadeia de caracteres que acrescenta ao termo realçado. Deve ser definido com highlightPostTag. Quando chamado usando GET, os caracteres reservados na URL devem ser codificados por porcentagem (por exemplo, %23 em vez de #).
$orderby	string	Opcional. Uma lista de expressões separadas por vírgulas para classificar os resultados. 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" (crescente) ou "desc" (decrescente). O padrão é a ordem crescente. Há um limite de 32 cláusulas para $orderby. Quando chamado com POST, esse parâmetro é nomeado ordem em vez de $orderby.
minimumCoverage	inteiro	Opcional. O padrão é 80. Um número entre 0 e 100 indicando a porcentagem do índice que deve estar disponível para atender à consulta antes que ela possa ser relatada como um sucesso. O padrão reflete um viés em relação à velocidade e à eficiência em relação à cobertura completa. A redução da cobertura restringe a expansão da consulta, permitindo que os resultados retornem mais rapidamente. Ele também permite que a consulta tenha êxito na disponibilidade parcial do índice, mesmo que um fragmento esteja lento para responder ou indisponível devido a problemas de integridade do serviço ou manutenção de índice. Qualquer que seja o valor de minimumCoverage, esse percentual do índice deve estar disponível ou Sugestões retorna HTTP status código 503. Se Sugestões tiverem êxito no nível minimumCoverage, ela retornará HTTP 200 e incluirá um @search.coverage valor na resposta indicando a porcentagem do índice que estava disponível ao atender a consulta. A redução desse valor poderá ser útil se 503 erros estiverem ocorrendo. Caso contrário, você poderá considerar aumentar o valor se a resposta estiver fornecendo correspondências insuficientes.
pequisa	string	Obrigatórios. O texto de pesquisa para usar as consultas de sugestão. Deve ter pelo menos 1 e não mais que 100 caracteres. Ele não pode conter operadores, sintaxe de consulta ou frases entre aspas.
searchFields	string	Opcional. A lista de nomes de campos separada por vírgulas para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser listados na definição Sugestores no índice.
$select	string	Opcional. Uma lista de campos separados por vírgulas a serem recuperados. Se não for especificado, somente a chave do documento e o texto da sugestão serão retornados. Você pode solicitar explicitamente todos os campos ao definir esse parâmetro para `*`. Ao chamar com POST, esse parâmetro é nomeado select em vez de $select.
suggesterName	string	Obrigatórios. O nome do sugestor conforme especificado na coleção Suggesters que faz parte da definição de índice. Um sugestor determina quais campos são verificados quanto aos termos de consulta sugeridos.
$top	inteiro	Opcional. O padrão é 5). O número de sugestões autocompletadas a serem recuperadas. O valor deve ser um número entre 1 e 100. Ao chamar com POST, esse parâmetro é nomeado top em vez de $top.

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.

Compartilhar via