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

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

Para aplicaciones web con requisitos mínimos, considera usar el widget de búsqueda. 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 de OAuth para la aplicación.
3. Consulta el índice.
4. Muestra los resultados de la consulta.

Puedes mejorar la interfaz con funciones como paginación, clasificación, filtrado, facetas y autocompletar.

Configura una aplicación de búsqueda

Debes crear al menos una aplicación de búsqueda para cada interfaz de búsqueda. Una aplicación de búsqueda proporciona parámetros predeterminados, como fuentes de datos, orden de clasificación, filtros y facetas. Puedes anular estos parámetros con la API de Query.

No puedes aumentar la cantidad de fuentes de datos que se usan en una consulta más allá de las configuradas en la aplicación de búsqueda. Puedes restringir una búsqueda a un subconjunto de estas fuentes con dataSourceRestrictions.

Nota: Cloud Search actualiza las aplicaciones de búsqueda cuando actualizas o borras un esquema. Por ejemplo, si se cambia el nombre de un operador de esquema, también se cambia en la aplicación de búsqueda. Si una actualización es incompatible, la actualización del esquema falla.

Para obtener más información, consulta Cómo personalizar la experiencia de búsqueda.

Genera credenciales OAuth para la aplicación

Además de los pasos que se indican en Configura el acceso a la API de Cloud Search, debes generar credenciales OAuth para tu aplicación web.

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

Para obtener más información sobre las opciones de OAuth, consulta Google Identity Platform.

Consulta el índice

Usa el método search para buscar en el índice.

Todas las solicitudes deben incluir un query de texto y un searchApplicationId.

En este ejemplo, se consulta una fuente de datos de películas:

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

Muestra los resultados de la consulta

Las interfaces de búsqueda deben mostrar el elemento title y un vínculo al elemento original. También puedes usar fragmentos y metadatos para mejorar la visualización.

Nota: Si no ves resultados, asegúrate de haber creado una aplicación de búsqueda personalizada y de haber habilitado la fuente de datos para ella.

Cómo controlar los resultados complementarios

Cloud Search devuelve resultados complementarios cuando no hay suficientes coincidencias para una búsqueda. Esto se indica en el campo queryInterpretation. Si solo se muestran resultados complementarios, InterpretationType es REPLACE. Si están combinados, es BLEND.

Cuando devuelvas resultados complementarios, considera informar al usuario. En el caso de un REPLACE, podrías decir: "No se encontraron resultados para tu búsqueda. Se muestran resultados para búsquedas similares".

Cómo controlar los resultados de personas

Cloud Search devuelve documentos relacionados con personas y la información de los empleados a través de la función de Búsqueda de personas. Los resultados se encuentran en el campo structuredResults:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Nota: Si defines más de 20 atributos personalizados, la Búsqueda de personas solo usará 20.

Correlación de subordinados directos

La función de correlación de subordinados directos permite a los usuarios ver los subordinados directos de una persona. La respuesta incluye un assistCardProtoHolder con un cardType de RELATED_PEOPLE_ANSWER_CARD.

Desactiva las optimizaciones

Las optimizaciones, como los resultados complementarios, están habilitadas de forma predeterminada. Puedes inhabilitarlas de la siguiente manera:

• Nivel de la aplicación de búsqueda: Establece force_verbatim_mode en true.
• Nivel de la búsqueda: Establece enableVerbatimMode en true.

Destaca los fragmentos

Cloud Search devuelve un fragmento para el texto o el HTML indexados. Si hay términos de búsqueda, matchRanges identifica su ubicación. Usa estos rangos para destacar texto.

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 para obtener información como createTime, updateTime y datos estructurados. Usa displayOptions para mostrar datos estructurados.

Recupera resultados adicionales

Para recuperar más resultados, configura el campo start en la compensación seleccionada. Ajusta el tamaño de la página con pageSize. Usa resultCount para mostrar el total de artículos o los recuentos estimados.

Ordenar resultados

Usa sortOptions para especificar el orden:

• operatorName: Es la propiedad por la que se ordenará.
• sortOrder: ASCENDING o DESCENDING.

La relevancia es la clave de orden predeterminada y secundaria.

Agregar filtros

Restringe los resultados con filtros en la aplicación o solicitud de búsqueda. Si ambos especifican filtros para una fuente, ambos deben evaluarse como verdaderos.

Aplica filtros en dataSourceRestrictions.filterOptions[]. Tipos de filtros principales:

• Filtros de objeto: Restringen las coincidencias a un tipo específico.
• Filtros de valor: Restringen las coincidencias en función de un operador y un valor.

Los filtros compuestos combinan varios filtros de valores.

Define mejor los resultados con facetas

Las facetas ayudan a los usuarios a definir mejor las consultas de forma interactiva. Cuando solicitas facetas, Cloud Search calcula los valores más frecuentes para esas propiedades.

Patrón típico: 1. Es la consulta que especifica las propiedades de la faceta. 1. Procesa los resultados de faceta y búsqueda. 1. El usuario selecciona valores de facetas. 1. Repite la consulta con un filtro basado en las selecciones.

Nota: Solo las propiedades de datos estructurados admiten facetas.

Resultados de facetas con campos basados en números enteros

Marca una propiedad de número entero como facetable para refinar los resultados por rangos (p.ej., "100-200" páginas). Establece isFacetable en true y define las opciones de discretización predeterminadas en el esquema.

Resultados de facetas por tamaño o fecha del documento

Usa operadores reservados:

• itemsize: Para el tamaño del archivo en bytes.
• createddatetimestamp: Para la fecha de creación.
• lastmodified: Para la fecha de modificación.

Agrega sugerencias

Usa la API de sugerencias para autocompletar búsquedas según el historial de búsquedas, los contactos y el contenido de los documentos.