Method: query.search

A API Cloud Search Query oferece o método de pesquisa, que retorna os resultados mais relevantes da consulta de um 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:para executar essa API, é preciso ter uma conta de usuário final padrão. Uma conta de serviço não pode fazer solicitações da API Query diretamente. Se você quiser usar uma conta de serviço para 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 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 Restringir sua pesquisa com operadores
pageSize

integer

O número máximo de resultados de 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 resultados além de 2.000 são solicitados.
start

integer

Índice inicial dos resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

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

object (FacetOptions)
sortOptions

object (SortOptions)

Opções para classificar os resultados da pesquisa
queryInterpretationOptions

object (QueryInterpretationOptions)

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

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 a consulta do usuário. Vai 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)

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

object (FacetResult)

Resultados repetidos de atributos.
hasMoreResults

boolean

Se há mais resultados de 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 sobre a contagem de resultados aberta.

Campo de união result_count. A contagem total de resultados em todas as fontes de dados solicitadas. Omitido se as origens predefinidas estiverem incluídas no conjunto de fontes consultadas. As contagens de resultados podem ser retornadas como uma estimativa, e não exatas, 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 exclusivos a serem avaliados for muito grande para ser calculado em uma latência razoável.

No caso raro de o sistema não conseguir 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 desta consulta.

Escopos de autorização

Requer um dos seguintes escopos de 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

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 verdadeiro para desativar a interpretação de linguagem natural. A interpretação de 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 consultas em linguagem natural (NL), a recuperação complementar de resultados 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 essa sinalização 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)
}
Campos
interpretedQuery

string

A interpretação da consulta usada na pesquisa. Por exemplo, consultas com intenção de linguagem natural, como "e-mail de joão" serão interpretadas como "from:joão source: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á NÃO ESPECIFICADO se o tipo de interpretação não for NONE.

QueryInterpretation.InterpretationType

Enums
NONE Nem a interpretação de 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 da combinação desses outros resultados com os resultados da consulta original é preenchido no campo "Motivo" abaixo.
REPLACE Os resultados da consulta original são substituídos. O motivo para substituir os resultados da consulta original é preenchido no campo "Motivo" abaixo.

QueryInterpretation.Reason

Enums
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 semelhança entre os termos da consulta e do documento é usada para ampliar seletivamente a consulta e recuperar resultados de pesquisa adicionais, já que não foram encontrados resultados suficientes para a consulta do usuário. A consulta interpretada estará vazia neste caso.

SearchResult

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

object (Snippet)

A concatenação de todos os snippets (resumos) disponíveis 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 em cluster. Se a origem atual não estiver ativada para clustering, este campo estará vazio.
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. O snippet do documento. Pode conter um caractere HTML com escape que não pode ter escape 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 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

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.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, 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 for usado para calcular a atualização e não for definido, o padrão será dois anos a partir do horário atual.

Um carimbo de data/hora no formato UTC "Zulu" RFC3339, 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 de metalines a ser exibido com o resultado.

ResultDisplayMetadata.ResultDisplayLine

Coleção 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 dos 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 de valor do nome para a 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 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 grafia sugerida da consulta.

FacetResult

Resposta de atributo específico 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 atributos são retornados. Não vai ficar em branco.
objectType

string

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

string

O nome do operador escolhido para a filtragem de atributos. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

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

FacetBucket

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

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

integer

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

integer

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

object (Filter)

Filtro que será transmitido na solicitação de pesquisa se o bucket correspondente estiver selecionado.
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 da contagem de resultados

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

object (SourceResultCount)

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

SourceResultCount

Informações de contagem de resultados por 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 à qual as informações da contagem de resultados estão associadas.
hasMoreResults

boolean

Se há mais resultados da pesquisa para essa 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 fonte.
resultCountExact

string (int64 format)

A contagem exata de resultados para esta origem.