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 Cómo crear 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 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 con cada interfaz de búsqueda que crees. Una aplicación de búsqueda proporciona la configuración parámetros para una consulta, como las fuentes de datos que se usarán, el orden de filtros y 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 Personaliza la experiencia de búsqueda en Cloud Search.

Genera credenciales OAuth para la aplicación

Además de los pasos en Configurar el acceso a la API de Google Cloud Search, También debes generar credenciales de 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 se solicite autorización.

Para obtener información adicional sobre las opciones de OAuth y las bibliotecas cliente, consulta [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.

Consulta el índice

Usa la search. para realizar búsquedas en el índice.

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

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 como así como un enlace al elemento original. Puedes mejorar aún más la visualización de de los resultados de la búsqueda aprovechando la información adicional que aparece en los resultados de la búsqueda como el fragmento y los metadatos.

Controla los resultados complementarios

De forma predeterminada, Cloud Search devuelve resultados complementarios cuando hay no hay resultados insuficientes para la consulta del usuario. El queryInterpretation en la respuesta indica cuándo se devuelven resultados complementarios. Si tan solo se muestran resultados complementarios, InterpretationType está configurado como REPLACE. Si se devuelven algunos resultados para la consulta original junto con resultados, InterpretationType se establece en BLEND. En cualquier caso QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY

Cuando se devuelvan algunos resultados complementarios, considera proporcionar texto para indicar que se devolvieron resultados complementarios. Por ejemplo, en el caso de una REPLACE, puedes mostrar la cadena “Tu búsqueda de tu consulta original” no coincide con ningún resultado. Se muestran los resultados de búsquedas similares”.

En el caso de un BLEND, puedes mostrar la cadena "Your search for your búsqueda original no coincidió con suficientes resultados. Se incluyen resultados de búsquedas similares consultas”.

Administra los resultados de personas

Cloud Search devuelve dos tipos de “resultados de personas”: documentos relacionados con un persona cuyo nombre se usa en la consulta e información de empleados de una persona cuyo nombre se usa en una consulta. El último tipo de resultado es una función de Cloud la función Búsqueda de personas de la Búsqueda y los resultados para esa consulta pueden encontrarse en el structuredResults campo de una respuesta de la API de consulta:

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

Coincidencia de informes directos

La coincidencia de informes directos es una función de búsqueda de personas de Cloud Search que los usuarios ven los subordinados directos de una persona en su organización. El resultado está disponible en el campo structuredResults.

Para las consultas sobre el gerente o los subordinados directos de una persona, la respuesta tiene un assistCardProtoHolder en structuredResults. El assistCardProtoHolder tiene un campo llamado cardType que será igual a RELATED_PEOPLE_ANSWER_CARD El assistCardProtoHolder contiene una tarjeta llamada relatedPeopleAnswerCard, que contiene la respuesta real. Contiene el subject (la persona que se incluyó en la consulta) y relatedPeople, que es el conjunto de personas relacionadas con el tema. El El campo relationType muestra el valor MANAGER o DIRECT_REPORTS.

El siguiente código muestra un ejemplo de respuesta para una coincidencia de subordinados directos consulta:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

Desactivar las optimizaciones, incluidos los resultados complementarios

De forma predeterminada, las optimizaciones, como los resultados complementarios, están habilitadas. Puedes hacer lo siguiente: pero desactiva todas las optimizaciones o solo los resultados complementarios de la app de búsqueda y el nivel de la consulta:

• Para desactivar todas las optimizaciones en el nivel de la aplicación de búsqueda, incluidas incluidos resultados complementarios, sinónimos y correcciones ortográficas, establece QueryInterpretationConfig.force_verbatim_mode a true en las aplicaciones de búsqueda.

• Para desactivar todas las optimizaciones a nivel de la búsqueda, incluidas resultados complementarios, sinónimos y correcciones ortográficas, establecer QueryInterpretationOptions.enableVerbatimMode a true en la búsqueda.

• Para desactivar los resultados complementarios a nivel de la aplicación de búsqueda, establece QueryInterpretationOptions.forceDisableSupplementalResults a true en la búsqueda.

• Para desactivar los resultados complementarios a nivel de la búsqueda, establece QueryInterpretationOptions.disableSupplementalResults a true en la búsqueda.

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 el elemento matchRanges para destacar el texto coincidente durante la renderización. los resultados. El siguiente ejemplo de JavaScript convierte el fragmento en 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 la metadata. para mostrar información adicional sobre el artículo devuelto que pueda ser relevante para los usuarios. El campo metadata incluye createTime y updateTime del elemento, así como cualquier dato estructurado que se pueda mostrar y asociado con el elemento.

Para mostrar los datos estructurados, usa 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 array de etiquetas de visualización y pares de valores configurados en el esquema.

Recupera resultados adicionales

Para recuperar resultados adicionales, establece start de la solicitud para la compensación deseada. Puedes ajustar el tamaño de cada página con el elemento pageSize .

Para mostrar la cantidad de elementos devueltos o los controles de paginación en paginar los artículos devueltos, usa el resultCount . Se proporciona un valor estimado o real según el tamaño del conjunto de resultados.

Ordenar resultados

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

• operatorName: Es 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: Es 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 el aplicación de búsqueda y en la solicitud de búsqueda.

Para agregar filtros en una solicitud o aplicación de búsqueda, agrega el filtro en 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: restricciones elementos coincidentes con el tipo especificado, según se define en un esquema personalizado.
• Filtros de valor — restringe los elementos coincidentes según un operador de consulta y el valor proporcionado.

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 anulada por la configuración en tu 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:

1. Realiza una consulta inicial y especifica qué propiedades 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 búsquedas de películas por año y por la calificación MPAA Incluye la propiedad facetOptions en la consulta.

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

Resultados de facetas con campos basados en números enteros

También puedes agregar facetas a los resultados de la solicitud con campos basados en números enteros. Por ejemplo, Es posible que marques una propiedad de número entero llamada book_pages como faceta para definir mejor resultados para una búsqueda de libros con "100-200" páginas.

Cuando configures tu esquema de campo de propiedad de número entero, establece isFacetable en true y agrega las opciones de agrupamiento correspondientes al integerPropertyOptions Esto garantiza que cada propiedad de facetas de números enteros tenga agrupamiento predeterminado las opciones definidas.

Cuando definas la lógica de las opciones de agrupamiento, proporciona un array de valores incrementales que representan rangos. Por ejemplo, si el usuario final especifica rangos 2, 5, 10, 100, luego, facetas para <2, [2-5), [5-10), [10-100), >=100 calcular.

Puedes anular las facetas basadas en números enteros si defines las mismas opciones de agrupamiento para facetOptions en la solicitud. Si es necesario, Cloud Search usa las opciones de agrupamiento definidas en el esquema cuando ni la aplicación de búsqueda ni la solicitud de consulta tienen facetas las opciones definidas. Las facetas definidas en la consulta tienen prioridad sobre las facetas definidas. en la aplicación de búsqueda, y las facetas definidas en la aplicación de búsqueda toman prioridad sobre las facetas definidas en el esquema.

Resultados de facetas por tamaño o fecha del documento

Puedes usar operadores reservados para definir mejor los resultados de la búsqueda por tamaño de archivo del documento, medido en bytes o por cuándo se creó o modificó un documento. No es necesario definir un esquema personalizado, pero sí debes especificar el valor operatorName en el archivo FacetOptions

• Para la creación de facetas por tamaño de documento, usa itemsize y define las opciones de agrupamiento.
• Para aplicar facetas por fecha de creación del documento, usa createddatetimestamp.
• Para aplicar facetas por fecha de modificación del documento, usa lastmodified.

Interpreta los depósitos de facetas

La facetResults en la respuesta de la búsqueda incluye la solicitud de filtro exacta del usuario en el campo filter de cada bucket

Para las facetas que no se basan en números enteros, facetResults incluye una entrada para cada propiedad solicitada. Para cada propiedad, una lista de valores o rangos, llamada buckets. Los valores más frecuentes aparecen primero.

Cuando un usuario selecciona uno o más valores para filtrar, construye una nueva consulta 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 siguiente llamada 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.