Method: query.search

A API Cloud Search Query fornece o método de pesquisa, que retorna os resultados mais relevantes de uma consulta do usuário. Os resultados podem vir de apps do Google Workspace, como o Gmail ou do Google Drive, ou de dados que você indexou de terceiros.

Observação: essa API requer uma conta de usuário final padrão para ser executada. Uma conta de serviço não pode realizar solicitações da API Query diretamente. Para usar uma conta de serviço para realizar consultas, configure a delegação de autoridade em todo o domínio do Google Workspace.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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)

Opções de solicitação, como o app de pesquisa e o fuso horário do usuário.
query

string

A string de consulta bruta. Veja os operadores de pesquisa compatíveis em Refinar a pesquisa com operadores
pageSize

integer

Número máximo de resultados da pesquisa a serem retornados em uma página. Os valores válidos estão entre 1 e 100. O valor padrão é 10. O valor mínimo é 50 quando são solicitados resultados além de 2.000.
start

integer

Índice inicial dos resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

As fontes que serão usadas para consultas. Se não for especificado, todas as origens de dados do app de pesquisa atual serão usadas.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

As opções para classificar os resultados da pesquisa
queryInterpretationOptions

object (QueryInterpretationOptions)

opções para interpretar a consulta do usuário.
contextAttributes[]

object (ContextAttribute)

Os atributos de contexto da solicitação que serão usados para ajustar a classificação dos resultados da pesquisa. O número máximo de elementos é 10.

Corpo da resposta

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

A resposta da API de pesquisa.

Representação 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 da interpretação de consulta para consulta do usuário. Será vazio se a interpretação de consulta estiver desativada.
results[]

object (SearchResult)

Resultados de uma consulta de pesquisa.
structuredResults[]

object (StructuredResult)

Resultados estruturados para a consulta do usuário. Esses resultados não são contabilizados no pageSize.
spellResults[]

object (SpellResult)

Ortografia sugerida para a consulta.
facetResults[]

object (FacetResult)

Resultados de atributos repetidos
hasMoreResults

boolean

Indica se há mais resultados de pesquisa que correspondam à consulta.
debugInfo

object (ResponseDebugInfo)

Informações de depuração sobre a resposta.
errorInfo

object (ErrorInfo)

Informações de erro sobre a resposta.
resultCounts

object (ResultCounts)

As informações da contagem de resultados foram expandidas.

Campo de união result_count. A contagem total de resultados em todas as fontes de dados solicitadas. Omitido se fontes predefinidas forem incluídas no conjunto de fontes de dados consultadas. As contagens de resultados podem ser retornadas como uma estimativa em vez de exata nestas circunstâncias:

  • Quando a consulta tem mais de dois termos em uma frase, como "quot;contagem exata" entre aspas.

  • Quando o número de ACLs de resultados exclusivos da pesquisa para avaliar é muito grande para ser computado em uma latência razoável.

Nos raros casos em que o sistema não consegue pesquisar todos os documentos, execute novamente a consulta. result_count pode ser apenas de um dos tipos a seguir:
resultCountEstimate

string (int64 format)

A contagem estimada de resultados para esta consulta.
resultCountExact

string (int64 format)

A contagem exata de resultados para esta consulta.

Escopos da autorização

Requer um dos seguintes escopos do OAuth:

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

Para mais informações, consulte a Visão geral do OAuth 2.0.

Opções de interpretação

opções para interpretar a consulta do usuário.

Representação JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Campos
disableNlInterpretation

boolean

Sinalização para desativar a interpretação de linguagem natural (NL) das consultas. O padrão é "false". Defina como "true" para desativar a interpretação de linguagem natural. A interpretação NL só se aplica a fontes de dados predefinidas.
enableVerbatimMode

boolean

Ative essa sinalização para desativar todas as otimizações internas, como a interpretação de consulta em linguagem natural (NL), a recuperação de resultados complementares e o uso de sinônimos, incluindo os personalizados. A interpretação nl será desativada se uma das duas sinalizações for verdadeira.
disableSupplementalResults

boolean

Use esta sinalização para desativar os resultados complementares de uma consulta. A configuração de resultados complementares escolhida no nível de SearchApplication terá precedência se for definida como verdadeira.

QueryInterpretation.

Representação JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Campos
interpretedQuery

string

A interpretação da consulta usada na pesquisa. Por exemplo, as consultas com intenção de linguagem natural como "e-mail de joao" serão interpretadas como "from:joaofonte:e-mail" Este campo não será preenchido quando o motivo for NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

O motivo da interpretação da consulta. Este campo não será UNSPECIFIED se o tipo de interpretação não for "NENHUM".

QueryInterpretation.InterpretationType

Enums
NONE A interpretação de linguagem natural e uma versão mais ampla da consulta não são usadas para buscar os resultados da pesquisa.
BLEND Os resultados da consulta original são combinados com outros resultados. O motivo para mesclar esses outros resultados com a consulta original é preenchido no campo 'Reason' abaixo.
REPLACE Os resultados da consulta original serão substituídos. O motivo para substituir os resultados da consulta original é preenchido no campo 'Reason' abaixo.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT A interpretação de linguagem natural da consulta é usada para buscar os resultados da pesquisa.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY A semelhança de termos de consulta e documento é usada para ampliar seletivamente a consulta a fim de recuperar mais resultados da pesquisa, já que resultados suficientes não foram encontrados para a consulta do usuário. Nesse caso, a consulta interpretada ficará vazia.

Resultado da pesquisa

Resultados que contêm informações indexadas de um documento.

Representação JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Campos
title

string

Título do resultado da pesquisa.
url

string

O URL do resultado da pesquisa. O URL contém um redirecionamento do Google para o item real. Este URL é assinado e não deve ser alterado.
snippet

object (Snippet)

A concatenação de todos os snippets (resumos) disponível para este resultado.
metadata

object (Metadata)

metadados do resultado da pesquisa.
clusteredResults[]

object (SearchResult)

Se a origem estiver em cluster, forneça uma lista de resultados em cluster. Haverá apenas um nível de resultados agrupados. Se a origem atual não estiver ativada para clustering, esse campo estará vazio.
debugInfo

object (ResultDebugInfo)

Informações de depuração sobre esse resultado da pesquisa.

Snippet

Snippet do resultado da pesquisa que resume o conteúdo da página resultante.

Representação JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Campos
snippet

string

O snippet do documento. O snippet do documento. Pode conter caracteres HTML com escape que não devem ter escapes antes da renderização.
matchRanges[]

object (MatchRange)

Os intervalos correspondentes no snippet.

Intervalo

Intervalo correspondente de um snippet [start, end].

Representação JSON 
{
  "start": integer,
  "end": integer
}
Campos
start

integer

É a posição inicial da correspondência no snippet.
end

integer

Fim da correspondência no snippet.

Metadados

metadados de um resultado de pesquisa correspondente.

Representação 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)

A origem nomeada do resultado, como o Gmail.
mimeType

string

Tipo de MIME do resultado da pesquisa.
thumbnailUrl

string

O URL da miniatura do resultado.
owner

object (Person)

proprietário (geralmente criador) do documento ou objeto do resultado da pesquisa.
createTime

string (Timestamp format)

A hora de criação deste documento ou objeto no resultado da pesquisa.

Timestamp no formato RFC3339 UTC "Zulu" com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

A data da última modificação do objeto no resultado da pesquisa. Se não for definido no item, o valor retornado aqui estará vazio. Quando updateTime é usado para calcular a atualização e não está definido, o valor padrão é dois anos a partir do horário atual.

Timestamp no formato RFC3339 UTC "Zulu" com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Campos indexados em dados estruturados, retornados como uma propriedade nomeada genérica.
displayOptions

object (ResultDisplayMetadata)

que especificam como exibir um resultado da pesquisa de dados estruturados.
objectType

string

Tipo de objeto do resultado da pesquisa.

ResultDisplayMetadata

Representação JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Campos
objectTypeLabel

string

O rótulo de exibição do objeto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

O conteúdo das metatags a ser exibido com o resultado.

ResultDisplayMetadata.ResultDisplayLine

O conjunto de campos que compõem uma linha exibida.

Representação JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Campos
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField.

Campos de exibição para os resultados de query.search

Representação JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Campos
label

string

A etiqueta de exibição da propriedade.
operatorName

string

O nome do operador da propriedade.
property

object (NamedProperty)

Par de valores de nome da propriedade.

ResultDebugInfo

Informações de depuração sobre o resultado.

Representação JSON 
{
  "formattedDebugInfo": string
}
Campos
formattedDebugInfo

string

Informações gerais de depuração formatadas para exibição.

Resultados estruturados

Resultados estruturados que são retornados como parte da solicitação de pesquisa.

Representação JSON 
{
  "person": {
    object (Person)
  }
}
Campos
person

object (Person)

Representação de uma pessoa

SpellResult

Representação JSON 
{
  "suggestedQuery": string
}
Campos
suggestedQuery

string

A ortografia sugerida da consulta.

FacetResult

Resposta do atributo específico da origem

Representação JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Campos
sourceName

string

Nome da origem para o qual os resultados de atributos são retornados. Não estará vazio.
objectType

string

Tipo de objeto para o qual os resultados de atributos são retornados. Pode ficar vazio.
operatorName

string

Nome do operador escolhido para o atributo. @ver cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

ComponentBuckets para valores em resposta que contêm pelo menos um único resultado com o filtro correspondente.

Bucket de atributos

Um bucket em um atributo é a unidade básica de operação. Um bucket pode abranger um único valor OU um intervalo contíguo de valores, dependendo do tipo do campo armazenado em intervalos. Atualmente, ComponentBucket é usado somente para retornar o objeto de resposta.

Representação JSON 
{
  "count": integer,
  "percentage": integer,
  "value": {
    object (Value)
  }
}
Campos
count

integer

Número de resultados que correspondem ao valor do bucket. As contagens só são retornadas para pesquisas quando a precisão da contagem é garantida. O Cloud Search não garante a contagem de atributos de qualquer consulta, e a contagem de atributos pode estar presente apenas de maneira intermitente, mesmo para consultas idênticas. Não crie dependências na existência da contagem de atributos. Em vez disso, use porcentagens de ausência de atributos que são sempre retornadas.
percentage

integer

Porcentagem de resultados que correspondem ao valor do bucket. O valor retornado está entre (0-100] e é arredondado para um número inteiro, se fracionado. Se o valor não for retornado explicitamente, ele representará um valor percentual que é arredondado para zero. As porcentagens são retornadas para todas as pesquisas, mas são uma estimativa. Como as porcentagens sempre são retornadas, é preciso renderizar as porcentagens em vez das contagens.
value

object (Value)

ResponseDebugInfo

Informações de depuração sobre a resposta.

Representação JSON 
{
  "formattedDebugInfo": string
}
Campos
formattedDebugInfo

string

Informações gerais de depuração formatadas para exibição.

ErrorInfo

Informações de erro sobre a resposta.

Representação JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Campos
errorMessages[]

object (ErrorMessage)

ErrorMessage

Mensagem de erro por resposta de origem.

Representação JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Campos
source

object (Source)
errorMessage

string

ResultCounts.

Informações sobre a contagem de resultados

Representação JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Campos
sourceResultCounts[]

object (SourceResultCount)

Informações da contagem de resultados para cada origem com resultados.

Número de SourceResult

Informações por contagem de resultados de origem.

Representação 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)

É a origem a que as informações de contagem de resultados estão associadas.
hasMoreResults

boolean

Indica se há mais resultados de pesquisa para esta origem.

Campo de união result_count.

result_count pode ser apenas de um dos tipos a seguir:
resultCountEstimate

string (int64 format)

A contagem de resultados estimada para esta origem.
resultCountExact

string (int64 format)

A contagem exata de resultados dessa origem.