Preenchimento automático (API REST do Azure AI Search)

A API de Preenchimento Automático conclui uma entrada de consulta parcialmente tipada usando termos existentes no índice de pesquisa para uso em uma consulta secundária. Por exemplo, se a entrada de consulta for "medic", a API de Preenchimento Automático retornará "medicare", "medicaid", "medicine" se esses termos estiverem no índice. Internamente, o mecanismo de pesquisa procura termos correspondentes em campos que têm um Sugestor configurado.

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

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

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

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, as expressões de filtro não podem ser arbitrariamente complexas. Para obter mais informações sobre limitações de complexidade de filtro, consulte Sintaxe de expressão OData para a Pesquisa de IA do Azure.

Parâmetros de URI

Recomendações de codificação de URL

Lembre-se de codificar parâmetros de consulta específicos da URL ao chamar a API REST GET diretamente. Para preenchimento automático, a codificação de URL pode ser necessária para os seguintes parâmetros de consulta:

• 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 usar POST ou ao usar a biblioteca de clientes .NET do Azure AI Search, que manipula a codificação 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:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "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),
  "search": "partial_search_input",  
  "searchFields": "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.

(1) Limitações de difuso no preenchimento automático:

Primeiro, a distância de edição é limitada a apenas uma diferença de caracteres por token, ao contrário do parâmetro difuso na pesquisa. Limitar a distância de edição a um caractere significa que nem todas as correspondências de candidatos serão encontradas, mas o limite é necessário para garantir um nível aceitável de desempenho.

Em segundo lugar, a etapa difusa ocorre após a expansão parcial do token e somente os termos do mesmo fragmento de índice são considerados para correspondências difusas. Essa restrição aumenta o desempenho da API de Preenchimento Automático eliminando a agregação de correspondências difusas em todos os fragmentos. Essa restrição se torna menos perceptível à medida que mais termos são adicionados ao índice, resultando em distribuição de termo semelhante para cada fragmento. Como os termos são distribuídos uniformemente, as correspondências difusas dentro de um fragmento são uma boa aproximação de correspondências difusas em todo o índice. No entanto, os resultados poderão ser inferiores se o índice tiver menos termos, como em um índice de teste ou protótipo, resultando na representação desigual entre fragmentos. Para obter mais informações sobre como os índices são divididos em fragmentos, consulte combinações de partição e réplica.

Resposta

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

O conteúdo da resposta tem duas propriedades.

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

Exemplos

Exemplo 1: Recupere três sugestões de preenchimento automático em que a entrada de pesquisa parcial é 'washington medic' com o modo padrão (oneTerm):

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}  

Resposta:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}  

Exemplo 2: recuperar três sugestões de preenchimento automático em que a entrada de pesquisa parcial é 'washington medic' e autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}  

Resposta:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}  

Observe que suggesterName é necessário em uma operação de preenchimento automático.

Confira também

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