Sugerencias (API REST de Azure AI Search)

  • Artículo

Una solicitud de sugerencias es una consulta de búsqueda como tipo que busca valores coincidentes en campos compatibles con el proveedor de sugerencias y devuelve documentos que contienen una coincidencia. Por ejemplo, si habilita sugerencias en un campo de ciudad , al escribir "mar" se generan documentos que contienen "Seattle", "Sea Tac" y "Seaside" (todos los nombres de ciudad reales) para ese campo.

La respuesta es un contenido de un documento coincidente más la clave del documento. A diferencia de Autocompletar, que devuelve un término o frase completado que se usa en una consulta secundaria, esta solicitud devuelve información que se resuelve en documentos reales. Si los términos o frases coincidentes son idénticos en los documentos, se repite el contenido coincidente. Para mejorar la estructura de los resultados, considere la posibilidad de usar el $select filtro para devolver campos adicionales que proporcionan más diferenciación y contexto.

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

A diferencia de una solicitud de documentos de búsqueda , puede enlazar una llamada de sugerencias a la entrada del teclado, mientras que una llamada de búsqueda podría estar enlazada a un evento de clic.

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. La versión estable actual es api-version=2020-06-30. Consulte Versiones de API para obtener más versiones. 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 las operaciones Sugerencias , se incluye lo siguiente:

  • 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 llamar a Sugerencias mediante POST o cuando se usa la biblioteca cliente de .NET de Azure AI Search controla la codificación de direcciones URL automáticamente.

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. Una clave de API es una cadena única generada por el sistema que autentica la solicitud en el servicio de búsqueda. Las solicitudes de consulta en la colección de documentos pueden especificar una clave de administrador o una clave de consulta como clave de API. La clave de consulta se usa para las operaciones de solo lectura en la colección de documentos. 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:

{  
      "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

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 Versiones de API. Para esta operación, la versión de api se especifica como un parámetro de consulta en la dirección URL, independientemente de si llama a la API con GET o POST.
$filter string Opcional. Una expresión que filtra los documentos considerados para obtener sugerencias. Solo se pueden usar campos filtrables en un filtro. Las expresiones de filtro "search.ismatch" y "search.ismatchscoring*" no se admiten en la API autocompletar. 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. La distancia de edición es de 1 por cadena de consulta. Si la cadena de consulta es de varios términos, solo puede haber un carácter ausente, adicional, sustituido o transpuesto en toda la cadena. La habilitación de la coincidencia aproximada puede ser una mejor experiencia en algunos escenarios, lo que supone 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 #).
$orderby string Opcional. Una lista de expresiones separadas por coma según la cual ordenar los resultados. Cada expresión puede ser un nombre de campo o una llamada a la función geo.distance() . Cada expresión se puede seguir por "asc" (ascendente) o "desc" (descendente). El valor predeterminado es ascendente. Hay un límite de 32 cláusulas para $orderby. Cuando se llama con POST, este parámetro se denomina order en lugar de $orderby.
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 Sugerencias devuelve el código de estado HTTP 503. Si las sugerencias se realizan 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. El texto de búsqueda que se va a utilizar para sugerir las consultas. 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.
$select string Opcional. Una lista de los campos separados por coma que se van a recuperar. Si no se especifica, solo se devuelven la clave del documento y el texto de sugerencia. Se pueden solicitar explícitamente todos los campos estableciendo este parámetro en *. Al llamar a con POST, este parámetro se denomina select en lugar de $select.
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. Al llamar a con POST, este parámetro se denomina top en lugar de $top.

Response

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

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

Si se utiliza la opción de proyección para recuperar campos, se incluyen en cada elemento de la matriz:

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

Ejemplos

Recuperar 5 sugerencias donde la entrada de búsqueda parcial es '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 es necesario en una operación De sugerencias.

Consulte también