Method: query.search

La API de Cloud Search Query proporciona el método de búsqueda, que devuelve los resultados más relevantes de una búsqueda del usuario. Los resultados pueden provenir de apps de Google Workspace, como Gmail o Google Drive, o de datos que indexaste de un tercero.

Nota: Esta API requiere una cuenta de usuario final estándar para ejecutarse. Una cuenta de servicio no puede realizar solicitudes a la API de consulta directamente. Para usar una cuenta de servicio para realizar consultas, configura la delegación de autoridad en todo el dominio de Google Workspace.

Solicitud HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

La URL usa la sintaxis de la transcodificación de gRPC.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Campos
requestOptions

object (RequestOptions)

Son las opciones de solicitud, como la aplicación de búsqueda y la zona horaria del usuario.
query

string

Es la cadena de consulta sin procesar. Consulta los operadores de búsqueda admitidos en Cómo definir mejor tu búsqueda con operadores
pageSize

integer

Es la cantidad máxima de resultados de la búsqueda que se devolverán en una página. Los valores válidos están entre 1 y 100, ambos incluidos. El valor predeterminado es 10. El valor mínimo es 50 cuando se solicitan resultados más allá de 2,000.
start

integer

Índice inicial de los resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

Son las fuentes que se usarán para la consulta. Si no se especifica, se usan todas las fuentes de datos de la aplicación de búsqueda actual.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Opciones para ordenar los resultados de la búsqueda
queryInterpretationOptions

object (QueryInterpretationOptions)

Son opciones para interpretar la búsqueda del usuario.
contextAttributes[]

object (ContextAttribute)

Son los atributos de contexto de la solicitud que se usarán para ajustar la clasificación de los resultados de la búsqueda. La cantidad máxima de elementos es 10.

Cuerpo de la respuesta

Es la respuesta de la API de búsqueda. ID SIGUIENTE: 19

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "queryInterpretation": {
    object (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Campos
queryInterpretation

object (QueryInterpretation)

Es el resultado de la interpretación de la búsqueda del usuario. Estará vacío si la interpretación de la búsqueda está inhabilitada.
results[]

object (SearchResult)

Son los resultados de una búsqueda.
structuredResults[]

object (StructuredResult)

Son los resultados estructurados de la búsqueda del usuario. Estos resultados no se incluyen en el recuento de pageSize.
spellResults[]

object (SpellResult)

Es la ortografía sugerida para la búsqueda.
facetResults[]

object (FacetResult)

Son los resultados de facetas repetidos.
hasMoreResults

boolean

Indica si hay más resultados de la búsqueda que coinciden con la búsqueda.
debugInfo

object (ResponseDebugInfo)

Es información de depuración sobre la respuesta.
errorInfo

object (ErrorInfo)

Es la información del error sobre la respuesta.
resultCounts

object (ResultCounts)

Se expandió la información del recuento de resultados.

Campo de unión result_count. Es el recuento total de resultados en todas las fuentes de datos solicitadas. Se omite si las fuentes predefinidas se incluyen en el conjunto de fuentes de datos consultadas. En las siguientes circunstancias, es posible que los recuentos de resultados se muestren como una estimación en lugar de un valor exacto:

  • Cuando la búsqueda tiene más de 2 términos en una frase, como "recuento de resultados exacto" entre comillas.

  • Cuando la cantidad de LCA de resultados de la búsqueda únicos que se deben evaluar es demasiado grande para calcularse dentro de una latencia razonable.

En el caso poco frecuente en que el sistema no pueda buscar en todos los documentos, vuelve a ejecutar la búsqueda. result_count puede ser una de las siguientes opciones:
resultCountEstimate

string (int64 format)

Es el recuento de resultados estimado para esta búsqueda.
resultCountExact

string (int64 format)

Es el recuento exacto de resultados para esta búsqueda.

Permisos de autorización

Se necesita uno de los siguientes permisos de OAuth:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

Para obtener más información, consulta la Guía de autorización.

QueryInterpretationOptions

Opciones para interpretar la búsqueda del usuario.

Representación JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Campos
disableNlInterpretation

boolean

Es una marca para inhabilitar la interpretación de lenguaje natural (LN) de las búsquedas. El valor predeterminado es falso. Se debe establecer en verdadero para inhabilitar la interpretación del lenguaje natural. La interpretación del lenguaje natural solo se aplica a las fuentes de datos predefinidas.
enableVerbatimMode

boolean

Habilita esta marca para desactivar todas las optimizaciones internas, como la interpretación en lenguaje natural (LN) de las búsquedas, la recuperación de resultados complementarios y el uso de sinónimos, incluidos los personalizados. La interpretación del NL se inhabilitará si cualquiera de las dos marcas es verdadera.
disableSupplementalResults

boolean

Usa esta marca para inhabilitar los resultados complementarios de una búsqueda. El parámetro de configuración de resultados complementarios elegido a nivel de SearchApplication tendrá prioridad si se establece en verdadero.

QueryInterpretation

Representación JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
Campos
interpretedQuery

string

Es la interpretación de la búsqueda que se usa en la búsqueda. Por ejemplo, las búsquedas con intención de lenguaje natural, como "correo electrónico de Juan", se interpretarán como "from:juan source:mail". Este campo no se completará cuando el motivo sea NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Es el motivo de la interpretación de la búsqueda. Este campo no será UNSPECIFIED si el tipo de interpretación no es NONE.
interpretedQueryActualResultCount

integer

Es la cantidad real de resultados que devuelve la búsqueda interpretada.
interpretedQueryEstimatedResultCount

string (int64 format)

Es la cantidad estimada de resultados que devuelve la búsqueda interpretada.

QueryInterpretation.InterpretationType

Enums
NONE Ni la interpretación en lenguaje natural ni una versión más amplia de la búsqueda se usan para recuperar los resultados de la búsqueda.
BLEND Los resultados de la búsqueda original se combinan con otros resultados. El motivo por el que se combinan estos otros resultados con los de la búsqueda original se completa en el campo "reason" que se muestra a continuación.
REPLACE Se reemplazan los resultados de la búsqueda original. El motivo por el que se reemplazaron los resultados de la búsqueda original se completa en el campo "reason" que se muestra a continuación.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT La interpretación en lenguaje natural de la búsqueda se usa para recuperar los resultados de la búsqueda.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La similitud entre los términos de la búsqueda y los del documento se usa para ampliar la búsqueda de forma selectiva y recuperar resultados adicionales, ya que no se encontraron suficientes resultados para la búsqueda del usuario. La consulta interpretada estará vacía en este caso.

SearchResult

Son los resultados que contienen información indexada para un documento. ID siguiente: 16

Representación JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Campos
title

string

Título del resultado de la búsqueda.
url

string

Es la URL del resultado de la búsqueda. La URL contiene un redireccionamiento de Google al elemento real. Esta URL está firmada y no se debe cambiar.
snippet

object (Snippet)

Es la concatenación de todos los fragmentos (resúmenes) disponibles para este resultado.
metadata

object (Metadata)

son los metadatos del resultado de la búsqueda.
clusteredResults[]

object (SearchResult)

Si la fuente está agrupada, proporciona una lista de los resultados agrupados. Solo habrá un nivel de resultados agrupados. Si la fuente actual no está habilitada para el agrupamiento, este campo estará vacío.
debugInfo

object (ResultDebugInfo)

Es la información de depuración sobre este resultado de la búsqueda.

Fragmento

Es el fragmento del resultado de la búsqueda, que resume el contenido de la página resultante.

Representación JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Campos
snippet

string

Es el fragmento del documento. Puede contener caracteres HTML escapados que se deben no escapar antes de la renderización.
matchRanges[]

object (MatchRange)

Son los rangos coincidentes en el fragmento.

MatchRange

Es el rango coincidente de un fragmento [inicio, fin).

Representación JSON 
{
  "start": integer,
  "end": integer
}
Campos
start

integer

Es la posición inicial de la coincidencia en el fragmento.
end

integer

Es el final del partido en el fragmento.

Metadatos

Son los metadatos de un resultado de la búsqueda coincidente.

Representación JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Campos
source

object (Source)

Es la fuente con nombre del resultado, como Gmail.
mimeType

string

Tipo de MIME del resultado de la búsqueda.
thumbnailUrl

string

Es la URL de la miniatura del resultado.
owner

object (Person)

Propietario (por lo general, el creador) del documento o del objeto del resultado de la búsqueda.
createTime

string (Timestamp format)

Es la fecha y hora de creación de este documento u objeto en el resultado de la búsqueda.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Es la fecha de modificación más reciente del objeto en el resultado de la búsqueda. Si no se configura en el elemento, el valor que se devuelve aquí está vacío. Cuando se usa updateTime para calcular la actualización y no se configura, este valor se establece de forma predeterminada en 2 años a partir de la hora actual.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

Son los campos indexados en los datos estructurados, que se devuelven como una propiedad genérica con nombre.
displayOptions

object (ResultDisplayMetadata)

Son opciones que especifican cómo mostrar un resultado de la búsqueda de datos estructurados.
objectType

string

Es el tipo de objeto del resultado de la búsqueda.

ResultDisplayMetadata

Representación JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Campos
objectTypeLabel

string

Es la etiqueta visible del objeto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Es el contenido de las metalíneas que se mostrará con el resultado.

ResultDisplayMetadata.ResultDisplayLine

Es la colección de campos que componen una línea mostrada.

Representación JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Campos
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Campos de visualización para los resultados de query.search

Representación JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Campos
label

string

Es la etiqueta visible de la propiedad.
operatorName

string

Es el nombre del operador de la propiedad.
property

object (NamedProperty)

Es el par clave-valor de la propiedad.

ResultDebugInfo

Es información de depuración sobre el resultado.

Representación JSON 
{
  "formattedDebugInfo": string
}
Campos
formattedDebugInfo

string

Es información de depuración general con formato para mostrar.

StructuredResult

Son los resultados estructurados que se muestran como parte de la solicitud de búsqueda.

Representación JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Campos

Campo de unión structured_result.

structured_result puede ser una de las siguientes opciones:
person

object (Person)

Representación de una persona

SpellResult

Representación JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Campos
suggestedQuery

string

Es la ortografía sugerida de la búsqueda.
suggestionType

enum (SpellResult.SuggestionType)

Es la sugerencia que se activó para la búsqueda actual.
suggestedQueryHtml

object (SafeHtmlProto)

Es el código HTML sanitizado que representa la consulta con la ortografía corregida y que se puede usar en la IU. Por lo general, tiene etiquetas específicas del idioma para marcar partes de la búsqueda que se verifican ortográficamente.

SpellResult.SuggestionType

Es el tipo de sugerencia que se activó para la búsqueda.

Enums
SUGGESTION_TYPE_UNSPECIFIED Tipo de revisión ortográfica predeterminado
NON_EMPTY_RESULTS_SPELL_SUGGESTION Se cambió la sugerencia ortográfica sin ningún resultado. Los resultados se siguen mostrando para la búsqueda original (que tiene resultados distintos de cero) con una sugerencia de ortografía que tendría resultados.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Sugerencia de corrección ortográfica que se activa cuando la búsqueda original no arroja resultados. Cuando la búsqueda original no tiene resultados y la sugerencia de corrección ortográfica sí, activamos los resultados para la búsqueda corregida.

SafeHtmlProto

IMPORTANTE: No es seguro aceptar este mensaje de una fuente no confiable, ya que es trivial para un atacante falsificar mensajes serializados que no cumplen con el contrato de seguridad del tipo. Por ejemplo, podría contener una secuencia de comandos controlada por el atacante. Un sistema que recibe un SafeHtmlProto confía implícitamente en el productor del SafeHtmlProto. Por lo tanto, en general, es seguro devolver este mensaje en las respuestas de RPC, pero no es seguro aceptarlo en las solicitudes de RPC.

Representación JSON 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
Campos
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

IMPORTANTE: Nunca establezcas ni leas este campo, ni siquiera desde las pruebas, ya que es privado. Consulta la documentación en la parte superior del archivo .proto para obtener información sobre los paquetes de lenguajes de programación con los que se puede crear o leer este mensaje.

FacetResult

Respuesta de faceta específica de la fuente

Representación JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Campos
sourceName

string

Es el nombre de la fuente para la que se devuelven los resultados de la faceta. No estará vacío.
objectType

string

Es el tipo de objeto para el que se devuelven los resultados de la faceta. Puede estar vacío.
operatorName

string

Es el nombre del operador elegido para la segmentación. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets para los valores de la respuesta que contiene al menos un resultado con el filtro correspondiente.

FacetBucket

Un bucket en una faceta es la unidad básica de operación. Un discretizador puede comprender un solo valor O un rango contiguo de valores, según el tipo de campo discretizado. Actualmente, FacetBucket solo se usa para devolver el objeto de respuesta.

Representación JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Campos
count

integer

Es la cantidad de resultados que coinciden con el valor del bucket. Los recuentos solo se devuelven para las búsquedas cuando se garantiza la precisión del recuento. Cloud Search no garantiza los recuentos de facetas para ninguna búsqueda, y es posible que los recuentos de facetas solo estén presentes de forma intermitente, incluso para búsquedas idénticas. No compiles dependencias en la existencia del recuento de facetas; en su lugar, usa los porcentajes de recuento de facetas que siempre se devuelven.
percentage

integer

Es el porcentaje de resultados que coinciden con el valor del bucket. El valor que se muestra está entre (0 y 100], y se redondea hacia abajo a un número entero si es fraccionario. Si el valor no se devuelve de forma explícita, representa un valor porcentual que se redondea a 0. Los porcentajes se muestran para todas las búsquedas, pero son una estimación. Dado que siempre se devuelven porcentajes, debes renderizar porcentajes en lugar de recuentos.
filter

object (Filter)

Es el filtro que se pasará en la solicitud de búsqueda si se selecciona el bucket correspondiente.
Campo de unión bucket_value. El rango o el valor de la discretización en la que se aplica la faceta bucket_value solo puede ser uno de los siguientes:
value

object (Value)

ResponseDebugInfo

Es información de depuración sobre la respuesta.

Representación JSON 
{
  "formattedDebugInfo": string
}
Campos
formattedDebugInfo

string

Es información de depuración general con formato para mostrar.

ErrorInfo

Es la información del error sobre la respuesta.

Representación JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Campos
errorMessages[]

object (ErrorMessage)

ErrorMessage

Es el mensaje de error por respuesta de la fuente.

Representación JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Campos
source

object (Source)
errorMessage

string

ResultCounts

Información sobre el recuento de resultados

Representación JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Campos
sourceResultCounts[]

object (SourceResultCount)

Es la información del recuento de resultados para cada fuente con resultados.

SourceResultCount

Es la información del recuento de resultados por fuente.

Representación JSON 
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Campos
source

object (Source)

Es la fuente con la que se asocia la información del recuento de resultados.
hasMoreResults

boolean

Indica si hay más resultados de la búsqueda para esta fuente.

Campo de unión result_count.

result_count puede ser una de las siguientes opciones:
resultCountEstimate

string (int64 format)

Es el recuento de resultados estimados para esta fuente.
resultCountExact

string (int64 format)

Es el recuento exacto de resultados para esta fuente.