Method: query.search

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 (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, come l'applicazione di ricerca e il fuso orario dell'utente.
query

string

La stringa di query non elaborata. Scopri 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 il 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 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 dell'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 per pageSize.
spellResults[]

object (SpellResult)

Ortografia suggerita per la query.
facetResults[]

object (FacetResult)

Risultati facet ripetuti.
hasMoreResults

boolean

Se ci sono 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 estese.

Campo unione result_count. Il conteggio totale dei risultati in tutte le origini dati richieste. Omesso se le origini predefinite sono incluse nel set di origini dati sottoposte a query. Nei seguenti casi, è possibile che i conteggi dei risultati vengano restituiti come stima, anziché come esatta:

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

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

Nel raro caso in cui il sistema non sia in grado di cercare in tutti i documenti, esegui nuovamente la query. result_count può essere solo uno dei seguenti:
resultCountEstimate

string (int64 format)

Il conteggio stimato dei risultati per questa query.
resultCountExact

string (int64 format)

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

boolean

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

boolean

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

boolean

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 (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Campi
interpretedQuery

string

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

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.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 (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 Google all'elemento 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)

metadati del risultato di ricerca.
clusteredResults[]

object (SearchResult)

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

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. Può contenere un carattere HTML di escape che deve essere rimosso da caratteri di escape prima del rendering.
matchRanges[]

object (MatchRange)

Gli intervalli corrispondenti nello snippet.

MatchRange

Intervallo corrispondente di uno snippet [inizio, fine).

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)

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: "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. Se per il calcolo dell'aggiornamento viene utilizzato updateTime e non è impostato, questo valore è impostato in modo predefinito su 2 anni dall'ora attuale.

Un timestamp nel formato RFC3339 UTC "Zulu" 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à con nome generico.
displayOptions

object (ResultDisplayMetadata)

opzioni che specificano come visualizzare un risultato di ricerca di 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 da visualizzare per l'oggetto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

I contenuti delle metaline da visualizzare con il risultato.

ResultDisplayMetadata.ResultDisplayLine

La raccolta dei campi che compongono una linea visualizzata

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

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Visualizza i campi per i risultati query.search

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

string

L'etichetta da visualizzare per la proprietà.
operatorName

string

Il nome dell'operatore della proprietà.
property

object (NamedProperty)

La coppia nome-valore della 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 di origine per cui vengono restituiti i risultati dei facet. Il campo non sarà vuoto.
objectType

string

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

string

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

object (FacetBucket)

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 (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 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

integer

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

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 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 fonte 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 esistono altri risultati di ricerca per questa fonte.

Campo unione result_count.

result_count può essere solo uno dei seguenti:
resultCountEstimate

string (int64 format)

Il conteggio dei risultati stimato per questa origine.
resultCountExact

string (int64 format)

Il numero esatto dei risultati per questa origine.