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 o Google Drive, ou de dados indexados 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 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

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 resultados além de 2.000 são solicitados.
start

integer

Índice inicial dos resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

As fontes a serem usadas para consulta. Se não forem especificadas, todas as fontes 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)

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 da consulta para a consulta do usuário. Vai ficar 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 de atributos repetidos.
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)

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 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 de pesquisa exclusivos a serem avaliadas for muito grande para ser calculado em uma latência razoável.

No caso raro em que o sistema não consegue pesquisar em todos os documentos, execute a consulta novamente. 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 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

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 consultas em linguagem natural (NL). O padrão é "false". Defina como "true" para desativar a interpretação em linguagem natural. A interpretação de NL 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 (NL), recuperação de resultados complementares e uso de sinônimos, incluindo os personalizados. A interpretação de delas será desativada se uma das duas flags 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 do SearchApplication terá precedência se 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, consultas com intenção de linguagem natural, como "e-mail do João" será interpretada como "from:joao 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á UNSPECIFIED se o tipo de interpretação não for NONE.

QueryInterpretation.InterpretationType

Enums
NONE Para buscar os resultados da pesquisa, não usamos a interpretação em linguagem natural nem uma versão mais ampla da consulta.
BLEND Os resultados da consulta original são combinados com outros resultados. O motivo para combinar esses outros resultados com os resultados da consulta original é preenchido no campo "Motivo" campo abaixo.
REPLACE Os resultados da consulta original serão substituídos. O motivo para substituir os resultados da consulta original é preenchido no campo "Motivo" campo abaixo.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT A interpretação da consulta em linguagem natural é usada para buscar os resultados da pesquisa.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY A similaridade de termos de consulta e 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. Nesse caso, a consulta interpretada ficará vazia.

SearchResult

Resultados contendo informações indexadas para 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. O URL está assinado e não pode 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 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, este campo ficará 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 caracteres HTML com escape que não devem ter escape antes da renderização.
matchRanges[]

object (MatchRange)

Os intervalos correspondentes no snippet.

MatchRange

Intervalo correspondente de um snippet [start, end).

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

Um carimbo de data/hora 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 é de dois anos a partir do horário atual.

Um carimbo de data/hora 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 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

Exibir 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 de valor de 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 ortografia sugerida para a 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 atributo são retornados. Não ficará em branco.
objectType

string

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

string

O nome do operador escolhido para as facetas. @consulte cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets para valores de resposta contendo 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 incluir um único valor OU um intervalo contíguo de valores, dependendo do tipo do campo em buckets. 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ó são retornadas para pesquisas quando a precisão está garantida. O Cloud Search não garante a contagem de atributos para qualquer consulta, e a contagem de atributos pode estar presente apenas de modo intermitente, mesmo para consultas idênticas. Não crie dependências na existência da contagem de atributos. Em vez disso, use porcentagens de alocação 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, se for fracionário, será arredondado para um número inteiro. Se o valor não é retornado explicitamente, ele representa um valor percentual arredondado para 0. As porcentagens são retornadas para todas as pesquisas, mas são uma estimativa. Como as porcentagens são sempre retornadas, você deve renderizar porcentagens em vez de contagens.
filter

object (Filter)

Filtro a ser passado na solicitação de pesquisa se o bucket correspondente for 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 de 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 associada às informações de contagem de resultados.
hasMoreResults

boolean

Indica se existem mais resultados de 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 fonte.