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 en una aplicación.

Para aplicaciones web con requisitos mínimos, considera el uso del 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 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 autocompletado.

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 consulta.

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 consulta 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 cambias el nombre de un operador de esquema, también se cambia en la aplicación de búsqueda. Si una actualización no es compatible, falla la actualización del esquema.

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

Genera credenciales OAuth para la aplicación

Además de los pasos que figuran 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 permiso 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 search método para buscar en el índice.

Cada solicitud debe incluir un texto query 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.

Maneja los resultados complementarios

Cloud Search muestra resultados complementarios cuando no hay suficientes coincidencias para una consulta. El queryInterpretation campo indica esto. Si solo se muestran resultados complementarios, InterpretationType es REPLACE. Si se combinan, es BLEND.

Cuando muestres resultados complementarios, considera informar al usuario. Para un REPLACE, puedes decir: "Tu búsqueda no coincidió con ningún resultado. Se muestran resultados para consultas similares".

Maneja los resultados de personas

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

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

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

Coincidencia de subordinados directos

La Coincidencia 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.

Inhabilita las optimizaciones

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

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

Destaca los fragmentos

Cloud Search muestra un fragmento para el texto indexado o el HTML. Si hay términos de consulta, matchRanges identifica su ubicación. Usa estos rangos para destacar el 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 metadata campo para obtener información como createTime, updateTime y datos estructurados. Usa displayOptions para mostrar datos estructurados.

Recupera resultados adicionales

Para recuperar más resultados, establece el start campo en el desplazamiento seleccionado. Ajusta el tamaño de la página con pageSize. Usa resultCount para mostrar los elementos totales o las cantidades estimadas.

Ordenar resultados

Usa sortOptions para especificar el orden:

• operatorName: 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 de búsqueda o la solicitud. 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 valor.

Define mejor los resultados con facetas

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

Patrón típico: 1. Consulta que especifica las propiedades de faceta. 1. Procesa los resultados de faceta y búsqueda. 1. El usuario selecciona valores de faceta. 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 definir mejor los resultados por rangos (p.ej., páginas "100-200"). Establece isFacetable en true y define las opciones de segmentació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 el autocompletado en función del historial de consultas, los contactos y el contenido del documento.