- Solicitação HTTP
- Corpo da solicitação
- Corpo da resposta
- Escopos da autorização
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType (link em inglês)
- QueryInterpretation.Reason
- Resultado da pesquisa
- Snippet
- MatchRange
- Metadados
- ResultDisplayMetadata.
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField.
- ResultDebugInfo
- StructuredResult
- parcelas ortográficas
- FacetResult
- FacetBucket
- 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 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 ( |
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 |
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 |
Índice inicial dos resultados. |
dataSourceRestrictions[] |
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[] |
|
sortOptions |
Opções para classificar os resultados da pesquisa |
queryInterpretationOptions |
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 Search.
Representação JSON |
---|
{ "queryInterpretation": { object ( |
Campos | |
---|---|
queryInterpretation |
Resultado de interpretação de consulta para a 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 atributo repetidos. |
hasMoreResults |
Indica se há mais resultados de pesquisa correspondentes à 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 expandida. |
Campo de união
Nos raros casos em que o sistema não conseguir pesquisar em todos os documentos, execute novamente a consulta. |
|
resultCountEstimate |
A contagem de resultados estimados para esta consulta. |
resultCountExact |
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 |
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 |
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 |
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 ( |
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" 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 |
|
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 ( |
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. Esse URL é assinado e não pode ser alterado. |
snippet |
A concatenação de todos os snippets (resumos) disponíveis para este resultado. |
metadata |
os metadados do resultado da pesquisa. |
clusteredResults[] |
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 |
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 caracteres HTML com escape que não podem ter escape antes da renderização. |
matchRanges[] |
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 |
É 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 fonte nomeada do resultado, como Gmail. |
mimeType |
Tipo 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. 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 para o objeto no resultado da pesquisa. Se não for definido no item, o valor retornado vai ficar 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. |
MetadadosDisplayDisplay
Representação JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Campos | |
---|---|
objectTypeLabel |
O rótulo de exibição do objeto. |
metalines[] |
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 ( |
Campos | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Campos de exibição para os resultados da consulta.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 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 |
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 ( |
Campos | |
---|---|
person |
Representação de uma pessoa |
Resultado ortográfico
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 fonte para a qual os resultados de atributo são retornados. Não ficará vazio. |
objectType |
Tipo de objeto para o qual os resultados de atributo são retornados. Pode ficar vazio. |
operatorName |
O nome do operador escolhido para a criação de atributos. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
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 ( |
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 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 |
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 |
Filtro a ser transmitido na solicitação de pesquisa se o bucket correspondente for selecionado. |
value |
|
Informações de depuração
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 |
|
Contagens de resultados
Informações do número de resultados
Representação JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Campos | |
---|---|
sourceResultCounts[] |
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 ( |
Campos | |
---|---|
source |
A fonte associada às informações de contagem de resultados. |
hasMoreResults |
Indica se há mais resultados da pesquisa para esta fonte. |
Campo de união
|
|
resultCountEstimate |
A contagem de resultados estimada para esta origem. |
resultCountExact |
A contagem de resultados exata para essa origem. |