Method: query.search

La API de Cloud Search Query proporciona el método de búsqueda, que muestra los resultados más relevantes de la consulta de un usuario. Los resultados pueden provenir de aplicaciones de Google Workspace, como Gmail o Google Drive, o de datos que usted indexó de un tercero.

Nota: Para ejecutarse esta API, se requiere una cuenta de usuario final estándar. Una cuenta de servicio no puede realizar solicitudes a la API de Query directamente. Si quieres usar una cuenta de servicio para realizar consultas, debes configurar la delegación de autoridad de 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 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)

Opciones de solicitud, como la aplicación de búsqueda y la zona horaria del usuario
query

string

La cadena de consulta sin procesar. Para conocer los operadores de búsqueda compatibles, consulta el artículo Limita tu búsqueda con operadores
pageSize

integer

Cantidad máxima de resultados de la búsqueda que se mostrarán en una página. Los valores válidos están entre 1 y 100, inclusive. El valor predeterminado es 10. El valor mínimo es 50 cuando se solicitan resultados superiores a 2,000.
start

integer

Índice inicial de los resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

Las fuentes que se usarán para las consultas. 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)

Las opciones para ordenar los resultados de la búsqueda
queryInterpretationOptions

object (QueryInterpretationOptions)

para interpretar la consulta del usuario.
contextAttributes[]

object (ContextAttribute)

Atributos de contexto para la solicitud que se utilizará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

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

Es la respuesta de la API de búsqueda.

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)

Resultado de la interpretación de consultas de la consulta del usuario. Estará vacío si la interpretación de consultas está inhabilitada.
results[]

object (SearchResult)

Resultados de una búsqueda.
structuredResults[]

object (StructuredResult)

Resultados estructurados para la consulta del usuario. Estos resultados no se toman en cuenta para pageSize.
spellResults[]

object (SpellResult)

Ortografía sugerida para la consulta.
facetResults[]

object (FacetResult)

Resultados de facetas repetidas
hasMoreResults

boolean

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

object (ResponseDebugInfo)

Información de depuración sobre la respuesta.
errorInfo

object (ErrorInfo)

Información de error sobre la respuesta.
resultCounts

object (ResultCounts)

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

Campo de unión result_count. Recuento total de resultados en todas las fuentes de datos solicitadas. Se omite si se incluyen fuentes predefinidas en el conjunto de fuentes de datos consultadas. Los recuentos de resultados se pueden mostrar como una estimación, en lugar de ser exactos, en las siguientes circunstancias:

  • Cuando la consulta tiene más de 2 términos en una frase, como “cantidad exacta de resultados” entre comillas.

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

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

string (int64 format)

El recuento de resultados estimado para esta consulta.
resultCountExact

string (int64 format)

El recuento de resultados exactos para esta consulta.

Alcances de la autorización

Se necesita uno de los siguientes alcances 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

para interpretar la consulta del usuario.

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

boolean

Marca para inhabilitar la interpretación de consultas en lenguaje natural (NL). El valor predeterminado es falso. Configúralo como verdadero para inhabilitar la interpretación de lenguaje natural. La interpretación de NL solo se aplica a las fuentes de datos predefinidas.
enableVerbatimMode

boolean

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

boolean

Usa esta marca para inhabilitar los resultados complementarios en una consulta. Si se establece como verdadera, prevalecerá la configuración de resultados complementarios a nivel de SearchApplication.

QueryInterpretation

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

string

La interpretación de la consulta usada en la búsqueda. Por ejemplo, las consultas con una intención de lenguaje natural como "correo electrónico de juan" se interpretarán como "from:juan fuente:correo". Este campo no se completará cuando el motivo sea NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

El motivo de la interpretación de la consulta. Este campo no será UNSPECIFIED si el tipo de interpretación no es NINGUNO.

QueryInterpretation.InterpretationType

Enumeradores
NONE No se usa la interpretación de lenguaje natural ni una versión más amplia de la consulta para recuperar los resultados de la búsqueda.
BLEND Los resultados de la consulta original se mezclan con otros resultados. El motivo para combinar estos otros resultados con los resultados de la consulta original se completa en el campo "Motivo" a continuación.
REPLACE Se reemplazan los resultados de la consulta original. El motivo para reemplazar los resultados de la consulta original se completa en el campo "Motivo" que aparece a continuación.

QueryInterpretation.Reason

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

SearchResult

Resultados que contienen información indexada de un documento.

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

string

Es el título del resultado de la búsqueda.
url

string

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

object (Snippet)

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

object (Metadata)

metadatos del resultado de búsqueda.
clusteredResults[]

object (SearchResult)

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

object (ResultDebugInfo)

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

Fragmento

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. Es el fragmento del documento. Puede contener un carácter HTML de escape al que se le debe quitar el carácter de escape antes de la renderización.
matchRanges[]

object (MatchRange)

Los rangos coincidentes en el fragmento

MatchRange

Rango coincidente de un fragmento [inicio, fin].

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

integer

Posición inicial de la coincidencia en el fragmento.
end

integer

Fin de la coincidencia en el fragmento.

Metadata

metadatos de un resultado de 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)

La fuente con nombre del resultado, como Gmail.
mimeType

string

Es el tipo MIME del resultado de la búsqueda.
thumbnailUrl

string

La URL en miniatura del resultado.
owner

object (Person)

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

string (Timestamp format)

La hora de creación de este objeto o documento en el resultado de la búsqueda.

Una marca de tiempo en formato RFC3339 UTC "Zulú", con resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

La fecha de la última modificación del objeto en el resultado de la búsqueda. Si no se configura en el elemento, el valor que se muestra aquí estará vacío. Si se usa updateTime para calcular la actualidad y no se establece, este valor se establece de forma predeterminada en 2 años a partir de la hora actual.

Una marca de tiempo en formato RFC3339 UTC "Zulú", con resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Campos indexados en datos estructurados que se muestran como una propiedad genérica con nombre.
displayOptions

object (ResultDisplayMetadata)

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

La etiqueta de visualización del objeto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

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

ResultDisplayMetadata.ResultDisplayLine

El conjunto de campos que conforman una línea que se muestra

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Mostrar campos para los resultados de query.search

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

string

Es la etiqueta de visualización de la propiedad.
operatorName

string

El nombre del operador de la propiedad.
property

object (NamedProperty)

Es el par de valor y nombre de la propiedad.

ResultDebugInfo

Información de depuración sobre el resultado.

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

string

Es la información de depuración general con formato para la visualización.

StructuredResult

Resultados estructurados que se muestran como parte de la solicitud de búsqueda.

Representación JSON 
{
  "person": {
    object (Person)
  }
}
Campos
person

object (Person)

Representación de una persona

SpellResult

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

string

La ortografía sugerida de la consulta.

FacetResult

Respuesta de faceta específica de la fuente

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

string

Nombre de la fuente para la que se muestran resultados de faceta. No estará vacío.
objectType

string

Tipo de objeto para el que se muestran resultados de faceta. Puede estar vacío.
operatorName

string

El nombre del operador elegido para la faceta. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets para valores en una respuesta que contiene al menos un solo resultado con el filtro correspondiente.

FacetBucket

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

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

integer

Cantidad de resultados que coinciden con el valor del bucket. Los recuentos solo se muestran para las búsquedas cuando se garantiza su precisión. Cloud Search no garantiza recuentos de facetas para ninguna consulta, y puede que estos recuentos solo estén presentes de manera intermitente, incluso en consultas idénticas. No compiles dependencias sobre la existencia del recuento de facetas. En su lugar, usa porcentajes de ondas de facetas que siempre se muestran.
percentage

integer

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

object (Filter)

Filtro que se pasará en la solicitud de búsqueda si se selecciona el bucket correspondiente.
value

object (Value)

ResponseDebugInfo

Información de depuración sobre la respuesta.

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

string

Es la información de depuración general con formato para la visualización.

ErrorInfo

Información de error sobre la respuesta.

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

object (ErrorMessage)

ErrorMessage

Mensaje de error por respuesta de origen.

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)

Información sobre el recuento de resultados para cada fuente con resultados.

SourceResultCount

Información de 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)

La fuente con la que está asociada 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 estimado para esta fuente.
resultCountExact

string (int64 format)

El recuento de resultados exacto de esta fuente.