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. Consulta Creare un'interfaccia di ricerca con il widget di ricerca.

Creare un'interfaccia di ricerca

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

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

Puoi migliorare l'interfaccia con funzionalità come paginazione, ordinamento, filtri, facet 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 sostituire 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.

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

Generare 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 una query sull'indice

Utilizza il search metodo per eseguire una ricerca nell'indice.

Ogni richiesta deve includere un query di testo 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 della query

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

Gestire i risultati supplementari

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

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

Gestire i risultati delle persone

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

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

Corrispondenza dei subordinati diretti

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

Disattivare le ottimizzazioni

Le ottimizzazioni come i risultati supplementari sono attivate per impostazione predefinita. Puoi disattivarle:

Evidenziare gli snippet

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

Visualizzare i metadati

Utilizza il metadata campo per informazioni come createTime, updateTime e dati strutturati. Utilizza displayOptions per mostrare i dati strutturati.

Recuperare risultati aggiuntivi

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

Ordinare i risultati

Utilizza sortOptions per specificare l'ordine:

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

La pertinenza è la chiave di ordinamento predefinita e secondaria.

Aggiungere filtri

Limita i risultati con filtri nell'applicazione di ricerca o nella richiesta. Se entrambi specificano i filtri per un'origine, entrambi devono restituire il valore true.

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

  • Filtri di oggetti: limitano le corrispondenze a un tipo specifico.
  • Filtri di valori: limitano le corrispondenze in base a un operatore e a un valore.

I filtri composti combinano più filtri di valori.

Perfezionare i risultati con i facet

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

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

Risultati dei facet con campi basati su numeri interi

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

Risultati dei facet in base alle dimensioni o alla data del documento

Utilizza gli 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.