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 exige uma conta de usuário final padrão para ser executada. Uma conta de serviço não pode executar solicitações da API Query diretamente. Para usar uma conta de serviço para executar 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 de pesquisa 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 os resultados além de 2.000 são solicitados.
start

integer

Índice inicial dos resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

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

object (FacetOptions)
sortOptions

object (SortOptions)

As opções de classificação dos 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

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

A resposta da API Search.

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

Campo de união result_count. A contagem total de resultados em todas as origens 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 "result count exact" entre aspas.

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

No caso raro 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 essa 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

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 (NL, na sigla em inglês). O padrão é "false". Defina como "true" 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 flag para desativar todas as otimizações internas, como a interpretação de consultas em linguagem natural (NL, na sigla em inglês), a recuperação de resultados complementares e o 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 suplementares escolhida no nível da SearchApplication vai ter precedência se 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 a intenção de linguagem natural, como "e-mail de João", serão interpretadas como "de:João origem: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. Esse campo não será UNSPECIFIED se o tipo de interpretação não for NONE.

QueryInterpretation.InterpretationType

Enums
NONE Nem a interpretação da 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 mesclados com outros resultados. O motivo para combinar esses 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 da substituição dos resultados da consulta original é preenchido no campo "Motivo" 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 semelhança entre os termos da consulta e do documento é usada para ampliar seletivamente a consulta e recuperar outros 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 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. Esse URL é assinado e não pode ser alterado.
snippet

object (Snippet)

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

object (Metadata)

metadados do resultado da pesquisa.
clusteredResults[]

object (SearchResult)

Se a origem for 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 agrupamento, esse campo vai ficar 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 precisam ser removidos 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 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 do 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 vai estar vazio. Quando updateTime é usado para calcular a atualização e não está definido, esse valor é definido como 2 anos a partir do momento 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)

opções que especificam como mostrar um resultado de 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 que será mostrado com o resultado.

ResultDisplayMetadata.ResultDisplayLine

A 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 para resultados de pesquisa de query.

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 nome e 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 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 de faceta específica da origem

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

string

Nome da origem para os resultados de atributo retornados. Não pode estar em branco.
objectType

string

Tipo de objeto para que os resultados de facetas são retornados. Pode ficar vazio.
operatorName

string

O nome do operador escolhido para a divisão em 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 bucket em uma faceta é a unidade básica de operação. Um bucket pode incluir um único valor OU um intervalo contínuo de valores, dependendo do tipo de bucket de campo. No momento, o 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. Os números são retornados apenas para pesquisas quando a precisão do cálculo é garantida. O Cloud Search não garante a contagem de facetas para nenhuma consulta, e as contagens de facetas podem estar presentes apenas de forma intermitente, mesmo para consultas idênticas. Não crie dependências na existência da contagem de facetas. Use as 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-100] e é arredondado para um número inteiro se for fracionário. Se o valor não for retornado explicitamente, ele vai representar 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, renderize porcentagens em vez de contagens.
filter

object (Filter)

Filtro a ser transmitido 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 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 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 com que as informações de contagem de resultados estão associadas.
hasMoreResults

boolean

Se há 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 estimados para essa origem.
resultCountExact

string (int64 format)

A contagem exata de resultados para essa origem.