- Solicitação HTTP
- Corpo da solicitação
- Corpo da resposta
- Escopos da autorização
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Snippet
- MatchRange
- Metadados
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket (em inglês)
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Faça um teste
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 ( |
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 Restringir sua pesquisa com operadores |
pageSize |
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 |
Índice inicial dos resultados. |
dataSourceRestrictions[] |
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[] |
|
sortOptions |
Opções para classificar os resultados da pesquisa |
queryInterpretationOptions |
para interpretar a consulta do usuário. |
contextAttributes[] |
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 a consulta do usuário. Vai 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[] |
Sugestão de ortografia para a consulta. |
facetResults[] |
Resultados repetidos de atributos. |
hasMoreResults |
Se há mais resultados de pesquisa que correspondem à consulta. |
debugInfo |
Informações de depuração sobre a resposta. |
errorInfo |
Informações de erro sobre a resposta. |
resultCounts |
Informações sobre a contagem de resultados aberta. |
Campo de união
No caso raro de o sistema não conseguir pesquisar todos os documentos, execute a consulta novamente. |
|
resultCountEstimate |
A contagem de resultados estimada para esta consulta. |
resultCountExact |
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 |
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 |
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 |
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 ( |
Campos | |
---|---|
interpretedQuery |
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 |
|
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 ( |
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 em questão. Esse URL é assinado e não deve ser alterado. |
snippet |
A concatenação de todos os snippets (resumos) disponíveis 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 em cluster. Se a origem atual não estiver ativada para clustering, este campo estará vazio. |
debugInfo |
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 ( |
Campos | |
---|---|
snippet |
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[] |
Os intervalos correspondentes no snippet. |
MatchRange
Intervalo correspondente de um snippet [início, fim).
Representação JSON |
---|
{ "start": integer, "end": integer } |
Campos | |
---|---|
start |
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 |
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. Um carimbo de data/hora no formato UTC "Zulu" RFC3339, 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 Um carimbo de data/hora no formato UTC "Zulu" RFC3339, 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 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 ( |
Campos | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Campos de exibição dos resultados de query.search
Representação JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Campos | |
---|---|
label |
O rótulo de exibição da propriedade. |
operatorName |
O nome do operador da propriedade. |
property |
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 |
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 ( |
Campos | |
---|---|
person |
Representação de uma pessoa |
SpellResult
Representação JSON |
---|
{ "suggestedQuery": string } |
Campos | |
---|---|
suggestedQuery |
A grafia sugerida da consulta. |
FacetResult
Resposta de atributo específico da origem
Representação JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Campos | |
---|---|
sourceName |
Nome da origem para a qual os resultados de atributos são retornados. Não vai ficar em branco. |
objectType |
Tipo de objeto para o qual os resultados de atributos são retornados. Pode ficar vazio. |
operatorName |
O nome do operador escolhido para a filtragem de atributos. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
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 ( |
Campos | |
---|---|
count |
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 |
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 |
Filtro que será transmitido na solicitação de pesquisa se o bucket correspondente estiver selecionado. |
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 da contagem de resultados
Representação JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Campos | |
---|---|
sourceResultCounts[] |
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 ( |
Campos | |
---|---|
source |
A origem à qual as informações da contagem de resultados estão associadas. |
hasMoreResults |
Se há mais resultados da pesquisa para essa origem. |
Campo de união
|
|
resultCountEstimate |
A contagem de resultados estimada para esta fonte. |
resultCountExact |
A contagem exata de resultados para esta origem. |