Sugestões (API REST da Pesquisa de IA do Azure)

Artigo
11/13/2023

Um pedido de Sugestões é uma consulta de pesquisa à medida que escreve que procura valores correspondentes em campos com deteção de sugestões e devolve documentos que contêm uma correspondência. Por exemplo, se ativar sugestões num campo da cidade , escrever "mar" produz documentos que contêm "Seattle", "Sea Tac" e "Seaside" (todos os nomes reais da cidade) para esse campo.

A resposta é um conteúdo de um documento correspondente e a chave do documento. Em contraste com a Conclusão Automática, que devolve um termo ou expressão concluído utilizado numa consulta secundária, este pedido devolve informações que são resolvidas para documentos reais. Se os termos ou expressões correspondentes forem idênticos em todos os documentos, o conteúdo correspondente é repetido. Para melhorar a estrutura dos resultados, considere utilizar o $select filtro para devolver campos adicionais que fornecem mais diferenciação e contexto.

É necessário HTTPS para pedidos de serviço. O pedido Suggest pode ser construído com 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]

Ao contrário de um pedido de Documentos de Pesquisa , pode vincular uma chamada de Sugestões à entrada de teclado, ao passo que uma chamada de Pesquisa pode estar vinculada a um evento de clique.

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 muito 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 muito 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.
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 operações de Sugestões , isto inclui:

pesquisar
$filter
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 chamar Sugestões através de POST ou ao utilizar a biblioteca de cliente .NET da Pesquisa de IA do Azure processa a codificação de URL 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:

{  
      "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 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 de consulta no URL, independentemente de chamar a API com GET ou POST.
$filter	string	Opcional. Uma expressão que filtra os documentos considerados para sugestões. Apenas os campos filtráveis podem ser utilizados num filtro. As expressões de filtro "search.ismatch" e "search.ismatchscoring*" não são suportadas na API de Conclusão Automática. Quando chamado 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.
difuso	boolean	Opcional. O valor predefinido é falso. Quando definida como verdadeira, esta API encontra sugestões mesmo que exista um caráter substituído ou em falta no texto de pesquisa. A distância de edição é 1 por cadeia de consulta. Se a cadeia de consulta for de múltiplos termos, só pode existir um caráter em falta, adicional, substituído ou transposto em toda a cadeia. Ativar a correspondência difusa pode ser uma melhor experiência em alguns cenários, tem um custo de desempenho, uma vez que as pesquisas de sugestões difusas são mais lentas e consomem mais recursos.
highlightPostTag	string	Opcional. A predefinição é uma cadeia vazia. 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 #). Quando chamados com GET, os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
highlightPreTag	string	Opcional. A predefinição é uma cadeia vazia. Uma etiqueta de cadeia que se prepara para o termo realçado. Tem de ser definido com highlightPostTag. Quando chamados com GET, os carateres reservados no URL têm de estar codificados por percentagem (por exemplo, %23 em vez de #).
$orderby	string	Opcional. Uma lista de expressões separadas por vírgulas para ordenar os resultados. Cada expressão pode ser um nome de campo ou uma chamada para a `geo.distance()` função. Cada expressão pode ser seguida por "asc" (ascendente) ou "desc" (descendente). A predefinição é ordem ascendente. Existe um limite de 32 cláusulas para $orderby. Quando chamado com POST, este parâmetro tem o nome order em vez de $orderby.
minimumCoverage	número inteiro	Opcional. A predefinição é 80. 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 reflete uma tendência para a velocidade e eficiência em relação à cobertura total. A redução da cobertura restringe a expansão das consultas, permitindo que os resultados voltem mais rapidamente. Também permite que a consulta tenha êxito na disponibilidade parcial do índice, mesmo que uma partição horizontal seja lenta a responder ou indisponível devido a problemas de estado de funcionamento do serviço ou manutenção do índice. Qualquer que seja o valor de minimumCoverage, essa percentagem do índice tem de estar disponível ou Sugestões devolve o código de estado HTTP 503. Se sugestões forem bem-sucedidas ao nível mínimo de Recuperação, devolve HTTP 200 e inclui um @search.coverage valor na resposta que indica a percentagem do índice que estava disponível ao servir a consulta. A redução deste valor poderá ser útil se estiverem a ocorrer erros 503. Caso contrário, poderá considerar aumentar o valor se a resposta fornecer correspondências insuficientes.
pesquisar	string	Obrigatório. O texto de pesquisa a utilizar para sugerir consultas. Tem de ter, pelo menos, 1 caráter e não ter mais de 100 carateres. Não pode conter operadores, sintaxe de consulta ou expressões citadas.
campos de pesquisa	string	Opcional. A lista de nomes de campos separados por vírgulas para procurar o texto de pesquisa especificado. Os campos de destino têm de estar listados na definição Suggesters no índice.
$select	string	Opcional. Uma lista de campos separados por vírgulas a obter. Se não for especificado, apenas a chave do documento e o texto de sugestão são devolvidos. Pode pedir explicitamente todos os campos ao definir este parâmetro como `*`. Ao chamar com POST, este parâmetro tem o nome select em vez de $select.
suggesterName	string	Obrigatório. O nome do sugeridor, conforme especificado na coleção Suggesters que faz parte da definição do índice. Um sugeridor determina que campos são analisados para termos de consulta sugeridos.
$top	número inteiro	Opcional. A predefinição é 5). O número de sugestões de conclusão automática a obter. O valor tem de ser um número entre 1 e 100. Ao chamar com POST, este parâmetro tem o nome top em vez de $top.

Resposta

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

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

Se a opção de projeção for utilizada para obter campos, estes são incluídos em cada elemento da matriz:

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

Exemplos

Obtenha 5 sugestões em que 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"  
    }

Repare que suggesterName é necessário numa operação sugestões.