Method: query.search

L'API Cloud Search Query fornisce il metodo di ricerca, che restituisce i risultati più pertinenti della query dell'utente. I risultati possono provenire da app di Google Workspace, come Gmail o Google Drive, oppure da dati indicizzati da una terza parte.

Nota:per l'esecuzione di questa API è necessario un account utente finale standard. Un account di servizio non può eseguire direttamente richieste all'API Query. Per utilizzare un account di servizio per eseguire query, configura la delega dell'autorità a livello di dominio di Google Workspace.

Richiesta HTTP

POST https://cloudsearch.googleapis.com/v1/query/search

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione 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)
    }
  ]
}
Campi
requestOptions

object (RequestOptions)

Opzioni di richiesta, ad esempio l'applicazione di ricerca e il fuso orario dell'utente.
query

string

La stringa di query non elaborata. Consulta gli operatori di ricerca supportati nella sezione Restringere la ricerca con gli operatori
pageSize

integer

Numero massimo di risultati di ricerca da restituire in una pagina. I valori validi sono compresi tra 1 e 100 inclusi. Il valore predefinito è 10. Il valore minimo è 50 quando vengono richiesti risultati oltre 2000.
start

integer

Indice iniziale dei risultati.
dataSourceRestrictions[]

object (DataSourceRestriction)

Le origini da utilizzare per le query. Se non specificato, vengono utilizzate tutte le origini dati dell'applicazione di ricerca corrente.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Le opzioni per ordinare i risultati di ricerca
queryInterpretationOptions

object (QueryInterpretationOptions)

per interpretare la query dell'utente.
contextAttributes[]

object (ContextAttribute)

Attributi di contesto per la richiesta che verranno utilizzati per modificare il ranking dei risultati di ricerca. Il numero massimo di elementi è 10.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

La risposta dell'API Search.

Rappresentazione 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.
}
Campi
queryInterpretation

object (QueryInterpretation)

Risultato dell'interpretazione delle query per la query utente. Vuoto se l'interpretazione della query è disabilitata.
results[]

object (SearchResult)

Risultati di una query di ricerca.
structuredResults[]

object (StructuredResult)

Risultati strutturati per la query dell'utente. Questi risultati non vengono conteggiati nella paginaSize.
spellResults[]

object (SpellResult)

Ortografia suggerita per la query.
facetResults[]

object (FacetResult)

Risultati facet ripetuti.
hasMoreResults

boolean

Se sono presenti più risultati di ricerca corrispondenti alla query.
debugInfo

object (ResponseDebugInfo)

Informazioni di debug sulla risposta.
errorInfo

object (ErrorInfo)

Informazioni sull'errore nella risposta.
resultCounts

object (ResultCounts)

Informazioni sul conteggio dei risultati espansi.

Campo di unione result_count. Il conteggio totale dei risultati in tutte le origini dati richieste. Omissione se le origini predefinite sono incluse nel set di origini dati su cui è stata eseguita la query. I conteggi dei risultati potrebbero essere restituiti come stima, anziché come esatta, nei seguenti casi:

  • Quando la query contiene più di due termini in una frase, ad esempio "conteggio risultato esatto" tra virgolette.

  • Quando il numero di ACL dei risultati di ricerca univoci da valutare è troppo elevato per il calcolo con una latenza ragionevole.

Nei rari casi in cui il sistema non sia in grado di eseguire ricerche in tutti i documenti, esegui nuovamente la query. result_count può essere solo uno dei seguenti:
resultCountEstimate

string (int64 format)

Il conteggio dei risultati stimati per questa query.
resultCountExact

string (int64 format)

Il conteggio esatto dei risultati per questa query.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud_search.query
  • https://www.googleapis.com/auth/cloud_search

Per ulteriori informazioni, consulta la Guida alle autorizzazioni.

QueryInterpretationOptions

per interpretare la query dell'utente.

Rappresentazione JSON 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Campi
disableNlInterpretation

boolean

Segnala per disattivare l'interpretazione delle query in linguaggio naturale (NL). Il valore predefinito è false. Impostalo su true per disattivare l'interpretazione del linguaggio naturale. L'interpretazione NL si applica solo alle origini dati predefinite.
enableVerbatimMode

boolean

Attiva questo flag per disattivare tutte le ottimizzazioni interne come l'interpretazione delle query in linguaggio naturale (NL), il recupero supplementare di risultati e l'utilizzo di sinonimi, inclusi quelli personalizzati. L'interpretazione Nl verrà disattivata se uno dei due flag è vero.
disableSupplementalResults

boolean

Utilizza questo flag per disabilitare i risultati supplementari per una query. L'impostazione dei risultati supplementari scelta a livello di SearchApplication ha la precedenza se viene impostata su True.

QueryInterpretation

Rappresentazione JSON 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Campi
interpretedQuery

string

L'interpretazione della query utilizzata nella ricerca. Ad esempio, query con un intento di linguaggio naturale come "email da giovanni" verranno interpretate come "from:john source:mail". Questo campo non verrà compilato se il motivo è NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Il motivo dell'interpretazione della query. Questo campo non sarà NON SPECIFICATO se il tipo di interpretazione non è NESSUNO.

QueryInterpretation.InterpretationType

Enum
NONE Per recuperare i risultati di ricerca, non vengono utilizzate l'interpretazione in linguaggio naturale né una versione più ampia della query.
BLEND I risultati della query originale vengono combinati con altri risultati. Il motivo della combinazione di questi altri risultati con i risultati della query originale viene inserito nel campo "Motivo" di seguito.
REPLACE I risultati della query originale vengono sostituiti. Il motivo della sostituzione dei risultati della query originale viene inserito nel campo "Motivo" di seguito.

QueryInterpretation.Reason

Enum
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Per recuperare i risultati di ricerca, viene utilizzata l'interpretazione della query in linguaggio naturale.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La somiglianza tra termini di query e documenti viene utilizzata per ampliare selettivamente la query al fine di recuperare ulteriori risultati di ricerca, poiché non sono stati trovati risultati sufficienti per la query dell'utente. La query interpretata sarà vuota per questo caso.

SearchResult

Risultati contenenti informazioni indicizzate per un documento.

Rappresentazione JSON 
{
  "title": string,
  "url": string,
  "snippet": {
    object (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Campi
title

string

Titolo del risultato di ricerca.
url

string

L'URL del risultato di ricerca. L'URL contiene un reindirizzamento di Google all'articolo effettivo. Questo URL è firmato e non deve essere modificato.
snippet

object (Snippet)

La concatenazione di tutti gli snippet (riepilogo) disponibili per questo risultato.
metadata

object (Metadata)

metadati del risultato della ricerca.
clusteredResults[]

object (SearchResult)

Se l'origine è in cluster, fornisci un elenco dei risultati in cluster. Ci sarà un solo livello di risultati in cluster. Se l'origine attuale non è abilitata per il clustering, questo campo sarà vuoto.
debugInfo

object (ResultDebugInfo)

Informazioni di debug su questo risultato di ricerca.

Snippet

Snippet del risultato di ricerca, che riepiloga i contenuti della pagina risultante.

Rappresentazione JSON 
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Campi
snippet

string

Lo snippet del documento. Lo snippet del documento. Può contenere un carattere HTML di escape che deve essere privo di caratteri di escape prima del rendering.
matchRanges[]

object (MatchRange)

Gli intervalli corrispondenti nello snippet.

MatchRange

Intervallo corrispondente di uno snippet [start, end).

Rappresentazione JSON 
{
  "start": integer,
  "end": integer
}
Campi
start

integer

Posizione iniziale della corrispondenza nello snippet.
end

integer

Fine della corrispondenza nello snippet.

Metadati

metadati di un risultato di ricerca con corrispondenza.

Rappresentazione JSON 
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Campi
source

object (Source)

L'origine denominata per il risultato, ad esempio Gmail.
mimeType

string

Tipo MIME del risultato di ricerca.
thumbnailUrl

string

L'URL della miniatura del risultato.
owner

object (Person)

proprietario (di solito l'autore) del documento o dell'oggetto del risultato di ricerca.
createTime

string (Timestamp format)

L'ora di creazione del documento o dell'oggetto nel risultato di ricerca.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

La data dell'ultima modifica dell'oggetto nel risultato di ricerca. Se non è impostato nell'elemento, il valore restituito qui è vuoto. Quando updateTime viene utilizzato per calcolare l'aggiornamento e non è impostato, per impostazione predefinita questo valore corrisponde a due anni dall'ora attuale.

Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
fields[]

object (NamedProperty)

Campi indicizzati nei dati strutturati, restituiti come proprietà denominata generica.
displayOptions

object (ResultDisplayMetadata)

opzioni che specificano come visualizzare un risultato di ricerca con dati strutturati.
objectType

string

Tipo di oggetto del risultato di ricerca.

ResultDisplayMetadata

Rappresentazione JSON 
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Campi
objectTypeLabel

string

L'etichetta di visualizzazione dell'oggetto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Il contenuto delle metaline da visualizzare con il risultato.

ResultDisplayMetadata.ResultDisplayLine

L'insieme di campi che compongono una linea visualizzata

Rappresentazione JSON 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Campi
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Visualizza campi per i risultati query.search

Rappresentazione JSON 
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Campi
label

string

L'etichetta di visualizzazione della proprietà.
operatorName

string

Il nome dell'operatore della proprietà.
property

object (NamedProperty)

La coppia nome-valore per la proprietà.

ResultDebugInfo

Informazioni di debug sul risultato.

Rappresentazione JSON 
{
  "formattedDebugInfo": string
}
Campi
formattedDebugInfo

string

Informazioni di debug generali formattate per la visualizzazione.

StructuredResult

Risultati strutturati restituiti come parte della richiesta di ricerca.

Rappresentazione JSON 
{
  "person": {
    object (Person)
  }
}
Campi
person

object (Person)

Rappresentazione di una persona

SpellResult

Rappresentazione JSON 
{
  "suggestedQuery": string
}
Campi
suggestedQuery

string

L'ortografia suggerita della query.

FacetResult

Risposta facet specifica di origine

Rappresentazione JSON 
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Campi
sourceName

string

Nome dell'origine per il quale vengono restituiti i risultati dei facet. Il campo non sarà vuoto.
objectType

string

Tipo di oggetto per il quale vengono restituiti i risultati dei facet. Può essere vuoto.
operatorName

string

Il nome dell'operatore scelto per il faceting. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBucket per i valori in risposta contenenti almeno un singolo risultato con il filtro corrispondente.

FacetBucket

Un bucket in un facet è l'unità di base dell'operazione. Un bucket può comprendere un singolo valore OPPURE un intervallo contiguo di valori, a seconda del tipo di bucket di campo. FacetBucket è attualmente utilizzato solo per restituire l'oggetto risposta.

Rappresentazione JSON 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Campi
count

integer

Numero di risultati che corrispondono al valore del bucket. I conteggi vengono restituiti per le ricerche solo quando è garantita la precisione del conteggio. Cloud Search non garantisce il conteggio dei facet per qualsiasi query, che potrebbe essere presente solo a intermittenza, anche per query identiche. Non creare dipendenze sull'esistenza del conteggio dei facet; utilizza invece le percentuali di facet ount che vengono sempre restituite.
percentage

integer

Percentuale di risultati che corrisponde al valore del bucket. Il valore restituito è compreso tra (0-100] ed è arrotondato per difetto a un numero intero se frazionario. Se il valore non viene restituito esplicitamente, rappresenta una percentuale che viene arrotondata a 0. Per tutte le ricerche vengono restituite percentuali percentuali, ma rappresentano una stima. Poiché le percentuali vengono sempre restituite, è necessario eseguire il rendering delle percentuali anziché dei conteggi.
filter

object (Filter)

Filtro da passare nella richiesta di ricerca se è selezionato il bucket corrispondente.
value

object (Value)

ResponseDebugInfo

Informazioni di debug sulla risposta.

Rappresentazione JSON 
{
  "formattedDebugInfo": string
}
Campi
formattedDebugInfo

string

Informazioni di debug generali formattate per la visualizzazione.

ErrorInfo

Informazioni sull'errore nella risposta.

Rappresentazione JSON 
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Campi
errorMessages[]

object (ErrorMessage)

ErrorMessage

Messaggio di errore per risposta di origine.

Rappresentazione JSON 
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Campi
source

object (Source)
errorMessage

string

ResultCounts

Informazioni sul conteggio dei risultati

Rappresentazione JSON 
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Campi
sourceResultCounts[]

object (SourceResultCount)

Informazioni sul conteggio dei risultati per ogni origine con risultati.

SourceResultCount

Informazioni sul conteggio dei risultati per origine.

Rappresentazione 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.
}
Campi
source

object (Source)

L'origine a cui sono associate le informazioni sul conteggio dei risultati.
hasMoreResults

boolean

Se sono presenti altri risultati di ricerca per questa fonte.

Campo di unione result_count.

result_count può essere solo uno dei seguenti:
resultCountEstimate

string (int64 format)

Il conteggio dei risultati stimati per questa origine.
resultCountExact

string (int64 format)

Il conteggio esatto dei risultati per questa origine.