- Richiesta HTTP
- Corpo della richiesta
- Corpo della risposta
- Ambiti di autorizzazione
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Snippet
- MatchRange
- Metadati
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- Prova!
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 ( |
Campi | |
---|---|
requestOptions |
Opzioni di richiesta, ad esempio l'applicazione di ricerca e il fuso orario dell'utente. |
query |
La stringa di query non elaborata. Consulta gli operatori di ricerca supportati nella sezione Restringere la ricerca con gli operatori |
pageSize |
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 |
Indice iniziale dei risultati. |
dataSourceRestrictions[] |
Le origini da utilizzare per le query. Se non specificato, vengono utilizzate tutte le origini dati dell'applicazione di ricerca corrente. |
facetOptions[] |
|
sortOptions |
Le opzioni per ordinare i risultati di ricerca |
queryInterpretationOptions |
per interpretare la query dell'utente. |
contextAttributes[] |
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 ( |
Campi | |
---|---|
queryInterpretation |
Risultato dell'interpretazione delle query per la query utente. Vuoto se l'interpretazione della query è disabilitata. |
results[] |
Risultati di una query di ricerca. |
structuredResults[] |
Risultati strutturati per la query dell'utente. Questi risultati non vengono conteggiati nella paginaSize. |
spellResults[] |
Ortografia suggerita per la query. |
facetResults[] |
Risultati facet ripetuti. |
hasMoreResults |
Se sono presenti più risultati di ricerca corrispondenti alla query. |
debugInfo |
Informazioni di debug sulla risposta. |
errorInfo |
Informazioni sull'errore nella risposta. |
resultCounts |
Informazioni sul conteggio dei risultati espansi. |
Campo di unione
Nei rari casi in cui il sistema non sia in grado di eseguire ricerche in tutti i documenti, esegui nuovamente la query. |
|
resultCountEstimate |
Il conteggio dei risultati stimati per questa query. |
resultCountExact |
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 |
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 |
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 |
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 ( |
Campi | |
---|---|
interpretedQuery |
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 |
|
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 ( |
Campi | |
---|---|
title |
Titolo del risultato di ricerca. |
url |
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 |
La concatenazione di tutti gli snippet (riepilogo) disponibili per questo risultato. |
metadata |
metadati del risultato della ricerca. |
clusteredResults[] |
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 |
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 ( |
Campi | |
---|---|
snippet |
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[] |
Gli intervalli corrispondenti nello snippet. |
MatchRange
Intervallo corrispondente di uno snippet [start, end).
Rappresentazione JSON |
---|
{ "start": integer, "end": integer } |
Campi | |
---|---|
start |
Posizione iniziale della corrispondenza nello snippet. |
end |
Fine della corrispondenza nello snippet. |
Metadati
metadati di un risultato di ricerca con corrispondenza.
Rappresentazione JSON |
---|
{ "source": { object ( |
Campi | |
---|---|
source |
L'origine denominata per il risultato, ad esempio Gmail. |
mimeType |
Tipo MIME del risultato di ricerca. |
thumbnailUrl |
L'URL della miniatura del risultato. |
owner |
proprietario (di solito l'autore) del documento o dell'oggetto del risultato di ricerca. |
createTime |
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: |
updateTime |
La data dell'ultima modifica dell'oggetto nel risultato di ricerca. Se non è impostato nell'elemento, il valore restituito qui è vuoto. Quando Un timestamp in formato "Zulu" UTC RFC3339, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: |
fields[] |
Campi indicizzati nei dati strutturati, restituiti come proprietà denominata generica. |
displayOptions |
opzioni che specificano come visualizzare un risultato di ricerca con dati strutturati. |
objectType |
Tipo di oggetto del risultato di ricerca. |
ResultDisplayMetadata
Rappresentazione JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Campi | |
---|---|
objectTypeLabel |
L'etichetta di visualizzazione dell'oggetto. |
metalines[] |
Il contenuto delle metaline da visualizzare con il risultato. |
ResultDisplayMetadata.ResultDisplayLine
L'insieme di campi che compongono una linea visualizzata
Rappresentazione JSON |
---|
{
"fields": [
{
object ( |
Campi | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Visualizza campi per i risultati query.search
Rappresentazione JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Campi | |
---|---|
label |
L'etichetta di visualizzazione della proprietà. |
operatorName |
Il nome dell'operatore della proprietà. |
property |
La coppia nome-valore per la proprietà. |
ResultDebugInfo
Informazioni di debug sul risultato.
Rappresentazione JSON |
---|
{ "formattedDebugInfo": string } |
Campi | |
---|---|
formattedDebugInfo |
Informazioni di debug generali formattate per la visualizzazione. |
StructuredResult
Risultati strutturati restituiti come parte della richiesta di ricerca.
Rappresentazione JSON |
---|
{
"person": {
object ( |
Campi | |
---|---|
person |
Rappresentazione di una persona |
SpellResult
Rappresentazione JSON |
---|
{ "suggestedQuery": string } |
Campi | |
---|---|
suggestedQuery |
L'ortografia suggerita della query. |
FacetResult
Risposta facet specifica di origine
Rappresentazione JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Campi | |
---|---|
sourceName |
Nome dell'origine per il quale vengono restituiti i risultati dei facet. Il campo non sarà vuoto. |
objectType |
Tipo di oggetto per il quale vengono restituiti i risultati dei facet. Può essere vuoto. |
operatorName |
Il nome dell'operatore scelto per il faceting. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
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 ( |
Campi | |
---|---|
count |
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 |
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 |
Filtro da passare nella richiesta di ricerca se è selezionato il bucket corrispondente. |
value |
|
ResponseDebugInfo
Informazioni di debug sulla risposta.
Rappresentazione JSON |
---|
{ "formattedDebugInfo": string } |
Campi | |
---|---|
formattedDebugInfo |
Informazioni di debug generali formattate per la visualizzazione. |
ErrorInfo
Informazioni sull'errore nella risposta.
Rappresentazione JSON |
---|
{
"errorMessages": [
{
object ( |
Campi | |
---|---|
errorMessages[] |
|
ErrorMessage
Messaggio di errore per risposta di origine.
Rappresentazione JSON |
---|
{
"source": {
object ( |
Campi | |
---|---|
source |
|
errorMessage |
|
ResultCounts
Informazioni sul conteggio dei risultati
Rappresentazione JSON |
---|
{
"sourceResultCounts": [
{
object ( |
Campi | |
---|---|
sourceResultCounts[] |
Informazioni sul conteggio dei risultati per ogni origine con risultati. |
SourceResultCount
Informazioni sul conteggio dei risultati per origine.
Rappresentazione JSON |
---|
{ "source": { object ( |
Campi | |
---|---|
source |
L'origine a cui sono associate le informazioni sul conteggio dei risultati. |
hasMoreResults |
Se sono presenti altri risultati di ricerca per questa fonte. |
Campo di unione
|
|
resultCountEstimate |
Il conteggio dei risultati stimati per questa origine. |
resultCountExact |
Il conteggio esatto dei risultati per questa origine. |