- Solicitação HTTP
- Corpo da solicitação
- Corpo da resposta
- Escopos da autorização
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType (link em inglês)
- QueryInterpretation.Reason (link em inglês)
- SearchResult
- Snippet
- MatchRange
- Metadados
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo.
- StructuredResult
- SpellResult
- AtributoResult
- AtributoBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Faça um teste
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 do Google Drive, ou de dados que você indexou 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 realizar 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 ( |
Campos | |
---|---|
requestOptions |
Opções de solicitação, como o app de pesquisa e o fuso horário do usuário. |
query |
A string de consulta bruta. Veja os operadores de pesquisa compatíveis em Refinar a pesquisa com operadores |
pageSize |
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. O valor padrão é 10. O valor mínimo é 50 quando são solicitados resultados além de 2.000. |
start |
Índice inicial dos resultados. |
dataSourceRestrictions[] |
As fontes que serão usadas para consultas. Se não for especificado, todas as origens de dados do app de pesquisa atual serão usadas. |
facetOptions[] |
|
sortOptions |
As opções para classificar os resultados da pesquisa |
queryInterpretationOptions |
opções para interpretar a consulta do usuário. |
contextAttributes[] |
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 de pesquisa.
Representação JSON |
---|
{ "queryInterpretation": { object ( |
Campos | |
---|---|
queryInterpretation |
Resultado da interpretação de consulta para consulta do usuário. Será vazio se a interpretação de consulta estiver desativada. |
results[] |
Resultados de uma consulta de pesquisa. |
structuredResults[] |
Resultados estruturados para a consulta do usuário. Esses resultados não são contabilizados no pageSize. |
spellResults[] |
Ortografia sugerida para a consulta. |
facetResults[] |
Resultados de atributos repetidos |
hasMoreResults |
Indica se há mais resultados de pesquisa que correspondam à consulta. |
debugInfo |
Informações de depuração sobre a resposta. |
errorInfo |
Informações de erro sobre a resposta. |
resultCounts |
As informações da contagem de resultados foram expandidas. |
Campo de união
Nos raros casos em que o sistema não consegue pesquisar todos os documentos, execute novamente a consulta. |
|
resultCountEstimate |
A contagem estimada de resultados para esta consulta. |
resultCountExact |
A contagem exata de resultados para esta consulta. |
Escopos da 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 a Visão geral do OAuth 2.0.
Opções de interpretação
opções para interpretar a consulta do usuário.
Representação JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Campos | |
---|---|
disableNlInterpretation |
Sinalização para desativar a interpretação de linguagem natural (NL) das consultas. O padrão é "false". Defina como "true" para desativar a interpretação de linguagem natural. A interpretação NL só se aplica a fontes de dados predefinidas. |
enableVerbatimMode |
Ative essa sinalização para desativar todas as otimizações internas, como a interpretação de consulta em linguagem natural (NL), a recuperação de resultados complementares e o uso de sinônimos, incluindo os personalizados. A interpretação nl será desativada se uma das duas sinalizações for verdadeira. |
disableSupplementalResults |
Use esta sinalização para desativar os resultados complementares de 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 ( |
Campos | |
---|---|
interpretedQuery |
A interpretação da consulta usada na pesquisa. Por exemplo, as consultas com intenção de linguagem natural como "e-mail de joao" serão interpretadas como "from:joaofonte:e-mail" Este campo não será preenchido quando o motivo for NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
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 |
A interpretação de linguagem natural e uma versão mais ampla da consulta não são usadas para buscar os resultados da pesquisa. |
BLEND |
Os resultados da consulta original são combinados com outros resultados. O motivo para mesclar esses outros resultados com a consulta original é preenchido no campo 'Reason' abaixo. |
REPLACE |
Os resultados da consulta original serão substituídos. O motivo para substituir os resultados da consulta original é preenchido no campo 'Reason' 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 a fim de recuperar mais resultados da pesquisa, já que resultados suficientes não foram encontrados para a consulta do usuário. Nesse caso, a consulta interpretada ficará vazia. |
Resultado da pesquisa
Resultados que contêm informações indexadas de um documento.
Representação JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
Campos | |
---|---|
title |
Título do resultado da pesquisa. |
url |
O URL do resultado da pesquisa. O URL contém um redirecionamento do Google para o item real. Este URL é assinado e não deve ser alterado. |
snippet |
A concatenação de todos os snippets (resumos) disponível para este resultado. |
metadata |
metadados do resultado da pesquisa. |
clusteredResults[] |
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, esse campo estará vazio. |
debugInfo |
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 ( |
Campos | |
---|---|
snippet |
O snippet do documento. O snippet do documento. Pode conter caracteres HTML com escape que não devem ter escapes antes da renderização. |
matchRanges[] |
Os intervalos correspondentes no snippet. |
Intervalo
Intervalo correspondente de um snippet [start, end].
Representação JSON |
---|
{ "start": integer, "end": integer } |
Campos | |
---|---|
start |
É a posição inicial da correspondência no snippet. |
end |
Fim da correspondência no snippet. |
Metadados
metadados de um resultado de pesquisa correspondente.
Representação JSON |
---|
{ "source": { object ( |
Campos | |
---|---|
source |
A origem nomeada do resultado, como o Gmail. |
mimeType |
Tipo de MIME do resultado da pesquisa. |
thumbnailUrl |
O URL da miniatura do resultado. |
owner |
proprietário (geralmente criador) do documento ou objeto do resultado da pesquisa. |
createTime |
A hora de criação deste documento ou objeto no resultado da pesquisa. Timestamp no formato RFC3339 UTC "Zulu" com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: |
updateTime |
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 Timestamp no formato RFC3339 UTC "Zulu" com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: |
fields[] |
Campos indexados em dados estruturados, retornados como uma propriedade nomeada genérica. |
displayOptions |
que especificam como exibir um resultado da pesquisa de dados estruturados. |
objectType |
Tipo de objeto do resultado da pesquisa. |
ResultDisplayMetadata
Representação JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Campos | |
---|---|
objectTypeLabel |
O rótulo de exibição do objeto. |
metalines[] |
O conteúdo das metatags a ser exibido com o resultado. |
ResultDisplayMetadata.ResultDisplayLine
O conjunto de campos que compõem uma linha exibida.
Representação JSON |
---|
{
"fields": [
{
object ( |
Campos | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField.
Campos de exibição para os resultados de query.search
Representação JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Campos | |
---|---|
label |
A etiqueta de exibição da propriedade. |
operatorName |
O nome do operador da propriedade. |
property |
Par de valores de nome da propriedade. |
ResultDebugInfo
Informações de depuração sobre o resultado.
Representação JSON |
---|
{ "formattedDebugInfo": string } |
Campos | |
---|---|
formattedDebugInfo |
Informações gerais de depuração formatadas para exibição. |
Resultados estruturados
Resultados estruturados que são retornados como parte da solicitação de pesquisa.
Representação JSON |
---|
{
"person": {
object ( |
Campos | |
---|---|
person |
Representação de uma pessoa |
SpellResult
Representação JSON |
---|
{ "suggestedQuery": string } |
Campos | |
---|---|
suggestedQuery |
A ortografia sugerida da consulta. |
FacetResult
Resposta do atributo específico da origem
Representação JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Campos | |
---|---|
sourceName |
Nome da origem para o qual os resultados de atributos são retornados. Não estará vazio. |
objectType |
Tipo de objeto para o qual os resultados de atributos são retornados. Pode ficar vazio. |
operatorName |
Nome do operador escolhido para o atributo. @ver cloudsearch.SchemaPropertyOptions |
buckets[] |
ComponentBuckets para valores em resposta que contêm pelo menos um único resultado com o filtro correspondente. |
Bucket de atributos
Um bucket em um atributo é a unidade básica de operação. Um bucket pode abranger um único valor OU um intervalo contíguo de valores, dependendo do tipo do campo armazenado em intervalos. Atualmente, ComponentBucket é usado somente para retornar o objeto de resposta.
Representação JSON |
---|
{
"count": integer,
"percentage": integer,
"value": {
object ( |
Campos | |
---|---|
count |
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 de qualquer 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 ausência de atributos que são sempre retornadas. |
percentage |
Porcentagem de resultados que correspondem ao valor do bucket. O valor retornado está entre (0-100] e é arredondado para um número inteiro, se fracionado. Se o valor não for retornado explicitamente, ele representará um valor percentual que é arredondado para zero. As porcentagens são retornadas para todas as pesquisas, mas são uma estimativa. Como as porcentagens sempre são retornadas, é preciso renderizar as porcentagens em vez das contagens. |
value |
|
ResponseDebugInfo
Informações de depuração sobre a resposta.
Representação JSON |
---|
{ "formattedDebugInfo": string } |
Campos | |
---|---|
formattedDebugInfo |
Informações gerais de depuração formatadas para exibição. |
ErrorInfo
Informações de erro sobre a resposta.
Representação JSON |
---|
{
"errorMessages": [
{
object ( |
Campos | |
---|---|
errorMessages[] |
|
ErrorMessage
Mensagem de erro por resposta de origem.
Representação JSON |
---|
{
"source": {
object ( |
Campos | |
---|---|
source |
|
errorMessage |
|
ResultCounts.
Informações sobre a contagem de resultados
Representação JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Campos | |
---|---|
sourceResultCounts[] |
Informações da contagem de resultados para cada origem com resultados. |
Número de SourceResult
Informações por contagem de resultados de origem.
Representação JSON |
---|
{ "source": { object ( |
Campos | |
---|---|
source |
É a origem a que as informações de contagem de resultados estão associadas. |
hasMoreResults |
Indica se há mais resultados de pesquisa para esta origem. |
Campo de união
|
|
resultCountEstimate |
A contagem de resultados estimada para esta origem. |
resultCountExact |
A contagem exata de resultados dessa origem. |