- 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 per una query utente. I risultati possono provenire dalle app di Google Workspace, come Gmail o Google Drive, oppure da dati che hai indicizzato 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 le richieste 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, come l'applicazione di ricerca e il fuso orario dell'utente. |
query |
La stringa di query non elaborata. Scopri 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 il 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 di ricerca.
Rappresentazione JSON |
---|
{ "queryInterpretation": { object ( |
Campi | |
---|---|
queryInterpretation |
Risultato dell'interpretazione della query dell'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 per pageSize. |
spellResults[] |
Ortografia suggerita per la query. |
facetResults[] |
Risultati facet ripetuti. |
hasMoreResults |
Se ci sono 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 estese. |
Campo unione
Nel raro caso in cui il sistema non sia in grado di cercare in tutti i documenti, esegui nuovamente la query. |
|
resultCountEstimate |
Il conteggio stimato dei risultati per questa query. |
resultCountExact |
Il numero 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
per interpretare la query dell'utente.
Rappresentazione JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Campi | |
---|---|
disableNlInterpretation |
Flag per disabilitare l'interpretazione in linguaggio naturale (NL) delle query. Il valore predefinito è false. Impostalo su true per disattivare l'interpretazione in linguaggio naturale. L'interpretazione NL si applica solo alle origini dati predefinite. |
enableVerbatimMode |
Abilita questo flag per disattivare tutte le ottimizzazioni interne come l'interpretazione in linguaggio naturale (NL) delle query, il recupero supplementare dei risultati e l'utilizzo di sinonimi, inclusi quelli personalizzati. L'interpretazione Nl verrà disabilitata se uno dei due flag è true. |
disableSupplementalResults |
Utilizza questo flag per disattivare risultati supplementari per una query. Se il criterio è impostato su True, l'impostazione dei risultati supplementari scelta a livello di applicazione di ricerca avrà la precedenza. |
QueryInterpretation
Rappresentazione JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Campi | |
---|---|
interpretedQuery |
L'interpretazione della query utilizzata nella ricerca. Ad esempio, query con intent in linguaggio naturale come "email da mario" verrà interpretata 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 verrà ANNULLATO se il tipo di interpretazione non è NESSUNA. |
QueryInterpretation.InterpretationType
Enum | |
---|---|
NONE |
Per recuperare i risultati di ricerca non vengono utilizzati né l'interpretazione in linguaggio naturale né una versione più ampia della query. |
BLEND |
I risultati della query originale vengono uniti ad altri risultati. Il motivo per la combinazione di questi altri risultati con i risultati della query originale viene compilato nella sezione "Motivo" campo sottostante. |
REPLACE |
I risultati della query originale vengono sostituiti. Il motivo per la sostituzione dei risultati della query originale viene inserito nel campo "Motivo" campo sottostante. |
QueryInterpretation.Reason
Enum | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
Per recuperare i risultati della ricerca, viene utilizzata l'interpretazione in linguaggio naturale della query. |
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 è stato trovato un numero sufficiente di risultati 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 Google all'elemento effettivo. Questo URL è firmato e non deve essere modificato. |
snippet |
La concatenazione di tutti gli snippet (riepiloghi) disponibili per questo risultato. |
metadata |
metadati del risultato di ricerca. |
clusteredResults[] |
Se l'origine è in cluster, fornisci un elenco di risultati in cluster. Ci sarà solo un livello di risultati raggruppati. 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 riassume 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 rimosso da caratteri di escape prima del rendering. |
matchRanges[] |
Gli intervalli corrispondenti nello snippet. |
MatchRange
Intervallo corrispondente di uno snippet [inizio, fine).
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 corrispondente.
Rappresentazione JSON |
---|
{ "source": { object ( |
Campi | |
---|---|
source |
L'origine denominata del risultato, ad esempio Gmail. |
mimeType |
Tipo MIME del risultato di ricerca. |
thumbnailUrl |
L'URL della miniatura del risultato. |
owner |
proprietario (di solito 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 nel formato RFC3339 UTC "Zulu" 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. Se per il calcolo dell'aggiornamento viene utilizzato Un timestamp nel formato RFC3339 UTC "Zulu" con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: |
fields[] |
Campi indicizzati nei dati strutturati, restituiti come proprietà con nome generico. |
displayOptions |
opzioni che specificano come visualizzare un risultato di ricerca di dati strutturati. |
objectType |
Tipo di oggetto del risultato di ricerca. |
ResultDisplayMetadata
Rappresentazione JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Campi | |
---|---|
objectTypeLabel |
L'etichetta da visualizzare per l'oggetto. |
metalines[] |
I contenuti delle metaline da visualizzare con il risultato. |
ResultDisplayMetadata.ResultDisplayLine
La raccolta dei campi che compongono una linea visualizzata
Rappresentazione JSON |
---|
{
"fields": [
{
object ( |
Campi | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Visualizza i campi per i risultati query.search
Rappresentazione JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Campi | |
---|---|
label |
L'etichetta da visualizzare per la proprietà. |
operatorName |
Il nome dell'operatore della proprietà. |
property |
La coppia nome-valore della 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 di origine per cui vengono restituiti i risultati dei facet. Il campo non sarà vuoto. |
objectType |
Tipo di oggetto per cui vengono restituiti i risultati dei facet. Può essere vuoto. |
operatorName |
Il nome dell'operatore scelto per il faceting. @vedi cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBucket per i valori in una risposta contenente almeno un singolo risultato con il filtro corrispondente. |
FacetBucket
Un bucket in un facet è l'unità di base operativa. Un bucket può comprendere un singolo valore O un intervallo di valori contiguo, a seconda del tipo di campo in bucket. FacetBucket viene attualmente utilizzato solo per restituire l'oggetto di risposta.
Rappresentazione JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Campi | |
---|---|
count |
Numero di risultati corrispondenti al valore del bucket. I conteggi vengono restituiti per le ricerche solo quando è garantita la precisione del conteggio. Cloud Search non garantisce che i conteggi dei facet per qualsiasi query e i conteggi dei facet siano presenti solo a intermittenza, anche per query identiche. Non creare dipendenze sull'esistenza del conteggio dei facet. al contrario usano le percentuali di scarto dei facet che vengono sempre restituite. |
percentage |
Percentuale di risultati che corrispondono al valore del bucket. Il valore restituito è compreso tra 0 e 100 e viene arrotondato per difetto a un numero intero se frazionario. Se non viene restituito esplicitamente, il valore rappresenta un valore percentuale arrotondato a 0. Le percentuali vengono restituite per tutte le ricerche, ma sono una stima. Poiché le percentuali vengono sempre restituite, dovresti visualizzare le percentuali anziché i 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 dell'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 fonte 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 esistono altri risultati di ricerca per questa fonte. |
Campo unione
|
|
resultCountEstimate |
Il conteggio dei risultati stimato per questa origine. |
resultCountExact |
Il numero esatto dei risultati per questa origine. |