Method: query.search

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

Nota: Para que se ejecute esta API, se requiere una cuenta de usuario final estándar. Una cuenta de servicio no puede realizar solicitudes a la API de consulta directamente. Si quieres usar una cuenta de servicio para realizar consultas, configura 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. Consulta los operadores de búsqueda admitidos en Acotar la 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 deben estar 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 la consulta. Si no se especifica, se usarán 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 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

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

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 correspondiente a 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 en el valor pageSize.
spellResults[]

object (SpellResult)

Ortografía sugerida para la consulta.
facetResults[]

object (FacetResult)

Resultados de facetas repetidas.
hasMoreResults

boolean

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. El 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 búsqueda 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 la búsqueda únicos para evaluar es demasiado grande para calcularse con una latencia razonable.

En el caso poco probable 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 exacto de resultados para esta consulta.

Alcances de la 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

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 del lenguaje natural. La interpretación de NL solo se aplica a 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 complementaria de resultados 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 de una consulta. La configuración de resultados complementarias que se elija a nivel de SearchApplication tendrá prioridad si la estableces como verdadera.

QueryInterpretation

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

string

Es la interpretación de la consulta usada en la búsqueda. Por ejemplo, búsquedas con intención de lenguaje natural, como “correo electrónico de juan” se interpretará 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)

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

QueryInterpretation.InterpretationType

Enumeraciones
NONE No se usan la interpretación del 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 combinan con otros resultados. La razón por la que se combinan 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 propaga en el campo “Motivo” a continuación.

QueryInterpretation.Reason

Enumeraciones
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT La interpretación de lenguaje natural de la consulta se usa para recuperar los resultados de la búsqueda.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La similitud de los términos de la consulta y del documento se usa para ampliar de forma selectiva la consulta y así 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

Es 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 la búsqueda.
clusteredResults[]

object (SearchResult)

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

object (ResultDebugInfo)

Depurando información sobre este resultado de 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 que no se debe escapar antes de la renderización.
matchRanges[]

object (MatchRange)

Son los rangos coincidentes del fragmento.

MatchRange

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

Final de la coincidencia en el fragmento.

Metadatos

los 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)

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

string

Es el tipo 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)

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 una 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 establece en el elemento, el valor que se muestra aquí estará vacío. Cuando 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 una 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 con nombre genérico.
displayOptions

object (ResultDisplayMetadata)

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

string

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 líneas meta que se mostrará con el resultado.

ResultDisplayMetadata.ResultDisplayLine

El conjunto de campos que conforman una línea mostrada

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

La etiqueta de visualización de la propiedad.
operatorName

string

Es el nombre del operador de la propiedad.
property

object (NamedProperty)

Es el par de nombre y valor de la propiedad.

ResultDebugInfo

Información de depuración sobre el resultado

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

string

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 
{
  "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 los resultados de faceta. No estará vacío.
objectType

string

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

string

El nombre del operador elegido para la creación de facetas. @ver cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

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

FacetBucket

La unidad básica de operación es un bucket de una faceta. Un bucket puede consistir en un solo valor O en un rango contiguo de valores, según el tipo de campo agrupado. FacetBucket se usa actualmente solo 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 se muestran solo para las búsquedas cuando se garantiza la exactitud de los recuentos. Cloud Search no garantiza que los recuentos de facetas de ninguna consulta puedan estar presentes solo de manera intermitente, incluso para consultas idénticas. No compiles dependencias sobre la existencia de un recuento de facetas. en su lugar, usa los porcentajes de facetas, que siempre se devuelven.
percentage

integer

Porcentaje de resultados que coinciden con el valor del bucket. El valor mostrado 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 los porcentajes siempre se muestran, debes renderizarlos en lugar de los recuentos.
filter

object (Filter)

El 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

Información de depuración general con formato para mostrar.

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)

Es la fuente con la que está asociada la información del recuento de resultados.
hasMoreResults

boolean

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)

Es el recuento exacto de resultados de esta fuente.