L'API Query fornisce metodi di ricerca e di suggerimento per creare un'interfaccia di ricerca o incorporare i risultati di ricerca in un'applicazione.
Per le applicazioni web con requisiti minimi, valuta l'utilizzo del widget di ricerca. Per scoprire di più, consulta Creare un'interfaccia di ricerca con il widget Ricerca
Crea un'interfaccia di ricerca
La creazione di un'interfaccia di ricerca minima richiede diversi passaggi:
- Configura un'applicazione di ricerca
- Generare le credenziali OAuth per l'applicazione
- Esegui una query sull'indice
- Visualizzare i risultati della query
Puoi migliorare ulteriormente l'interfaccia di ricerca con funzionalità come impaginazione, ordinamento, filtri, facet e suggerimenti automatici.
Configura un'applicazione di ricerca
Devi creare almeno un'applicazione di ricerca da associare a ogni interfaccia di ricerca creata. Un'applicazione di ricerca fornisce i parametri predefiniti per una query, ad esempio le origini dati da utilizzare, l'ordinamento, i filtri e i facet da richiedere. Se necessario, puoi sostituire questi parametri utilizzando l'API di query.
Per ulteriori informazioni sulle applicazioni di ricerca, consulta Personalizzare l'esperienza di ricerca in Cloud Search.
Generare le credenziali OAuth per l'applicazione
Oltre ai passaggi descritti in Configurare l'accesso all'API Google Cloud Search, devi generare le credenziali OAuth per l'applicazione web. Il tipo di credenziali che crei dipende dal contesto in cui viene utilizzata l'API.
Utilizza le credenziali per richiedere l'autorizzazione per conto dell'utente. Utilizza l'ambito https://www.googleapis.com/auth/cloud_search.query
quando richiedi l'autorizzazione.
Per ulteriori informazioni sulle opzioni e sulle librerie client OAuth, consulta [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).
Esegui una query sull'indice
Utilizza il metodo search
per eseguire ricerche nell'indice.
Ogni richiesta deve includere due informazioni: un testo query
per la corrispondenza degli elementi e un elemento searchApplicationId
che identifica l'ID dell'applicazione di ricerca da utilizzare.
Il seguente snippet mostra una query all'origine dati del film Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Visualizza risultati della query
Le interfacce di ricerca dovrebbero mostrare almeno l'elemento title
e un link all'elemento originale. Puoi migliorare ulteriormente la visualizzazione dei risultati di ricerca sfruttando le informazioni aggiuntive presenti nei risultati di ricerca, come lo snippet e i metadati.
Gestire i risultati supplementari
Per impostazione predefinita, Cloud Search restituisce risultati supplementari quando sono disponibili risultati insufficienti per la query dell'utente. Il campo queryInterpretation
nella risposta indica quando vengono restituiti risultati supplementari. Se vengono restituiti solo risultati supplementari, InterpretationType
è impostato su REPLACE
. Se
vengono restituiti alcuni risultati per la query originale insieme a risultati
aggiuntivi, InterpretationType
è impostato su BLEND
. In entrambi i casi
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Quando vengono restituiti alcuni risultati supplementari, valuta la possibilità di fornire un testo
per indicare che sono stati restituiti risultati supplementari. Ad esempio, nel caso di REPLACE
, potresti visualizzare la stringa "La tua ricerca della query originale non ha prodotto alcun risultato. Sono visualizzati i risultati per query simili."
Nel caso di un valore BLEND
, potresti visualizzare la stringa "La ricerca della query originale non ha prodotto risultati sufficienti. Sono inclusi i risultati per
query simili".
Gestire i risultati delle persone
Cloud Search restituisce due tipi di "risultati di persone": documenti relativi a una persona il cui nome viene utilizzato nella query e informazioni sul dipendente di una persona il cui nome viene utilizzato in una query. Quest'ultimo tipo di risultato è una funzione della funzionalità People Search di Cloud Search e i risultati per tale query sono disponibili nel campo structuredResults
di una risposta dell'API Query:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Corrispondenza per i subordinati diretti
Corrispondenza report diretti è una funzionalità di ricerca di persone di Cloud Search che consente agli utenti di visualizzare i dipendenti subordinati di una persona all'interno della propria organizzazione.
Il risultato è disponibile all'interno del campo structuredResults
.
Per le query sul responsabile o sui dipendenti subordinati di una persona, la risposta ha un
assistCardProtoHolder
all'interno dell'elemento structuredResults
. assistCardProtoHolder
ha un campo chiamato cardType
che sarà uguale a RELATED_PEOPLE_ANSWER_CARD
. assistCardProtoHolder
contiene una scheda
chiamata relatedPeopleAnswerCard
che contiene la risposta effettiva.
Contiene subject
(la persona che è stata inclusa nella query) e relatedPeople
, che sono l'insieme di persone correlate all'oggetto. Il
campo relationType
restituisce il valore MANAGER
o DIRECT_REPORTS
.
Il codice seguente mostra una risposta di esempio per una query corrispondente ai report diretti:
{
"results": [],
"structuredResults": [{
"assistCardProtoHolder": {
"extensions": {
"@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
"cardMetadata": {
"cardCategory": "ANSWER"
},
"cardType": "RELATED_PEOPLE_ANSWER_CARD",
"relatedPeopleAnswerCard": {
"subject": {
"email": "AdamStanford@psincs-test01.newjnj.com",
"displayName": "Adam Stanford"
"manager": {
"email": "simonsais@psincs-test01.newjnj.com"
}
},
"relatedPeople": [{
"email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
"displayName": "Edgar Mountain Ramirez"
}, {
"email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
"displayName": "Francisco Jose Martinez"
}],
"relationType": "DIRECT_REPORTS",
}
}
}
}]
}
Disattiva le ottimizzazioni, inclusi risultati supplementari
Per impostazione predefinita, le ottimizzazioni, ad esempio i risultati supplementari, sono attivate. Tuttavia, puoi disattivare tutte le ottimizzazioni o solo i risultati supplementari sia a livello di applicazione di ricerca che di query:
Per disattivare tutte le ottimizzazioni a livello di applicazione di ricerca, inclusi risultati supplementari, sinonimi e correzioni ortografiche, imposta
QueryInterpretationConfig.force_verbatim_mode
sutrue
nelle applicazioni di ricerca.Per disattivare tutte le ottimizzazioni a livello di query di ricerca, tra cui risultati supplementari, sinonimi e correzioni ortografiche, imposta
QueryInterpretationOptions.enableVerbatimMode
sutrue
nella query di ricerca.Per disattivare i risultati supplementari a livello di applicazione di ricerca, imposta
QueryInterpretationOptions.forceDisableSupplementalResults
sutrue
nella query di ricerca.Per disattivare i risultati supplementari a livello di query di ricerca, imposta
QueryInterpretationOptions.disableSupplementalResults
sutrue
nella query di ricerca.
Evidenzia snippet
Per gli elementi restituiti contenenti testo indicizzato o contenuti HTML, viene restituito uno snippet dei contenuti. Questi contenuti aiutano gli utenti a determinare la pertinenza dell'articolo restituito.
Se nello snippet sono presenti termini di query, vengono restituiti anche uno o più intervalli di corrispondenza che identificano la loro posizione.
Utilizza matchRanges
per evidenziare il testo corrispondente durante il rendering
dei risultati. Il seguente esempio di JavaScript converte lo snippet in markup HTML con ogni intervallo corrispondente racchiuso in un tag <span>
.
function highlightSnippet(snippet) {
let text = snippet.snippet;
let formattedText = text;
if (snippet.matchRanges) {
let parts = [];
let index = 0;
for (let match of snippet.matchRanges) {
let start = match.start || 0; // Default to 0 if omitted
let end = match.end;
if (index < start) { // Include any leading text before/between ranges
parts.push(text.slice(index, start));
}
parts.push('<span class="highlight">');
parts.push(text.slice(start, end));
parts.push('</span>');
index = end;
}
parts.push(text.slice(index)); // Include any trailing text after last range
formattedText = parts.join('');
}
return formattedText;
}
Dato lo snippet:
{
"snippet": "This is an example snippet...",
"matchRanges": [
{
"start": 11,
"end": 18
}
]
}
La stringa HTML risultante è:
This is an <span class="highlight">example</span> snippet...
Visualizza metadati
Utilizza il campo metadata
per visualizzare informazioni aggiuntive sull'articolo restituito che potrebbero essere pertinenti per gli utenti. Il campo metadata
include createTime
e
updateTime
dell'articolo, nonché eventuali dati strutturati restituibili associati
all'articolo.
Per visualizzare i dati strutturati, utilizza il campo displayOptions
. Il campo displayOptions
contiene l'etichetta di visualizzazione per il tipo di oggetto e un insieme di metalines
. Ogni metalinea è un array di etichette di visualizzazione e coppie di valori configurati nello schema.
Recupera risultati aggiuntivi
Per recuperare risultati aggiuntivi, imposta il campo start
nella richiesta sull'offset desiderato. Puoi regolare le dimensioni di ogni pagina con il campo pageSize
.
Per visualizzare il numero di elementi restituiti o i controlli di paging per sfogliare gli elementi restituiti, utilizza il campo resultCount
. A seconda delle dimensioni del set di risultati, viene fornito il valore effettivo o un valore stimato.
Ordina risultati
Utilizza il campo sortOptions
per specificare l'ordine degli articoli restituiti. Il valore sortOptions
è un oggetto con due campi:
operatorName
: un operatore in base a cui ordinare la proprietà dei dati strutturati. Per le proprietà con più operatori, puoi ordinare solo utilizzando l'operatore di uguaglianza principale.sortOrder
: la direzione per l'ordinamento, ovveroASCENDING
oDESCENDING
.
La pertinenza viene utilizzata anche come chiave di ordinamento secondaria. Se in una query non è specificato alcun ordinamento, i risultati vengono classificati solo in base alla pertinenza.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Aggiungere i filtri
Oltre alle espressioni di query, puoi limitare ulteriormente i risultati applicando filtri. Puoi specificare i filtri sia nell'applicazione di ricerca che nella richiesta di ricerca.
Per aggiungere filtri in un'applicazione di richiesta o di ricerca, aggiungi il filtro nel campo dataSourceRestrictions.filterOptions[]
.
Esistono due modi principali per filtrare ulteriormente un'origine dati:
- I filtri degli oggetti, tramite la proprietà
filterOptions[].objectType
, limitano gli elementi corrispondenti al tipo specificato in uno schema personalizzato. - Filtri valore: limita gli elementi corrispondenti in base a un operatore di query e al valore fornito.
I filtri composti consentono di combinare più filtri di valori in espressioni logiche per query più complesse.
Nell'esempio dello schema per i film, puoi applicare un vincolo di età basato sull'utente corrente e limitare i film disponibili in base alla classificazione MPAA.
{
"query": "adventure",
"requestOptions": {
"searchApplicationId": "<search_app_id>"
},
"dataSourceRestrictions": [
{
"source": {
"name": "datasources/<data_source_id>"
},
"filterOptions": [
{
"objectType": "movie",
"filter": {
"compositeFilter": {
"logicOperator": "AND"
"subFilters": [
{
"compositeFilter": {
"logicOperator": "OR"
"subFilters": [
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "G"
}
}
},
{
"valueFilter": {
"operatorName": "rated",
"value": {
"stringValue": "PG"
}
}
}
]
}
]
}
}
}
]
}
]
}
Perfeziona i risultati con i facet
I facet sono proprietà indicizzate che rappresentano categorie per il perfezionamento dei risultati di ricerca. Utilizza i facet per aiutare gli utenti a perfezionare le query in modo interattivo e a trovare più velocemente elementi pertinenti.
I facet possono essere definiti nella tua applicazione di ricerca e sostituiti dalle impostazioni della query.
Quando richiedi i facet, Cloud Search calcola i valori più frequenti per le proprietà richieste tra gli elementi corrispondenti. Questi valori vengono restituiti nella risposta. Usa questi valori per creare filtri che restringono i risultati nelle query successive.
Il tipico modello di interazione con i facet è il seguente:
- Crea una query iniziale specificando le proprietà da includere nei risultati dei facet.
- Visualizza i risultati di ricerca e facet.
- L'utente seleziona uno o più valori dei facet per perfezionare i risultati.
- Ripeti la query con un filtro in base ai valori selezionati.
Ad esempio, per consentire il perfezionamento delle query sui film in base all'anno e alla classificazione MPAA, includi la proprietà facetOptions
nella query.
"facetOptions": [
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "year"
},
{
"sourceName": "datasources/<data_source_id>",
"operatorName": "rated"
}
]
Risultati facet con campi basati su numeri interi
Puoi anche richiedere risultati in facet con campi basati su numeri interi. Ad esempio, potresti contrassegnare una proprietà con numeri interi denominata book_pages
come suddivisione in facet per perfezionare i risultati di una ricerca relativa a libri con pagine "100-200".
Quando configuri lo schema del campo della proprietà con numeri interi, imposta isFacetable
su true
e aggiungi le opzioni di bucketing corrispondenti a integerPropertyOptions
.
In questo modo, per ogni proprietà intere-facetable sono definite opzioni di bucketing predefinite.
Quando definisci la logica delle opzioni di bucket, fornisci un array di valori incrementali che indicano intervalli. Ad esempio, se l'utente finale specifica intervalli come 2, 5, 10, 100
, vengono calcolati i facet per <2
, [2-5)
, [5-10)
, [10-100)
e >=100
.
Puoi eseguire l'override dei facet basati su numeri interi definendo le stesse opzioni di bucket per facetOptions
nella richiesta. Se necessario, Cloud Search utilizza le opzioni di bucketing definite nello schema quando né l'applicazione di ricerca né la richiesta di query hanno opzioni di facet definite. I facet definiti nella query hanno la precedenza sui facet definiti nell'applicazione di ricerca e i facet definiti nell'applicazione di ricerca hanno la precedenza sui facet definiti nello schema.
Risultati facet per data o dimensione del documento
Puoi utilizzare gli operatori prenotati per perfezionare i risultati di ricerca in base alle dimensioni del file del documento, misurate in byte o in base alla data di creazione o modifica di un documento. Non è necessario definire uno schema personalizzato,
ma devi specificare il valore operatorName
nell'elemento
FacetOptions
dell'applicazione di ricerca.
- Per il faceting in base alle dimensioni del documento, utilizza
itemsize
e definisci le opzioni di bucket. - Per il faceting in base alla data di creazione del documento, utilizza
createddatetimestamp
. - Per il faceting in base alla data di modifica del documento, utilizza
lastmodified
.
Interpretazione dei bucket facet
La proprietà facetResults
nella risposta alla query di ricerca include la richiesta di filtro esatta dell'utente
nel campo filter
per ogni
bucket
.
Per i facet non basati su numeri interi, facetResults
include una voce per
ogni proprietà richiesta. Per ogni proprietà viene fornito un elenco di valori o intervalli, chiamato
buckets
. I valori che si verificano più di frequente vengono visualizzati per primi.
Quando un utente seleziona uno o più valori in base ai quali applicare il filtro, crea una nuova query con i filtri selezionati ed esegui di nuovo la query sull'API.
Aggiungi suggerimenti
Utilizza l'API suggest per il completamento automatico per le query basate sulla cronologia delle query personali dell'utente, sui contatti e sul corpus dei documenti.
Ad esempio, la chiamata seguente fornisce suggerimenti per la frase parziale jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Puoi quindi visualizzare i suggerimenti risultanti in base alla tua applicazione.