Crea un'interfaccia di ricerca con l'API Query

L'API Query fornisce metodi di ricerca e suggerimento per creare un'interfaccia di ricerca o incorporare i risultati in un'applicazione.

Per le applicazioni web con requisiti minimi, valuta la possibilità di utilizzare il widget di ricerca. Vedi Creare un'interfaccia di ricerca con il widget di ricerca.

Crea un'interfaccia di ricerca

La creazione di un'interfaccia di ricerca minimale richiede diversi passaggi:

1. Configurare un'applicazione di ricerca.
2. Genera le credenziali OAuth per l'applicazione.
3. Esegui query sull'indice.
4. Visualizza i risultati della query.

Puoi migliorare l'interfaccia con funzionalità come paginazione, ordinamento, filtro, sfaccettature e completamento automatico.

Configurare un'applicazione di ricerca

Devi creare almeno un'applicazione di ricerca per ogni interfaccia di ricerca. Un'applicazione di ricerca fornisce parametri predefiniti, come origini dati, ordinamento, filtri e facet. Puoi eseguire l'override di questi parametri utilizzando l'API Query.

Non puoi aumentare il numero di origini dati utilizzate in una query oltre a quelle configurate nell'applicazione di ricerca. Puoi limitare una query a un sottoinsieme di queste origini utilizzando dataSourceRestrictions.

Nota: Cloud Search aggiorna le applicazioni di ricerca quando aggiorni o elimini uno schema. Ad esempio, se rinomini un operatore dello schema, questo viene rinominato anche nell'applicazione di ricerca. Se un aggiornamento non è compatibile, l'aggiornamento dello schema non va a buon fine.

Per saperne di più, consulta Personalizzare l'esperienza di ricerca.

Genera le credenziali OAuth per l'applicazione

Oltre ai passaggi descritti in Configurare l'accesso all'API Cloud Search, devi generare le credenziali OAuth per la tua applicazione web.

Utilizza le credenziali per richiedere l'autorizzazione per conto dell'utente. Utilizza l'ambito https://www.googleapis.com/auth/cloud_search.query.

Per saperne di più sulle opzioni OAuth, consulta Google Identity Platform.

Eseguire query sull'indice

Utilizza il metodo search per cercare nell'indice.

Ogni richiesta deve includere un testo query e un searchApplicationId.

Questo esempio esegue una query su un'origine dati di film:

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  }
}

Visualizzare i risultati delle query

Le interfacce di ricerca devono mostrare l'elemento title e un link all'elemento originale. Puoi anche utilizzare snippet e metadati per migliorare la visualizzazione.

Nota: se non vedi risultati, assicurati di aver creato un'applicazione di ricerca personalizzata e di aver attivato l'origine dati.

Gestire i risultati supplementari

Cloud Search restituisce risultati supplementari quando non ci sono corrispondenze sufficienti per una query. Il campo queryInterpretation lo indica. Se vengono restituiti solo risultati supplementari, InterpretationType è REPLACE. Se sono misti, è BLEND.

Quando restituisci risultati supplementari, valuta la possibilità di informare l'utente. Per un REPLACE, potresti dire: "La tua ricerca non ha prodotto risultati. Sono visualizzati risultati per query simili."

Gestire i risultati di ricerca di persone

Cloud Search restituisce documenti relativi a persone e informazioni sui dipendenti utilizzando la funzionalità Ricerca persone. I risultati sono nel campo structuredResults:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

Nota: se definisci più di 20 attributi personalizzati, People Search ne utilizza solo 20.

Corrispondenza dei subordinati diretti

La corrispondenza dei dipendenti subordinati consente agli utenti di visualizzare i dipendenti subordinati di una persona. La risposta include un assistCardProtoHolder con un cardType di RELATED_PEOPLE_ANSWER_CARD.

Disattivare le ottimizzazioni

Ottimizzazioni come i risultati supplementari sono attive per impostazione predefinita. Puoi disattivarli:

• Livello dell'applicazione di ricerca: imposta force_verbatim_mode su true.
• A livello di query: imposta enableVerbatimMode su true.

Snippet in evidenza

Cloud Search restituisce uno snippet per il testo o l'HTML indicizzato. Se sono presenti termini di query, matchRanges ne identifica la posizione. Utilizza questi intervalli per evidenziare il testo.

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 il campo metadata per informazioni come createTime, updateTime e dati strutturati. Utilizza displayOptions per mostrare i dati strutturati.

Recuperare risultati aggiuntivi

Per recuperare più risultati, imposta il campo start sull'offset selezionato. Regola le dimensioni della pagina con pageSize. Utilizza resultCount per visualizzare il totale degli elementi o i conteggi stimati.

Ordina risultati

Utilizza sortOptions per specificare l'ordine:

• operatorName: la proprietà in base alla quale eseguire l'ordinamento.
• sortOrder: ASCENDING o DESCENDING.

Pertinenza è la chiave di ordinamento predefinita e secondaria.

Aggiungi filtri

Limita i risultati con i filtri nell'applicazione o nella richiesta di ricerca. Se entrambi specificano filtri per una sorgente, entrambi devono essere valutati come veri.

Applica filtri in dataSourceRestrictions.filterOptions[]. Tipi di filtri principali:

• Filtri per oggetto: limita le corrispondenze a un tipo specifico.
• Filtri dei valori: limitano le corrispondenze in base a un operatore e a un valore.

I filtri compositi combinano più filtri di valori.

Perfeziona i risultati con i facet

I facet aiutano gli utenti a perfezionare interattivamente le query. Quando richiedi i prospetti, Cloud Search calcola i valori più frequenti per queste proprietà.

Pattern tipico: 1. Query che specifica le proprietà delle sfaccettature. 1. Visualizza i risultati di ricerca e dei facet. 1. L'utente seleziona i valori dei facet. 1. Ripeti la query con un filtro basato sulle selezioni.

Nota: solo le proprietà dei dati strutturati supportano i facet.

Risultati dei facet con campi basati su numeri interi

Contrassegna una proprietà intera come sfaccettabile per perfezionare i risultati in base agli intervalli (ad es. "100-200" pagine). Imposta isFacetable su true e definisci le opzioni di raggruppamento predefinite nello schema.

Visualizzare i risultati per dimensione o data del documento

Utilizza operatori riservati:

• itemsize: per le dimensioni del file in byte.
• createddatetimestamp: per la data di creazione.
• lastmodified: per la data di modifica.

Aggiungere suggerimenti

Utilizza l'API suggest per il completamento automatico in base alla cronologia delle query, ai contatti e ai contenuti dei documenti.