Method: query.search

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 fazer 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 Restringir sua pesquisa com operadores
pageSize

integer

Número máximo de resultados da pesquisa para retornar 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 dos 2.000.
start

integer

Índice inicial dos resultados.
dataSourceRestrictions[]

object (DataSourceRestriction)

As fontes que vão ser usadas para consulta. Se não for especificado, todas as fontes de dados do app de pesquisa atual serão 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)

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 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 de interpretação de consulta para a 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 atributo repetidos.
hasMoreResults

boolean

Indica se há mais resultados de pesquisa correspondentes à 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 fontes de dados solicitadas. Omitido se origens predefinidas forem incluídas no conjunto de fontes de dados consultadas. As contagens de resultados podem ser retornadas como uma estimativa, e não exata, nas seguintes circunstâncias:

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

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

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

string (int64 format)

A contagem de resultados estimados para esta consulta.
resultCountExact

string (int64 format)

A contagem exata de resultados para esta 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 a Visão geral do OAuth 2.0.

Opções de interpretação de consulta

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) de consultas. 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 esta sinalização para desativar todas as otimizações internas, como a interpretação de linguagem natural (NL) de consultas, a recuperação de resultados complementares e o uso de sinônimos, incluindo os personalizados. A interpretação de N será desativada se uma das duas sinalizações for verdadeira.
disableSupplementalResults

boolean

Use essa sinalização para desativar os resultados complementares para 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, consultas com intenção de linguagem natural como "e-mail de joão" vão ser interpretadas como "from:joão fonte: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 Nem a interpretação de linguagem natural, nem uma versão mais ampla da consulta é usada para buscar os resultados da pesquisa.
BLEND Os resultados da consulta original são combinados com outros resultados. O motivo de combinar esses outros resultados com os da consulta original é preenchido no campo "Motivo" abaixo.
REPLACE Os resultados da consulta original serã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 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 e recuperar mais resultados, já que não foram encontrados resultados suficientes para a consulta do usuário. A consulta interpretada estará em branco neste caso.

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

object (Snippet)

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

object (Metadata)

os metadados do resultado da pesquisa.
clusteredResults[]

object (SearchResult)

Se a origem estiver em cluster, forneça a lista de resultados em cluster. Haverá apenas um nível de resultados em cluster. Se a origem atual não estiver ativada para clustering, esse 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 podem ter escape antes da renderização.
matchRanges[]

object (MatchRange)

Os intervalos correspondentes no snippet.

Intervalo de correspondências

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

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 fonte 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 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 para o objeto no resultado da pesquisa. Se não for definido no item, o valor retornado vai ficar 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.

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.

MetadadosDisplayDisplay

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 da metaline 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 da consulta.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 da propriedade.

Informações do resultado da depuração

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.

Resultado estruturado

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

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

object (Person)

Representação de uma pessoa

Resultado ortográfico

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 fonte para a qual os resultados de atributo são retornados. Não ficará vazio.
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 a criação de atributos. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets para valores em resposta com 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 agrupado. 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. 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 para nenhuma 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 base 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 será arredondado para um número inteiro se for fracionário. Se o valor não é retornado explicitamente, ele representa um valor percentual que é arredondado para zero. 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)

Informações de depuração

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

Contagens de resultados

Informações do número de resultados

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

object (SourceResultCount)

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

ContagemDeResultadosDeFonte

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 fonte associada às informações de contagem de resultados.
hasMoreResults

boolean

Indica se há mais resultados da pesquisa para esta 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 origem.
resultCountExact

string (int64 format)

A contagem de resultados exata para essa origem.