Method: query.search

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

Nota:questa API richiede l'esecuzione di un account utente finale standard. Un service account non può eseguire direttamente richieste API di query; per utilizzare un service account per eseguire query, configura la delega dell'autorità a livello di dominio 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. Consulta gli operatori di ricerca supportati nella sezione Restringere la ricerca con gli operatori.
pageSize

integer

Il 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 fonti da utilizzare per le query. Se non specificate, vengono utilizzate tutte le origini dati dell'applicazione di ricerca corrente.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

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

La risposta dell'API di ricerca. NEXT id: 19

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

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 è 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 rispetto a pageSize.
spellResults[]

object (SpellResult)

Ortografia suggerita per la query.
facetResults[]

object (FacetResult)

Risultati ripetuti dei facet.
hasMoreResults

boolean

Se ci sono 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 sul conteggio dei risultati espanse.

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. Il conteggio dei risultati potrebbe essere restituito come stima anziché come valore esatto nei seguenti casi:

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

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

Nel raro caso in cui il sistema non riesca a eseguire la ricerca in tutti i documenti, esegui di nuovo la query. result_count può essere solo uno dei seguenti tipi:
resultCountEstimate

string (int64 format)

Il conteggio dei risultati stimato 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

Flag per disattivare l'interpretazione in linguaggio naturale (NL) delle query. Il valore predefinito è false. Imposta true per disattivare l'interpretazione del linguaggio naturale. L'interpretazione del linguaggio naturale 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 del linguaggio naturale 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),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
Campi
interpretedQuery

string

L'interpretazione della query utilizzata nella ricerca. Ad esempio, le query con intento in linguaggio naturale come "email da mario" verranno interpretate come "da:mario origine:posta". Questo campo non verrà compilato quando 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.
interpretedQueryActualResultCount

integer

Il numero effettivo di risultati restituiti dalla query interpretata.
interpretedQueryEstimatedResultCount

string (int64 format)

Il numero stimato di risultati restituiti dalla query interpretata.

QueryInterpretation.InterpretationType

Enum
NONE Per recuperare i risultati di ricerca non vengono utilizzate né l'interpretazione in linguaggio naturale né una versione più generica della query.
BLEND I risultati della query originale vengono combinati con altri risultati. Il motivo per cui questi altri risultati vengono combinati con quelli 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 in linguaggio naturale della query.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY La somiglianza tra i termini della query e del documento viene utilizzata per ampliare selettivamente la query per recuperare risultati di ricerca aggiuntivi, 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. ID successivo: 16

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

string

il titolo del risultato di ricerca.
url

string

L'URL del risultato di ricerca. L'URL contiene un reindirizzamento di 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 è raggruppata, fornisci un elenco dei risultati raggruppati. Esiste 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. Potrebbe contenere un carattere HTML con escape che deve essere rimosso 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 partita 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 il creatore) del documento o dell'oggetto del risultato di ricerca.
createTime

string (Timestamp format)

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

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

La data dell'ultima modifica dell'oggetto nel risultato di ricerca. Se non è impostato nell'articolo, il valore restituito qui è vuoto. Quando updateTime viene utilizzato per calcolare la freschezza e non è impostato, questo valore viene impostato per impostazione predefinita su 2 anni a partire dall'ora corrente.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
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 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 visualizzata per l'oggetto.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

I contenuti delle metalinee da visualizzare con il risultato.

ResultDisplayMetadata.ResultDisplayLine

L'insieme 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 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 nell'ambito della richiesta di ricerca.

Rappresentazione JSON 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Campi

Campo unione structured_result.

structured_result può essere solo uno dei seguenti tipi:
person

object (Person)

Rappresentazione di una persona

SpellResult

Rappresentazione JSON 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Campi
suggestedQuery

string

L'ortografia suggerita della query.
suggestionType

enum (SpellResult.SuggestionType)

suggerimento attivato per la query corrente.
suggestedQueryHtml

object (SafeHtmlProto)

L'HTML sottoposto a sanitizzazione che rappresenta la query con correzione ortografica che può essere utilizzata nella UI. In genere, contiene tag specifici per la lingua per contrassegnare le parti della query sottoposte al controllo ortografico.

SpellResult.SuggestionType

Il tipo di suggerimento attivato per la query.

Enum
SUGGESTION_TYPE_UNSPECIFIED Tipo di controllo ortografico predefinito
NON_EMPTY_RESULTS_SPELL_SUGGESTION Suggerimento ortografico senza risultati modificati. I risultati vengono comunque mostrati per la query originale (che ha risultati diversi da zero) con un suggerimento per l'ortografia che avrebbe risultati.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Suggerimento ortografico attivato quando la query originale non restituisce risultati. Quando la query originale non ha risultati e il suggerimento ortografico ne ha, attiviamo i risultati per la query con correzione ortografica.

SafeHtmlProto

IMPORTANTE: non è sicuro accettare questo messaggio da un'origine non attendibile, poiché è banale per un malintenzionato falsificare messaggi serializzati che non soddisfano il contratto di sicurezza del tipo. Ad esempio, potrebbe contenere script controllati da un malintenzionato. Un sistema che riceve un SafeHtmlProto considera implicitamente attendibile il produttore di SafeHtmlProto. Pertanto, in genere è sicuro restituire questo messaggio nelle risposte RPC, ma in genere non è sicuro accettarlo nelle richieste RPC.

Rappresentazione JSON 
{
  "privateDoNotAccessOrElseSafeHtmlWrappedValue": string
}
Campi
privateDoNotAccessOrElseSafeHtmlWrappedValue

string

IMPORTANTE: non impostare o leggere mai questo campo, nemmeno dai test, è privato. Consulta la documentazione nella parte superiore del file .proto per i pacchetti di linguaggi di programmazione con cui creare o leggere questo messaggio.

FacetResult

Risposta alla sfaccettatura specifica 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 delle sfaccettature. 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 la sfaccettatura. @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 sfaccettatura è l'unità di base dell'operazione. Un bucket può comprendere un singolo valore O un intervallo contiguo di valori, a seconda del tipo di campo inserito nel bucket. FacetBucket viene attualmente utilizzato solo per restituire l'oggetto risposta.

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Campi
count

integer

Numero di risultati che corrispondono al valore del bucket. I conteggi vengono restituiti solo per le ricerche per le quali è garantita l'accuratezza del conteggio. Cloud Search non garantisce i conteggi delle sfaccettature per nessuna query e i conteggi delle sfaccettature potrebbero essere presenti solo in modo intermittente, anche per query identiche. Non creare dipendenze dall'esistenza del conteggio delle sfaccettature; utilizza invece le percentuali di 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 in modo esplicito, rappresenta un valore percentuale che viene arrotondato a 0. Le percentuali vengono restituite per tutte le ricerche, ma sono una stima. Poiché le percentuali vengono sempre restituite, devi visualizzare le percentuali anziché i conteggi.
filter

object (Filter)

Filtro da passare nella richiesta di ricerca se viene selezionato il bucket corrispondente.
Campo unione bucket_value. L'intervallo o il valore del bucket sfaccettato bucket_value può essere solo uno dei seguenti:
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 della sorgente.

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 fonte.

Campo unione result_count.

result_count può essere solo uno dei seguenti tipi:
resultCountEstimate

string (int64 format)

Il conteggio stimato dei risultati per questa origine.
resultCountExact

string (int64 format)

Il conteggio esatto dei risultati per questa fonte.