Method: query.search

A API de consulta do Cloud Search oferece 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 o Google Drive, ou de dados indexados de terceiros.

Observação:essa API exige uma conta de usuário final padrão para ser executada. Uma conta de serviço não pode fazer solicitações diretamente à API Query. Para usar uma conta de serviço e fazer 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 aplicativo de pesquisa e o fuso horário do usuário.
query

string

A string de consulta bruta. Consulte 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, inclusive. 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 a serem usadas para consulta. Se não for especificado, todas as fontes de dados do aplicativo 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)

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

A resposta da API Search. Próximo ID: 19

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

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 da consulta do usuário. Vazio se a interpretação de consultas 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 em relação ao pageSize.
spellResults[]

object (SpellResult)

Sugestão de ortografia para a consulta.
facetResults[]

object (FacetResult)

Resultados de atributos repetidos.
hasMoreResults

boolean

Se há mais resultados da pesquisa que correspondem à 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)

Informações expandidas sobre a contagem de resultados.

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. A contagem de resultados pode ser retornada como uma estimativa, em vez de um valor exato, nas seguintes circunstâncias:

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

  • Quando o número de ACLs de resultados da pesquisa únicos a serem avaliadas é muito grande para ser calculado em uma latência razoável.

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

string (int64 format)

A contagem de resultados estimada para esta consulta.
resultCountExact

string (int64 format)

A contagem exata de resultados para essa consulta.

Escopos de 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 o guia de autorização.

QueryInterpretationOptions

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

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

boolean

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

boolean

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

boolean

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

QueryInterpretation

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

string

A interpretação da consulta usada na pesquisa. Por exemplo, consultas com intenção de linguagem natural, como "e-mail do João", serão interpretadas como "from:joao source:mail". Esse 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. Esse campo não será UNSPECIFIED se o tipo de interpretação não for NONE.
interpretedQueryActualResultCount

integer

O número real de resultados retornados pela consulta interpretada.
interpretedQueryEstimatedResultCount

string (int64 format)

O número estimado de resultados retornados pela consulta interpretada.

QueryInterpretation.InterpretationType

Tipos enumerados
NONE Nem a interpretação em linguagem natural nem uma versão mais ampla da consulta são usadas para buscar os resultados da pesquisa.
BLEND Os resultados da consulta original são combinados com outros resultados. O motivo para combinar esses outros resultados com os da consulta original é preenchido no campo "motivo" abaixo.
REPLACE Os resultados da consulta original são substituídos. O motivo da substituição dos resultados da consulta original é preenchido no campo "motivo" abaixo.

QueryInterpretation.Reason

Tipos enumerados
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT A interpretação em linguagem natural da consulta é usada para buscar os resultados da pesquisa.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY A similaridade entre os termos da consulta e do documento é usada para ampliar seletivamente a consulta e recuperar mais resultados de pesquisa, já que não foram encontrados resultados suficientes para a consulta do usuário. A consulta interpretada vai estar vazia para esse caso.

SearchResult

Resultados que contêm informações indexadas para um documento. Próximo ID: 16

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. Esse URL é assinado e não deve ser alterado.
snippet

object (Snippet)

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

object (Metadata)

metadados do resultado da pesquisa.
clusteredResults[]

object (SearchResult)

Se a origem estiver agrupada, forneça uma lista de resultados agrupados. Só haverá um nível de resultados agrupados. Se a origem atual não estiver ativada para clustering, esse campo vai ficar em branco.
debugInfo

object (ResultDebugInfo)

Informações de depuração sobre este 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. Pode conter um caractere HTML com escape que precisa ser removido antes da renderização.
matchRanges[]

object (MatchRange)

Os intervalos correspondentes no snippet.

MatchRange

Intervalo correspondente de um snippet [início, fim).

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

integer

Posição inicial da correspondência no snippet.
end

integer

Fim da partida no snippet.

Metadados

metadados de um resultado da 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 fonte nomeada do resultado, como o Gmail.
mimeType

string

Tipo MIME do resultado da pesquisa.
thumbnailUrl

string

O URL da miniatura do resultado.
owner

object (Person)

proprietário (geralmente o 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.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

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

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

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

object (ResultDisplayMetadata)

opções que especificam como mostrar 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 metalinhas a ser exibido com o resultado.

ResultDisplayMetadata.ResultDisplayLine

A coleção de campos que compõem uma linha mostrada

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Mostrar campos para resultados de "query.search"

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

string

O rótulo de exibição da propriedade.
operatorName

string

O nome do operador da propriedade.
property

object (NamedProperty)

O par nome-valor 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.

StructuredResult

Resultados estruturados retornados como parte de uma solicitação de pesquisa.

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

structured_result pode ser apenas de um dos tipos a seguir:
person

object (Person)

Representação de uma pessoa

SpellResult

Representação JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Campos
suggestedQuery

string

A ortografia sugerida da consulta.
suggestionType

enum (SpellResult.SuggestionType)

sugestão acionada para a consulta atual.
suggestedQueryHtml

object (SafeHtmlProto)

O HTML higienizado que representa a consulta com grafia corrigida e pode ser usado na interface. Normalmente, isso tem tags específicas do idioma para marcar partes da consulta que foram corrigidas.

SpellResult.SuggestionType

O tipo de sugestão acionada para a consulta.

Tipos enumerados
SUGGESTION_TYPE_UNSPECIFIED Tipo de verificação ortográfica padrão
NON_EMPTY_RESULTS_SPELL_SUGGESTION Sugestão ortográfica sem resultados alterados. Os resultados ainda são mostrados para a consulta original (que tem resultados diferentes de zero) com uma sugestão de ortografia que teria resultados.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Sugestão ortográfica acionada quando a consulta original não tem resultados. Quando a consulta original não tem resultados, mas a sugestão de ortografia tem, mostramos os resultados da consulta corrigida.

SafeHtmlProto

IMPORTANTE: não é seguro aceitar essa mensagem de uma fonte não confiável, já que é trivial para um invasor falsificar mensagens serializadas que não atendem ao contrato de segurança do tipo. Por exemplo, ela pode conter um script controlado pelo invasor. Um sistema que recebe um SafeHtmlProto confia implicitamente no produtor dele. Portanto, geralmente é seguro retornar essa mensagem em respostas de RPC, mas não é seguro aceitá-la em solicitações de RPC.

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

string

IMPORTANTE: nunca defina ou leia este campo, mesmo em testes. Ele é particular. Consulte a documentação na parte de cima do arquivo .proto para ver os pacotes de linguagem de programação com que criar ou ler essa mensagem.

FacetResult

Resposta de refinamento específica da origem

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

string

Nome da origem para a qual os resultados de refinamento são retornados. Não vai estar vazio.
objectType

string

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

string

O nome do operador escolhido para a inclusão de facetas. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets para valores na resposta que contém pelo menos um único resultado com o filtro correspondente.

FacetBucket

Um agrupamento em uma faceta é a unidade básica de operação. Um agrupamento pode incluir um único valor OU um intervalo contíguo de valores, dependendo do tipo do campo agrupado. No momento, "FacetBucket" é usado apenas para retornar o objeto de resposta.

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

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 facetas para nenhuma consulta, e elas podem aparecer apenas de forma intermitente, mesmo para consultas idênticas. Não crie dependências na existência da contagem de facetas. Em vez disso, use porcentagens de contagem de facetas, que são sempre retornadas.
percentage

integer

Porcentagem de resultados que correspondem ao valor do bucket. O valor retornado está entre (0 e 100] e é arredondado para baixo até um número inteiro se for fracionário. Se o valor não for retornado explicitamente, ele representará uma porcentagem que será arredondada para 0. As porcentagens são retornadas para todas as pesquisas, mas são uma estimativa. Como as porcentagens são sempre retornadas, renderize porcentagens em vez de contagens.
filter

object (Filter)

Filtro a ser transmitido na solicitação de pesquisa se o bucket correspondente for selecionado.
Campo de união bucket_value. O intervalo ou valor do agrupamento por classes que é facetado bucket_value pode ser apenas um dos seguintes:
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 da fonte.

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 sobre a contagem de resultados para cada fonte com resultados.

SourceResultCount

Informações de contagem por resultado da 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

Se há mais resultados da pesquisa para essa fonte.

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 fonte.
resultCountExact

string (int64 format)

A contagem exata de resultados para essa fonte.