Method: query.search

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

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 in 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 se 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)

opzioni 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 di ricerca.

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 della query per la query dell'utente. Vuoto se l'interpretazione delle query è disattivata.
results[]

object (SearchResult)

Risultati di una query di ricerca.
structuredResults[]

object (StructuredResult)

Risultati strutturati per la query dell'utente. Questi risultati non vengono conteggiati ai fini del parametro pageSize.
spellResults[]

object (SpellResult)

Ortografia suggerita per la query.
facetResults[]

object (FacetResult)

Risultati delle sfaccettature ripetuti.
hasMoreResults

boolean

Se sono presenti altri risultati di ricerca corrispondenti alla query.
debugInfo

object (ResponseDebugInfo)

Informazioni di debug sulla risposta.
errorInfo

object (ErrorInfo)

Informazioni sull'errore relativo alla risposta.
resultCounts

object (ResultCounts)

Informazioni espanse sul conteggio dei risultati.

Campo unione result_count. Il conteggio totale dei risultati in tutte le origini dati richieste. Omesso se nel set di origini dati sottoposte a query sono incluse origini predefinite. I conteggi dei risultati potrebbero essere restituiti come stima, anziché esatti, nelle seguenti circostanze:

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

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

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

string (int64 format)

Il numero stimato di risultati 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 all'autorizzazione.

QueryInterpretationOptions

opzioni per interpretare la query dell'utente.

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

boolean

Indica se disattivare l'interpretazione delle query in linguaggio naturale (NL). Il valore predefinito è false. Imposta il valore true per disattivare l'interpretazione del linguaggio naturale. L'interpretazione in fiammingo 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 di risultati supplementari e l'utilizzo di sinonimi, inclusi quelli personalizzati. L'interpretazione in nl verrà disattivata se uno dei due flag è true.
disableSupplementalResults

boolean

Utilizza questo flag per disattivare i risultati supplementari per una query. L'impostazione dei risultati supplementari scelta a livello di SearchApplication avrà la precedenza se 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, le query con intent di linguaggio naturale come "email da Giovanni" verranno interpretate come "da:Giovanni origine:email". 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à UNSPECIFIED se il tipo di interpretazione non è NONE.

QueryInterpretation.InterpretationType

Enum
NONE Per recuperare i risultati di ricerca non viene utilizzata né 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 per cui questi altri risultati vengono combinati 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 dei termini delle query e dei documenti viene utilizzata per ampliare in modo selettivo la query in modo da recuperare ulteriori risultati di ricerca, poiché non sono stati trovati risultati sufficienti per la query dell'utente. La query interpretata sarà vuota per questa richiesta.

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 (riepiloghi) disponibili per questo risultato.
metadata

object (Metadata)

dei metadati del risultato di ricerca.
clusteredResults[]

object (SearchResult)

Se l'origine è raggruppata, fornisci un elenco dei risultati raggruppati. Verrà utilizzato un solo livello di risultati raggruppati. Se l'origine corrente 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 riassume i contenuti della pagina risultante.

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

string

Lo snippet del documento. Lo snippet del documento. Potrebbe contenere un carattere HTML con codice di escape che deve essere rimosso 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 corrispondente.

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 del 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 autore) del documento o dell'oggetto del risultato di ricerca.
createTime

string (Timestamp format)

La data e l'ora di creazione di questo documento o 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 viene impostato nell'elemento, il valore restituito qui è vuoto. Quando updateTime viene utilizzato per il calcolo dell'aggiornamento e non è impostato, il valore predefinito è 2 anni a partire dall'ora corrente.

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à denominate generiche.
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)

I contenuti delle metaline da visualizzare con il risultato.

ResultDisplayMetadata.ResultDisplayLine

La raccolta di campi che compongono una riga visualizzata

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Visualizza i campi per i risultati di query.search

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

string

L'etichetta visualizzata per la proprietà.
operatorName

string

Il nome dell'operatore della struttura.
property

object (NamedProperty)

La coppia di nome e 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 nell'ambito 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 ai componenti specifici dell'origine

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

string

Nome dell'origine per cui vengono restituiti i risultati del livello. Non sarà vuoto.
objectType

string

Tipo di oggetto per cui vengono restituiti i risultati delle sfaccettature. Può essere vuoto.
operatorName

string

Il nome dell'operatore scelto per la suddivisione in livelli. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets per i valori nella risposta contenenti almeno un risultato con il filtro corrispondente.

FacetBucket

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

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

integer

Numero di risultati corrispondenti al valore del bucket. I conteggi vengono restituiti per le ricerche solo quando è garantita la loro accuratezza. Cloud Search non garantisce il conteggio dei componenti per nessuna query e i conteggi dei componenti potrebbero essere presenti solo a intermittenza, anche per query identiche. Non creare dipendenze sull'esistenza del conteggio delle sfaccettature; utilizza invece le percentuali del conteggio delle sfaccettature che vengono sempre restituite.
percentage

integer

Percentuale di risultati che corrispondono al valore del bucket. Il valore restituito è compreso tra [0-100] e viene arrotondato per difetto a un numero intero se frazionario. Se il valore non viene restituito esplicitamente, rappresenta un valore percentuale arrotondato a 0. Le percentuali vengono restituite per tutte le ricerche, ma si tratta di una stima. Poiché vengono sempre restituite le percentuali, devi visualizzare le percentuali anziché i 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 relativo alla risposta.

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

object (ErrorMessage)

ErrorMessage

Messaggio di errore per risposta dell'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

Indica se sono presenti altri risultati di ricerca per questa origine.

Campo unione result_count.

result_count può essere solo uno dei seguenti:
resultCountEstimate

string (int64 format)

Il conteggio stimato dei risultati per questa origine.
resultCountExact

string (int64 format)

Il conteggio esatto dei risultati per questa origine.