Crea una interfaz de búsqueda con la API de consulta

La API de consulta proporciona métodos de sugerencia y búsqueda para compilar una interfaz de búsqueda o incorporar resultados de la búsqueda en una aplicación.

Para aplicaciones web con requisitos mínimos, considera el uso de un widget de búsqueda. Para obtener más información, consulta Crea una interfaz de búsqueda con el widget de búsqueda

Compila una interfaz de búsqueda

La compilación de una interfaz de búsqueda mínima requiere varios pasos:

  1. Configura una aplicación de búsqueda
  2. Genera credenciales OAuth para la aplicación.
  3. Consulta el índice
  4. Muestra los resultados de la consulta.

Puedes mejorar aún más la interfaz de búsqueda con características como la paginación, clasificación, filtrado, facetas y sugerencias automáticas.

Configura una aplicación de búsqueda

Debes crear al menos una aplicación de búsqueda para asociarla a cada interfaz de búsqueda que crees. Una aplicación de búsqueda proporciona los parámetros predeterminados para una consulta, como las fuentes de datos que se desean incluir, el orden de clasificación, los filtros y las facetas para solicitar. Si es necesario, puedes anular estos parámetros con la API de consulta.

Para obtener más información sobre las aplicaciones de búsqueda, consulta la página sobre cómo crear una experiencia de búsqueda personalizada.

Genera credenciales OAuth para la aplicación

Además de los pasos que figuran en Configura el acceso a la API de REST de Google Cloud Search, también debes generar credenciales OAuth para la aplicación web. El tipo de credenciales que creas depende del contexto en el que se usa la API.

Usa las credenciales para solicitar autorización en nombre del usuario. Usa el alcance https://www.googleapis.com/auth/cloud_search.query cuando solicites autorización.

Para obtener información adicional sobre las bibliotecas cliente y las opciones OAuth, consulta Google Identity Platform.

Consulta el índice

Usa el método search para realizar búsquedas en el índice.

Toda solicitud debe incluir dos datos: una query de texto de modo que coincida con los elementos y un searchApplicationId que identifica el ID para que use la aplicación de búsqueda.

En el fragmento siguiente, se muestra una consulta a la fuente de datos de películas para la película Titanic:

{
      "query": "titanic",
      "requestOptions": {
        "searchApplicationId": "searchapplications/<search_app_id>"
      },
    }
    

Muestra los resultados de la consulta

Como mínimo, se espera que las interfaces de búsqueda muestren el elemento title, así como un vínculo al elemento original. Puedes mejorar aún más la visualización de los resultados de la búsqueda si aprovechas la información adicional presente en estos, como el fragmento y los metadatos.

Destaca los fragmentos

Para los elementos mostrados que contienen texto indexado o contenido HTML, se muestra un fragmento del contenido. Este contenido ayuda a los usuarios a determinar la relevancia del elemento que se muestra.

Si los términos de la consulta están presentes en el fragmento, también se muestran uno o más rangos de coincidencia que identifican la ubicación de los términos.

Usa matchRanges para destacar el texto coincidente cuando se procesan los resultados. El siguiente ejemplo de javascript convierte el fragmento en un lenguaje de marcado HTML con cada rango coincidente en una etiqueta <span>.

function highlightSnippet(snippet) {
      let text = snippet.snippet;
      let formattedText = text;
      if (snippet.matchRanges) {
        let parts = [];
        let index = 0;
        for (let match of snippet.matchRanges) {
          let start = match.start || 0; // Default to 0 if omitted
          let end = match.end;
          if (index < start) { // Include any leading text before/between ranges
            parts.push(text.slice(index, start));
          }
          parts.push('<span class="highlight">');
          parts.push(text.slice(start, end));
          parts.push('</span>');
          index = end;
        }
        parts.push(text.slice(index)); // Include any trailing text after last range
        formattedText = parts.join('');
      }
      return formattedText;
    }
    

Dado el fragmento:

{
      "snippet": "This is an example snippet...",
      "matchRanges": [
        {
          "start": 11,
          "end": 18
        }
      ]
    }
    

La string HTML resultante es:

This is an <span class="highlight">example</span> snippet...
    

Muestra los metadatos

Usa el campo metadata a fin de mostrar información adicional sobre el elemento mostrado que puede ser relevante para los usuarios. El campo metadata incluye createTime y updateTime del elemento, así como cualquier dato estructurado, que se pueda mostrar, asociado al elemento.

Para mostrar los datos estructurados, usa el campo displayOptions. El campo displayOptions contiene la etiqueta de visualización para el tipo de objeto y un conjunto de metalines. Cada metalínea es un arreglo de etiquetas de visualización y pares de valor configurados en el esquema.

Recupera resultados adicionales

A fin de recuperar resultados adicionales, debes configurar el campo start en la solicitud para la compensación deseada. Puedes ajustar el tamaño de cada página con el campo pageSize.

A fin de mostrar el número de elementos mostrados o los controles de paginación para paginar los elementos mostrados, debes usar el campo resultCount. Se proporciona un valor estimado o real según el tamaño del conjunto de resultados.

Ordena los resultados

Usa el campo sortOptions para especificar el orden de los elementos mostrados. El valor sortOptions es un objeto con dos campos:

  • operatorName: un operador para ordenar la propiedad de los datos estructurados. Para las propiedades con operadores múltiples, solo puedes ordenar con el operador de igualdad principal
  • sortOrder: la dirección en la que se debe ordenar, ya sea ASCENDING o DESCENDING

La relevancia también se usa como la clave de orden secundaria. Si no se especifica ningún orden en una consulta, los resultados se clasifican solo por relevancia.

"sortOptions": {
      "operatorName": "priority",
      "sortOrder": "DESCENDING"
    }
    

Agrega filtros

Además de las expresiones de la consulta, puedes restringir aún más los resultados si aplicas filtros. Puedes especificar filtros en la aplicación de búsqueda o en la solicitud de búsqueda.

Para agregar filtros en una solicitud o aplicación de búsqueda, se deben añadir en el campo dataSourceRestrictions.filterOptions[].

Hay 2 formas principales de filtrar aún más una fuente de datos:

  • Filtros de objeto, a través de la propiedad filterOptions[].objectType: restringe los elementos coincidentes al tipo específico como se define en el esquema personalizado.
  • Filtros de valor: restringe los elementos coincidentes en función de un operador de consulta y el valor suministrado.

Los filtros compuestos permiten combinar los filtros de varios valores en expresiones lógicas para consultas más complejas.

En el ejemplo del esquema de película, puedes aplicar una restricción de edad según el usuario actual y restringir las películas disponibles en función de la clasificación MPAA.

{
      "query": "adventure",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>"
      },
      "dataSourceRestrictions": [
        {
          "source": {
            "name": "datasources/<data_source_id>"
          },
          "filterOptions": [
            {
              "objectType": "movie",
              "filter": {
                "compositeFilter": {
                  "logicOperator": "AND"
                  "subFilters": [
                    {
                      "compositeFilter": {
                      "logicOperator": "OR"
                      "subFilters": [
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "G"
                            }
                          }
                        },
                        {
                          "valueFilter": {
                            "operatorName": "rated",
                            "value": {
                              "stringValue": "PG"
                            }
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          ]
        }
      ]
    }
    

Define mejor los resultados con facetas

Las facetas son propiedades indexadas que representan categorías para definir mejor los resultados de la búsqueda. Usa las facetas para ayudar a los usuarios a definir mejor sus consultas de manera interactiva y encontrar elementos relevantes más rápido.

Las facetas se pueden definir en tu aplicación de búsqueda y se pueden anular mediante la configuración en la consulta.

Cuando se solicitan facetas, Cloud Search calcula los valores más frecuentes para las propiedades solicitadas entre los elementos coincidentes. Estos valores se muestran en la respuesta. Usa estos valores para construir filtros que limiten los resultados en consultas posteriores.

El patrón de interacción típico con las facetas es el siguiente:

  1. Realiza una consulta inicial y especifica qué propiedades se deben incluir en los resultados de faceta.
  2. Procesa los resultados de faceta y búsqueda.
  3. El usuario selecciona uno o más valores de facetas para definir mejor los resultados.
  4. Repite la consulta con un filtro basado en los valores seleccionados.

Por ejemplo, para habilitar el perfeccionamiento de las consultas de películas por año y la calificación MPAA, debes incluir la propiedad facetOptions en la consulta.

"facetOptions": [
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "year"
      },
      {
        "sourceName": "datasources/<data_source_id>",
        "operatorName": "rated"
      }
    ]
    

Interpreta los depósitos de facetas

La propiedad facetResults en la respuesta incluye una entrada para cada propiedad solicitada. Para cada propiedad, se proporciona una lista de valores o rangos, llamados buckets. Los valores más frecuentes aparecen primero.

Cuando un usuario selecciona uno o más valores para filtrar, construye una consulta nueva con los filtros seleccionados y vuelve a consultar la API.

Agrega sugerencias

Usa la API sugerida para autocompletar consultas en función del historial de consultas del usuario, así como los contactos y sus corpus de documentos.

Por ejemplo, la llamada siguiente ofrece sugerencias para la frase parcial jo.

{
      "query": "jo",
      "requestOptions": {
        "searchApplicationId": "<search_app_id>",
        "peoplePhotoOptions": {
          "peoplePhotoUrlSizeInPx": 32
        },
        "timeZone": "America/Denver"
      }
    }
    

Luego, puedes mostrar las sugerencias resultantes según corresponda para tu aplicación.