Autocompletar (API REST de Azure AI Search)

La API autocompletar finaliza una entrada de consulta parcialmente tipada mediante términos existentes en el índice de búsqueda para su uso en una consulta secundaria. Por ejemplo, si la entrada de consulta es "medic", la API autocompletar devuelve "medicare", "medicine""medicaid"si esos términos están en el índice. Internamente, el motor de búsqueda busca términos coincidentes en campos que tienen configurado un proveedor de sugerencias .

HTTPS es necesario para las solicitudes de servicio. La solicitud Autocompletar se puede construir mediante los métodos GET o 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]  

Cuando se llama con GET, la longitud de la dirección URL de la solicitud no puede superar los 8 KB. Esta longitud suele ser suficiente para la mayoría de las aplicaciones. Sin embargo, algunas aplicaciones producen consultas muy grandes, específicamente cuando se usan expresiones de filtro de OData. Para estas aplicaciones, HTTP POST es una mejor opción porque permite filtros más grandes que GET.

Con POST, el número de cláusulas en un filtro es el factor limitador, no el tamaño de la cadena del filtro, ya que el límite de tamaño de la solicitud POST es de 16 MB aproximadamente. Aunque el límite de tamaño de la solicitud POST es muy grande, las expresiones de filtro no pueden ser arbitrariamente complejas. Para más información sobre las limitaciones de complejidad del filtro, consulte Sintaxis de expresiones de OData para Azure AI Search.

Parámetros de identificador URI

Parámetro	Descripción
[nombre del servicio]	Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda.
[nombre de índice]/docs	Necesario. Especifica la colección de documentos de un índice con nombre.
api-version	Necesario. Consulte Versiones de API para obtener una lista de las versiones admitidas. En el caso de las consultas, la versión de api siempre se especifica como un parámetro URI para GET y POST.

Recomendaciones de codificación url

Recuerde codificar directamente los parámetros de consulta específicos para codificar la dirección URL al llamar directamente a la API REST GET. Para Autocompletar, es posible que sea necesario codificar url para los parámetros de consulta siguientes:

• paquetes Bower
• $filter
• highlightPreTag
• highlightPostTag

La codificación de direcciones URL solo se recomienda para parámetros individuales. Si por accidente codifica como URL la cadena de consulta completa (todo lo que hay después de ?), se interrumpirán las solicitudes.

Además, la codificación con URL solo es necesaria cuando se llama directamente a la API de REST directamente con GET. No es necesario codificar direcciones URL al usar POST o cuando se usa la biblioteca cliente de .NET de Azure AI Search, que controla la codificación por usted.

Encabezados de solicitud

En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.

Campos	Descripción
Content-Type	Necesario. Establézcalo en application/json
api-key	Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Las solicitudes de consulta en la docs colección pueden especificar una clave de administrador o una clave de consulta como api-key. La clave de consulta se usa para las operaciones de solo lectura en una colección de documentos de índice. Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información.

Cuerpo de la solicitud

Para GET: ninguno.

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

Una consulta acepta varios parámetros en la dirección URL cuando se llama con GET y como propiedades JSON en el cuerpo de la solicitud cuando se llama con POST. La sintaxis de algunos parámetros es algo diferente entre GET y POST. Estas diferencias se indican como se aplica a continuación.

Nombre	Tipo	Descripción
api-version	string	Necesario. Versión de la API REST usada para la solicitud. Para obtener una lista de las versiones admitidas, consulte Control de versiones de API. Para esta operación, la versión de api se especifica como un parámetro de URI independientemente de si llama a Autocompletar con GET o POST.
autocompletarMode	string	Opcional. El valor predeterminado es oneTerm. Los valores válidos son oneTerm, twoTerms, oneTermWithContext. oneTerm devuelve un único término. Si la consulta tiene dos términos, solo se completa el último término. Por ejemplo, dado "washington medic", la respuesta podría ser cualquiera de estos términos únicos: "medicaid", , "medicare""medicine". twoTerms coincide con frases de dos términos en el índice. Por ejemplo, dado "medic", la respuesta podría ser "medicare coverage"o "medical assistant". En muchos casos, los términos únicos o "medical" no se devolverán porque se da preferencia a frases de dos términos "medicare" que coinciden. oneTermWithContext completa el último término de una consulta con dos o más términos, donde los dos últimos términos son una frase que existe en el índice. Por ejemplo, dado "washington medic", la respuesta podría ser "washington medicaid", "washington medical".
$filter	string	Opcional. Expresión de búsqueda estructurada en sintaxis de OData estándar que filtra los documentos considerados para generar las sugerencias de términos completadas. Las expresiones de filtro "search.ismatch" y "search.ismatchscoring*" no se admiten en la API autocompletar. Solo se pueden usar campos filtrables en un filtro. Cuando se llama con POST, este parámetro se denomina filter en lugar de $filter. Consulte Sintaxis de expresiones de OData para Azure AI Search para más información sobre el subconjunto de la gramática de expresiones de OData que admite Azure AI Search.
Aproximada	boolean	Opcional. El valor predeterminado es "false". Cuando se establece en true, esta API busca sugerencias incluso si hay un carácter sustituido o que falta en el texto de búsqueda (1). Esto proporciona una mejor experiencia en algunos escenarios, pero conlleva un costo de rendimiento, ya que las búsquedas de sugerencias aproximadas son más lentas y consumen más recursos.
highlightPostTag	string	Opcional. El valor predeterminado es una cadena vacía. Etiqueta de cadena que se anexa al término resaltado. Debe establecerse con highlightPreTag. Los caracteres reservados en la dirección URL deben estar codificados con porcentaje (por ejemplo, %23 en vez de #). Cuando se llama mediante GET, los caracteres reservados de la dirección URL deben estar codificados por porcentaje (por ejemplo, %23 en lugar de #).
highlightPreTag	string	Opcional. El valor predeterminado es una cadena vacía. Etiqueta de cadena que antepone al término resaltado. Debe establecerse con highlightPostTag. Cuando se llama mediante GET, los caracteres reservados de la dirección URL deben estar codificados por porcentaje (por ejemplo, %23 en lugar de #).
minimumCoverage	integer	Opcional. El valor predeterminado es 80. Número comprendido entre 0 y 100 que indica el porcentaje del índice que debe estar disponible para atender la consulta antes de que se pueda notificar como correcto. El valor predeterminado refleja un sesgo hacia la velocidad y la eficiencia sobre la cobertura completa. La reducción de la cobertura restringe la expansión de las consultas, lo que permite que los resultados vuelvan más rápido. También permite que la consulta se realice correctamente en la disponibilidad parcial del índice, incluso si una partición es lenta para responder o no estar disponible debido a problemas de mantenimiento del servicio o mantenimiento de índices. Sea cual sea el valor de minimumCoverage, ese porcentaje del índice debe estar disponible o Autocompletar devuelve el código de estado HTTP 503. Si Autocompletar se realiza correctamente en el nivel mínimoCoverage, devuelve HTTP 200 e incluye un @search.coverage valor en la respuesta que indica el porcentaje del índice que estaba disponible al atender la consulta. Reducir este valor puede resultar útil si se producen errores 503. De lo contrario, puede considerar la posibilidad de generar el valor si la respuesta proporciona coincidencias insuficientes.
paquetes Bower	string	Necesario. Texto que se va a buscar. Texto de búsqueda que se va a completar. Debe tener 1 carácter como mínimo y no más de 100 caracteres. No puede contener operadores, sintaxis de consulta ni frases entrecomilladas.
searchFields	string	Opcional. La lista de nombres de campo separados por comas para buscar el texto especificado. Los campos de destino deben aparecer en la definición De proveedores de sugerencias del índice.
suggesterName	string	Necesario. Nombre del proveedor de sugerencias tal como se especifica en la colección Suggesters que forma parte de la definición de índice. Un proveedor de sugerencias determina qué campos se examinan para ver los términos de consulta sugeridos.
$top	integer	Opcional. El valor predeterminado es 5. Número de sugerencias de autocompleted que se van a recuperar. El valor debe ser un número entre 1 y 100. Cuando se llama con POST, este parámetro se denomina top en lugar de $top.

(1) Limitaciones de la función aproximada en Autocompletar:

En primer lugar, la distancia de edición se limita a solo una diferencia de caracteres por token a diferencia del parámetro aproximada en la búsqueda. Limitar la distancia de edición a un carácter significa que no se encontrarán todas las coincidencias candidatas, pero el límite es necesario para garantizar un nivel aceptable de rendimiento.

En segundo lugar, el paso aproximada se produce después de la expansión parcial del token y solo se consideran términos de la misma partición de índice para coincidencias aproximadas. Esta restricción aumenta el rendimiento de la API autocompletar eliminando la agregación de coincidencias aproximadas en todas las particiones. Esta restricción se vuelve menos perceptible a medida que se agregan más términos al índice, lo que da lugar a una distribución de términos similar para cada partición. A medida que los términos se distribuyen uniformemente, las coincidencias aproximadas dentro de una partición son una buena aproximación de coincidencias aproximadas en todo el índice. Sin embargo, los resultados podrían ser inferiores si el índice tiene menos términos, como en un índice de prueba o prototipo, lo que da lugar a la representación desigual entre particiones. Para obtener más información sobre cómo se dividen los índices en particiones, consulte combinaciones de particiones y réplicas.

Response

Código de estado: se devuelve "200 OK" para obtener una respuesta correcta.

La carga de respuesta tiene dos propiedades.

Propiedad	Descripción
"text"	El término o frase completados
"queryPlusText"	Entrada de consulta inicial más el término o frase completados

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

Ejemplos

Ejemplo 1: Recupere tres sugerencias de autocompletar en las que la entrada de búsqueda parcial esté 'washington medic' con el modo predeterminado (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"  
}  

Respuesta:

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

Ejemplo 2: Recuperar tres sugerencias de autocompletar donde la entrada de búsqueda parcial es 'washington medic' y 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"  
}  

Respuesta:

{    
  "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 es necesario en una operación autocompletar.

Consulte también

• Adición de proveedores de sugerencias a un índice
• Adición de sugerencias o autocompletar a una aplicación
• Códigos de estado HTTP