Method: query.search

La API de Cloud Search Query proporciona el método de búsqueda, que muestra 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 desde 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 Query 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 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)

Solicita opciones, 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 acotar tu búsqueda con operadores
pageSize

integer

Es la 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 más allá de 2,000.
start

integer

Es el índice inicial de los resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

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

opciones para interpretar la consulta del usuario.
contextAttributes[]

object (ContextAttribute)

Atributos de contexto para 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)

Es el resultado de la interpretación 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 tienen en cuenta en pageSize.
spellResults[]

object (SpellResult)

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

object (FacetResult)

Resultados de facetas repetidos
hasMoreResults

boolean

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

object (ResponseDebugInfo)

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

object (ErrorInfo)

Información de error sobre la respuesta.
resultCounts

object (ResultCounts)

Información expandida 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 se incluyen fuentes predefinidas en el conjunto de fuentes de datos consultadas. Los recuentos de resultados pueden mostrarse como una estimación, en lugar de un valor exacto, en las siguientes circunstancias:

  • Cuando la consulta tiene más de 2 términos en una frase, como "result count exact" entre comillas.

  • Cuando la cantidad de LCA de resultados de 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 consulta. result_count puede ser una de las siguientes opciones:
resultCountEstimate

string (int64 format)

Es el recuento estimado de resultados para esta consulta.
resultCountExact

string (int64 format)

Es el recuento exacto de resultados de esta consulta.

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 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 "false". Establece el valor en "true" 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 búsquedas 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 cualquiera de las dos marcas es verdadera.
disableSupplementalResults

boolean

Usa esta marca para inhabilitar los resultados complementarios de una consulta. El parámetro de configuración de resultados complementarios elegido a nivel de SearchApplication tendrá prioridad si se establece como "True".

QueryInterpretation

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

string

Es la interpretación de la consulta que se usa en la búsqueda. Por ejemplo, las búsquedas con un intent 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 consulta. Este campo no será UNSPECIFIED si el tipo de interpretación no es NONE.

QueryInterpretation.InterpretationType

Enumeraciones
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 combinan con otros. El motivo por el que se combinan estos otros resultados con los de la consulta original se propaga en el campo "Motivo" que aparece 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" que aparece a continuación.

QueryInterpretation.Reason

Enumeraciones
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 entre los términos de la consulta y los del documento se usa para ampliar de forma selectiva la búsqueda y recuperar resultados adicionales, ya que no se encontraron suficientes resultados para la búsqueda 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 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)

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)

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. Es el fragmento del documento. Puede contener caracteres HTML escapados que se deben desescapar antes de la renderización.
matchRanges[]

object (MatchRange)

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

Final de la coincidencia en el fragmento.

Metadatos

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 nombrada del resultado, como Gmail.
mimeType

string

Es el 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 objeto del resultado de la búsqueda
createTime

string (Timestamp format)

Es la hora de creación de este documento o objeto 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)

Es la fecha de la última modificación del objeto en el resultado de la búsqueda. Si no se establece en el artículo, el valor que se muestra aquí está vacío. Cuando se usa updateTime para calcular la actualización 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érica.
displayOptions

object (ResultDisplayMetadata)

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

ResultDisplayMetadata.ResultDisplayLine

Es la colección de campos que conforman una línea que se muestra.

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)

El par nombre-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 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

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

string

Es el tipo de objeto para el que se muestran los resultados de las facetas. Puede estar vacío.
operatorName

string

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

object (FacetBucket)

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

FacetBucket

Un bucket en un atributo 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 la precisión del recuento. Cloud Search no garantiza los recuentos de facetas para ninguna consulta, y es posible que estos solo estén presentes de forma intermitente, incluso para consultas idénticas. No crees dependencias en la existencia del recuento de facetas. En su lugar, usa los porcentajes de recuento de facetas que siempre se muestran.
percentage

integer

Es el porcentaje de resultados que coinciden con el valor del bucket. El valor que se muestra está entre [0-100] y se redondea hacia abajo a un número entero si es fraccionario. 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 una estimación. Debido a 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.
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 la fuente

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

object (Source)
errorMessage

string

ResultCounts

Información del recuento de resultados

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

object (SourceResultCount)

Información del recuento de resultados para cada fuente con resultados.

SourceResultCount

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 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 estimado de resultados para esta fuente.
resultCountExact

string (int64 format)

Es el recuento exacto de resultados de esta fuente.