Crear una interfaz de búsqueda con la API Query

La API Query proporciona métodos de búsquedas y sugerencias para crear una interfaz de búsqueda o para insertar resultados de búsqueda en una aplicación.

En aplicaciones web con requisitos mínimos, puedes usar el widget de la Búsqueda. Para obtener más información, consulta el capítulo Crear una interfaz de búsqueda con el widget de la Búsqueda.

Crear una interfaz de búsqueda

Para crear una interfaz de búsqueda básica, debes llevar a cabo estos pasos:

  1. Configurar una aplicación de búsqueda.
  2. Generar credenciales de OAuth para asignarlas a la aplicación.
  3. Consultar el índice.
  4. Mostrar los resultados de la consulta.

Puedes mejorar la interfaz de búsqueda con funciones como paginación, ordenación, filtrado, creación de facetas y sugerencias automáticas.

Configurar una aplicación de búsqueda

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

Para obtener más información sobre las aplicaciones de búsqueda, consulta el artículo Crear una experiencia de búsqueda personalizada.

Generar credenciales de OAuth para asignarlas a la aplicación

Además de seguir los pasos especificados en el capítulo Configurar el acceso a la API REST de Google Cloud Search, también deberás generar credenciales de OAuth para asignarlas a la aplicación web. El tipo de credenciales que crees dependerá del contexto en el que se use la API.

Utiliza las credenciales para solicitar autorización en nombre del usuario. Para ello, usa el ámbito https://www.googleapis.com/auth/cloud_search.query.

Para obtener más información sobre las opciones de OAuth y las bibliotecas de cliente, consulta la plataforma Google Identity.

Consultar el índice

Para realizar búsquedas en el índice, utiliza el método search.

Todas las solicitudes deben incluir dos datos: un elemento query de texto con el que buscar coincidencias y un searchApplicationId que identifique el ID de la aplicación de búsqueda que se usará.

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

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

Mostrar resultados de la consulta

Como mínimo, se espera que las interfaces de búsqueda muestren el title del elemento y un enlace al elemento original. Para mejorar la visualización de los resultados de búsqueda, aprovecha la información adicional que incluyen, como los fragmentos y metadatos.

Destacar fragmentos

Si los elementos devueltos incluyen contenido HTML o texto indexado, se mostrará un fragmento de ese contenido, que servirá para que los usuarios determinen si es relevante.

Si los términos de la consulta están presentes en el fragmento, también se devolverán uno o más intervalos de coincidencias para identificar la ubicación de los términos.

Cuando proceses los resultados, usa matchRanges para destacar el texto que coincide. En el siguiente ejemplo de JavaScript, el fragmento se convierte en etiquetas HTML y los intervalos que coinciden están incluidos dentro de etiquetas <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;
}

En el fragmento siguiente:

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

La cadena HTML resultante es:

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

Mostrar metadatos

Usa el campo metadata para mostrar información adicional del elemento devuelto que pueda ser relevante para los usuarios. El campo metadata incluye los datos createTime y updateTime del elemento, además de datos estructurados que se pueden devolver y que están asociados con el elemento.

Para mostrar los datos estructurados, usa el campo displayOptions. El campo displayOptions contiene la etiqueta de visualización del tipo de objeto y un conjunto de valores metalines. Cada uno de estos valores es una matriz de etiquetas de visualización y pares de valores, según la configuración del esquema.

Recuperar resultados adicionales

Para obtener resultados adicionales, en el campo start de la solicitud define el valor que quieras. Puedes ajustar el tamaño de las páginas con el campo pageSize.

Para mostrar el número de elementos devueltos o los controles de paginación que permiten desplazarse por ellos, usa el campo resultCount. En función del tamaño del conjunto de resultados, se proporcionará el valor real o uno aproximado.

Ordenar los resultados

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

  • operatorName: operador de la propiedad de datos estructurados que se usará para ordenar los resultados. En el caso de propiedades con varios operadores, solo puedes ordenar resultados con el operador de igualdad principal.
  • sortOrder: orden en que se muestran los resultados. Puede ser ASCENDING o DESCENDING.

También se utiliza la relevancia como clave de ordenación secundaria. Si no se especifica ningún orden en una consulta, los resultados se clasificarán solo por la relevancia.

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

Añadir filtros

Además de las expresiones de consulta, puedes restringir más los resultados por medio de filtros. Puedes especificarlos en la solicitud y en la aplicación de búsqueda.

Para especificar filtros en una solicitud o aplicación de búsqueda, añádelos en el campo dataSourceRestrictions.filterOptions[].

Existen dos formas principales de filtrar una fuente de datos:

  • Filtros de objetos a través de la propiedad filterOptions[].objectType: solo se muestran los elementos que coincidan con el tipo especificado en un esquema personalizado.
  • Filtros de valor: solo se muestran los elementos que coincidan con un operador de consulta y un valor proporcionado.

Con los filtros compuestos se pueden combinar varios filtros de valor en expresiones lógicas para conseguir consultas más complejas.

En el ejemplo de esquema de la película, podrías aplicar un límite de edad según el usuario actual y restringir las películas disponibles en función del sistema de calificación por edades.

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

Afinar los resultados con facetas

Las facetas son propiedades indexadas que representan categorías para acotar resultados de búsqueda. Puedes usarlas para permitir a los usuarios afinar sus consultas de forma interactiva y encontrar elementos relevantes más rápido.

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

Cuando se solicitan facetas, Cloud Search calcula los valores más frecuentes de las propiedades solicitadas entre los elementos que coinciden. Estos valores se devuelven en la respuesta. Puedes usarlos para crear filtros que restrinjan los resultados en consultas posteriores.

El patrón habitual de interacción con facetas es el siguiente:

  1. Se hace una consulta inicial en la que se indica qué propiedades se incluirán en los resultados de la faceta.
  2. Se procesan los resultados de la búsqueda y la faceta.
  3. El usuario selecciona uno o varios valores de faceta para acotar los resultados.
  4. Se repite la consulta con un filtro basado en los valores seleccionados.

Por ejemplo, para afinar consultas de películas por año y calificación por edades, incluye la propiedad facetOptions en la consulta.

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

Interpretar segmentos de facetas

La propiedad facetResults de la respuesta incluye una entrada por cada propiedad solicitada. Además, con cada una se proporciona una lista de valores o rangos, llamados "buckets". Los más frecuentes se muestran primero.

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

Añadir sugerencias

Usa la API Suggest para proporcionar la función de Autocompletar en consultas basadas en el historial de consultas personales del usuario, así como los contactos y documentos donde se realizarán las búsquedas.

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

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

A continuación, puedes mostrar las sugerencias resultantes según se requiera en tu aplicación.