L'API Query fornisce metodi di ricerca e suggerimento per creare una ricerca a riga di comando o di incorporare risultati di ricerca in un'applicazione.
Per le applicazioni web con requisiti minimi, prendi in considerazione l'utilizzo del widget di ricerca. Per ulteriori informazioni, vedi Creare un'interfaccia di ricerca con il widget di 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
- Eseguire 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 l'interfaccia di ricerca che crei. Un'applicazione di ricerca fornisce l'impostazione predefinita i parametri per una query, quali le origini dati da utilizzare, l'ordinamento filtri e facet da richiedere. Se necessario, puoi sostituire questi parametri utilizzando l'API Query.
Per ulteriori informazioni sulle applicazioni di ricerca, consulta Personalizza l'esperienza di ricerca in Cloud Search.
Generare le credenziali OAuth per l'applicazione
Oltre alla procedura per Configura l'accesso all'API Google Cloud Search. devi anche generare le credenziali OAuth per l'applicazione web. Il tipo le credenziali che crei dipendono dal contesto in cui viene utilizzata l'API.
Utilizzare le credenziali per richiedere l'autorizzazione per conto dell'utente. Utilizza la
l'ambito https://www.googleapis.com/auth/cloud_search.query
durante la richiesta
autorizzazione.
Per ulteriori informazioni sulle opzioni OAuth e sulle librerie client, consulta [Piattaforma Google Identity](https://developers.google.com/identity/choose-auth{: .external target="_blank"}.
Eseguire una query sull'indice
Utilizza la search
per eseguire ricerche rispetto all'indice.
Ogni richiesta deve includere due informazioni: un testo query
per trovare una corrispondenza tra gli elementi e un searchApplicationId
che identifica l'ID per
l'applicazione di ricerca da utilizzare.
Lo snippet seguente mostra una query sull'origine dati del film Titanic:
{
"query": "titanic",
"requestOptions": {
"searchApplicationId": "searchapplications/<search_app_id>"
},
}
Visualizza i risultati della query
Le interfacce di ricerca dovrebbero visualizzare almeno l'elemento title
come
e un link all'elemento originale. Puoi migliorare ulteriormente la visualizzazione
i risultati di ricerca sfruttando le informazioni aggiuntive presenti nei risultati
come snippet e metadati.
Gestire risultati supplementari
Per impostazione predefinita, Cloud Search restituisce risultati supplementari se sono presenti
risultati insufficienti per la query dell'utente. La
queryInterpretation
nella risposta indica quando vengono restituiti risultati supplementari. Se solo
vengono restituiti risultati supplementari. Il valore InterpretationType
è impostato su REPLACE
. Se
vengono restituiti alcuni risultati per la query originale
risultati, InterpretationType
è impostato su BLEND
. In entrambi i casi
QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY
.
Quando vengono restituiti alcuni risultati supplementari, ti consigliamo di fornire testo
per indicare che sono stati restituiti risultati supplementari. Ad esempio, nel caso di un
REPLACE
, potresti visualizzare la stringa "La tua ricerca per la tua query originale ha restituito
non corrisponde ad alcun risultato. Risultati relativi a query simili."
Nel caso di un valore BLEND
, potresti visualizzare la stringa "La tua ricerca
la query originale non ha fornito risultati sufficienti. Sono inclusi i risultati per simili
".
Gestire i risultati delle persone
Cloud Search restituisce due tipi di "risultati di persone": documenti relativi a un
persona il cui nome viene utilizzato nella query e informazioni sul dipendente di una persona
il cui nome viene utilizzato in una query. L'ultimo tipo di risultato è una funzione di Cloud
La funzionalità People Search della Ricerca e i risultati di questa query sono disponibili in
il
structuredResults
di una risposta dell'API Query:
{
"results": [...],
"structuredResults": [{
"person": {...}
}]
}
Corrispondenza dei rapporti diretti
La corrispondenza dei report diretti è una funzionalità di People Search di Cloud Search che ti consente
gli utenti vedono i dipendenti subordinati di una persona all'interno dell'organizzazione.
Il risultato è disponibile nel campo structuredResults
.
Per query sul responsabile o sui dipendenti subordinati di una persona, la risposta contiene
assistCardProtoHolder
in structuredResults
. La
assistCardProtoHolder
ha un campo denominato cardType
che sarà uguale a
RELATED_PEOPLE_ANSWER_CARD
. Il assistCardProtoHolder
contiene una scheda
chiamato relatedPeopleAnswerCard
, che contiene la risposta effettiva.
Contiene subject
(la persona inclusa nella query) e
relatedPeople
, ovvero l'insieme di persone correlate all'argomento. La
Il campo relationType
restituisce il valore MANAGER
o DIRECT_REPORTS
.
Il codice seguente mostra una risposta di esempio per una corrispondenza dei report diretti query:
{
"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 i risultati supplementari.
Le ottimizzazioni, ad esempio i risultati supplementari, sono attive per impostazione predefinita. Puoi: ma disattiva tutte le ottimizzazioni o solo i risultati supplementari a applicazione di ricerca e livello di query:
Per disattivare tutte le ottimizzazioni a livello di applicazione di ricerca, tra cui: tra cui risultati supplementari, sinonimi, e correzioni ortografiche,
QueryInterpretationConfig.force_verbatim_mode
atrue
nelle applicazioni di ricerca.Per disattivare tutte le ottimizzazioni a livello di query di ricerca, tra cui: risultati supplementari, sinonimi e correzioni ortografiche,
QueryInterpretationOptions.enableVerbatimMode
atrue
nella query di ricerca.Per disattivare i risultati supplementari a livello di applicazione di ricerca, imposta
QueryInterpretationOptions.forceDisableSupplementalResults
atrue
nella query di ricerca.Per disattivare i risultati supplementari a livello di query di ricerca, imposta
QueryInterpretationOptions.disableSupplementalResults
atrue
nella query di ricerca.
Snippet dei momenti salienti
Per gli elementi restituiti che includono testo indicizzato o contenuti HTML, uno snippet dei contenuti. Questi contenuti aiutano gli utenti a determinare pertinenza dell'articolo restituito.
Se nello snippet sono presenti termini di query, uno o più intervalli di corrispondenza che identificano viene restituita anche la posizione dei termini.
Utilizza matchRanges
per evidenziare il testo corrispondente durante il rendering
i risultati. Il seguente esempio JavaScript converte lo snippet in
Markup HTML con ogni intervallo corrispondente inserito 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...
Metadati visibili
Utilizza la metadata
per visualizzare informazioni aggiuntive sull'articolo restituito che potrebbero essere pertinenti
agli utenti. Il campo metadata
include createTime
e
updateTime
dell'articolo e di eventuali dati strutturati restituibili associati
con l'elemento.
Per visualizzare i dati strutturati, utilizza la displayOptions
. Il campo displayOptions
contiene l'etichetta di visualizzazione per il tipo di oggetto
e un set di metalines
. Ogni metalinea è un array di etichette di visualizzazione
coppie di valori configurate nello schema.
Recuperare risultati aggiuntivi
Per recuperare ulteriori risultati, imposta start
della richiesta all'offset desiderato. Puoi regolare le dimensioni
di ogni pagina con pageSize
.
Per visualizzare il numero di elementi restituiti o per visualizzare i controlli di paging per
pagina tra gli articoli restituiti, utilizza
resultCount
. A seconda della dimensione dell'insieme di risultati, il valore effettivo o
viene fornito un valore stimato.
Ordina risultati
Utilizza la sortOptions
per specificare l'ordine degli articoli restituiti. Il valore sortOptions
è un oggetto con due campi:
operatorName
: un operatore in base al quale ordinare la proprietà dei dati strutturati. Per le proprietà con più operatori, puoi ordinare solo utilizzando l'uguaglianza principale operatore.sortOrder
: la direzione di ordinamento,ASCENDING
oDESCENDING
.
La pertinenza viene utilizzata anche come chiave di ordinamento secondaria. Se non viene specificato alcun ordinamento in una query, i risultati sono classificati solo in base alla pertinenza.
"sortOptions": {
"operatorName": "priority",
"sortOrder": "DESCENDING"
}
Aggiungi filtri
Oltre alle espressioni di query, puoi limitare ulteriormente i risultati applicando filtri. Puoi specificare i filtri sia nel applicazione di ricerca così come nella richiesta di ricerca.
Per aggiungere filtri in una richiesta o in un'applicazione di ricerca, aggiungi il filtro nella
dataSourceRestrictions.filterOptions[]
.
Esistono due modi principali per filtrare ulteriormente un'origine dati:
- Filtri degli oggetti, tramite la proprietà
filterOptions[].objectType
: limitazioni che corrispondono al tipo specificato, come definito in uno schema personalizzato. - Filtri valore — limita gli elementi corrispondenti in base a una operatore di query e il valore fornito.
Filtri compositi consentono di combinare più filtri di valori in espressioni logiche per ottenere per query complesse.
Nell'esempio dello schema del film, potresti applicare un vincolo di età in base l'utente corrente e limita 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 facet
I facet sono proprietà indicizzate che rappresentano le categorie per perfezionare la ricerca che consentono di analizzare i dati e visualizzare i risultati. Usa i facet per aiutare gli utenti a perfezionare in modo interattivo le query e trovare più velocemente gli elementi pertinenti.
I facet possono essere definiti dell'applicazione di ricerca. e sovrascritto dalle impostazioni della query.
Quando vengono richiesti i facet, Cloud Search calcola i valori più frequenti per le proprietà richieste tra gli elementi corrispondenti. Questi vengono restituiti nella risposta. Utilizza questi valori per creare filtri che restringono i risultati nelle query successive.
Il modello di interazione tipico con i facet è:
- Crea una query iniziale specificando quali proprietà includere nel facet che consentono di analizzare i dati e visualizzare i risultati.
- Eseguire il rendering dei risultati della ricerca e dei facet.
- L'utente seleziona uno o più valori dei facet per perfezionare i risultati.
- Ripeti la query con un filtro basato sui valori selezionati.
Ad esempio, per consentire il perfezionamento delle query relative ai 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 dei facet con campi basati su numeri interi
Puoi anche fare richieste di risultati con campi basati su numeri interi. Ad esempio,
potrebbe contrassegnare una proprietà intero chiamata book_pages
come suddivisione in facet da perfezionare
risultati per una ricerca di libri con "100-200" pagine.
Quando configuri lo schema del campo della proprietà intero, imposta
isFacetable
a true
e aggiungere le opzioni di bucket corrispondenti
integerPropertyOptions
.
Questo garantisce che ogni proprietà con facetable interi abbia il bucketing predefinito
opzioni definite.
Quando definisci la logica delle opzioni di bucketing, fornisci un array di valori incrementali
che rappresentano intervalli significativi. Ad esempio, se l'utente finale specifica gli intervalli come
2, 5, 10, 100
, poi facet per <2
, [2-5)
, [5-10)
, [10-100)
, >=100
vengono calcolate.
Puoi eseguire l'override dei facet basati su numeri interi definendo le stesse opzioni di bucket
facetOptions
nella richiesta. Se necessario, Cloud Search utilizza le opzioni di bucketing definite
lo schema quando né l'applicazione di ricerca né la richiesta di query hanno facet
opzioni definite. I facet definiti nella query hanno la precedenza sui facet definiti
nell'applicazione di ricerca, mentre i facet definiti nell'applicazione di ricerca assumono
la precedenza sui facet definiti nello schema.
Risultati facet per dimensione o data del documento
Puoi utilizzare la modalità
operatori prenotati
per perfezionare i risultati di ricerca in base alle dimensioni del file del documento, misurate in byte o quando
un documento è stato creato o modificato. Non è necessario definire uno schema personalizzato
ma devi specificare il valore operatorName
nel campo
FacetOptions
- Per il faceting in base alle dimensioni del documento, utilizza
itemsize
e definisci le opzioni di bucketing. - Per il faceting in base alla data di creazione del documento, utilizza
createddatetimestamp
. - Per il faceting per data di modifica del documento, utilizza
lastmodified
.
Interpretazione dei bucket di facet
La facetResults
nella risposta alla query di ricerca include la richiesta di filtro esatto dell'utente.
nel campo filter
per ogni
bucket
.
Per i facet che non sono basati su numeri interi, facetResults
include una voce per
ciascuna proprietà richiesta. Per ogni proprietà, un elenco di valori o intervalli,
buckets
è fornito. Vengono visualizzati per primi i valori più frequenti.
Quando un utente seleziona uno o più valori in base ai quali applicare il filtro, crea una nuova query con i filtri selezionati ed eseguire nuovamente query sull'API.
Aggiungi suggerimenti
Utilizzare l'API suggest per fornire il completamento automatico per le query basate sui la cronologia delle query, nonché i contatti e il corpus dei documenti.
Ad esempio, la seguente chiamata fornisce suggerimenti per la parte jo.
{
"query": "jo",
"requestOptions": {
"searchApplicationId": "<search_app_id>",
"peoplePhotoOptions": {
"peoplePhotoUrlSizeInPx": 32
},
"timeZone": "America/Denver"
}
}
Puoi quindi visualizzare i suggerimenti risultanti in base alle tue esigenze un'applicazione.