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 di ricerca in un'applicazione.

Per le applicazioni web con requisiti minimi, ti consigliamo di utilizzare il widget di ricerca. Per ulteriori informazioni, 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. Configurare un'applicazione di ricerca
  2. Genera le credenziali OAuth per l'applicazione
  3. Esegui una query sull'indice
  4. Visualizzare i risultati della query

Puoi migliorare ulteriormente l'interfaccia di ricerca con funzionalità come la paginazione, l'ordinamento, i filtri, i facet e il suggerimento automatico.

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

Per ulteriori informazioni sulle applicazioni di ricerca, consulta Personalizzare l'esperienza di ricerca in Cloud Search.

Genera le credenziali OAuth per l'applicazione

Oltre ai passaggi descritti in Configurare l'accesso all'API Google Cloud Search, devi anche 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 OAuth e sulle librerie client, 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 in base al quale abbinare gli elementi e un searchApplicationId che identifica l'ID da usare per la applicazione di ricerca.

Lo snippet seguente mostra una query all'origine dati dei film per il film Titanic:

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

Visualizzare i risultati delle query

Come minimo, le interfacce di ricerca devono mostrare l'elemento title nonché 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 non sono disponibili risultati sufficienti per la query dell'utente. Il campo queryInterpretation nella risposta indica quando vengono restituiti risultati supplementari. Se vengono restituiti solo risultati supplementari, InterpretationType viene impostato su REPLACE. Se vengono restituiti alcuni risultati per la query originale insieme a risultati supplementari, InterpretationType viene 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 un messaggio REPLACE, potresti mostrare la stringa "La tua ricerca per la query originale non ha fornito risultati. Visualizzazione di risultati per query simili.

In caso di BLEND, potresti visualizzare la stringa "La ricerca per la query originale non ha prodotto risultati sufficienti. Sono inclusi i risultati per query simili".

Gestire i risultati di ricerca di persone

Cloud Search restituisce due tipi di "risultati relativi alle persone": documenti relativi a una persona il cui nome viene utilizzato nella query e informazioni sui dipendenti di una persona il cui nome viene utilizzato in una query. Quest'ultimo tipo di risultato è una funzione della funzionalità di ricerca di persone di Cloud Search e i risultati di una query di questo tipo sono disponibili nel campo structuredResults di una risposta dell'API di query:

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

Corrispondenza dei report diretti

La corrispondenza dei report diretti è una funzionalità di Cerca persone di Cloud Search che consente agli utenti di visualizzare i report diretti di una persona nella loro organizzazione. Il risultato è disponibile nel campo structuredResults.

Per le query relative al responsabile o ai dipendenti diretti di una persona, la risposta contiene un assistCardProtoHolder all'interno di structuredResults. assistCardProtoHolder ha un campo denominato cardType che sarà uguale a RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder contiene una scheda chiamata relatedPeopleAnswerCard che contiene la risposta effettiva. Contiene subject (la persona inclusa nella query) e relatedPeople, ovvero l'insieme di persone correlate all'argomento. Il campo relationType restituisce il valore MANAGER o DIRECT_REPORTS.

Il seguente codice mostra un esempio di risposta per una query di corrispondenza dei 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",
        }
      }
    }
  }]
}

Disattivare le ottimizzazioni, inclusi i risultati supplementari

Per impostazione predefinita, le ottimizzazioni, come i risultati supplementari, sono attivate. Tuttavia, puoi disattivare tutte le ottimizzazioni o solo i risultati supplementari sia a livello di applicazione di ricerca sia a livello di query:

Evidenzia gli 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 posizione dei termini.

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

Metadati visibili

Utilizza il campo metadata per visualizzare informazioni aggiuntive sull'elemento restituito che potrebbero essere pertinenti per gli utenti. Il campo metadata include createTime e updateTime dell'elemento, nonché eventuali dati strutturati restituibili associati all'elemento.

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 come configurato nello schema.

Recuperare risultati aggiuntivi

Per recuperare ulteriori risultati, 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 paginazione per scorrirli, 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 per la proprietà dei dati strutturati in base alla quale eseguire l'ordinamento. Per le proprietà con più operatori, puoi ordinare solo utilizzando l'operatore di uguaglianza principale.
  • sortOrder: la direzione di ordinamento, ASCENDING o DESCENDING.

La pertinenza viene utilizzata anche come chiave di ordinamento secondaria. Se non viene specificato alcun ordinamento in una query, i risultati vengono 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 nell'applicazione di ricerca sia nella richiesta di ricerca.

Per aggiungere filtri in una richiesta o in un'applicazione 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 come definito in uno schema personalizzato.
  • Filtri dei valori: limita gli elementi corrispondenti in base a un operatore di query e al valore fornito.

I filtri composti consentono di combinare più filtri di valore in espressioni logiche per query più complesse.

Nell'esempio dello schema dei film, puoi applicare una limitazione di età in base all'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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Perfezionare i risultati con i facet

I facet sono proprietà indicizzate che rappresentano categorie per perfezionare i risultati di ricerca. Utilizza le sfaccettature per aiutare gli utenti a perfezionare in modo interattivo le loro query e trovare più rapidamente gli elementi pertinenti.

I componenti possono essere definiti nella applicazione di ricerca. e sostituiti dalle impostazioni nella 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. Utilizza questi valori per creare filtri che restringono i risultati nelle query successive.

Il pattern di interazione tipico con le sfaccettature è:

  1. Esegui una query iniziale specificando le proprietà da includere nei risultati della riga.
  2. Esegui il rendering dei risultati di ricerca e dei facet.
  3. L'utente seleziona uno o più valori del facet per perfezionare i risultati.
  4. Ripeti la query con un filtro in base ai valori selezionati.

Ad esempio, per affinare le query sui film in base all'anno e alla classificazione MPAA, includere 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 eseguire la suddivisione in parti dei risultati della richiesta con campi basati su numeri interi. Ad esempio, potresti contrassegnare una proprietà di tipo intero denominata book_pages come aggregabile per perfezionare i risultati di una ricerca sui libri con "100-200" pagine.

Quando configuri lo schema del campo della proprietà intero, imposta isFacetable su true e aggiungi le opzioni di raggruppamento corrispondenti a integerPropertyOptions. In questo modo, per ogni proprietà con una tabella di facce di tipo intero sono definite le opzioni di bucketing predefinite.

Quando definisci la logica delle opzioni di raggruppamento, fornisci un array di valori incrementali che indicano gli intervalli. Ad esempio, se l'utente finale specifica intervalli come 2, 5, 10, 100, vengono calcolati i fattori per <2, [2-5), [5-10), [10-100), >=100.

Puoi ignorare le sfaccettature basate su numeri interi definendo le stesse opzioni di raggruppamento per facetOptions nella richiesta. Se necessario, Cloud Search utilizza le opzioni di raggruppamento definite nello schema quando né l'applicazione di ricerca né la richiesta di query hanno opzioni di espressione delle sfaccettate definite. I facet definiti nella query hanno la precedenza su quelli definiti nell'applicazione di ricerca, che a loro volta hanno la precedenza su quelli definiti nello schema.

Suddividere i risultati in base alle dimensioni o alla data del documento

Puoi utilizzare operatori riservati 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 in FacetOptions dell'applicazione di ricerca.

  • Per eseguire la suddivisione in base alle dimensioni del documento, utilizza itemsize e definisci le opzioni di raggruppamento.
  • Per le sfaccettature in base alla data di creazione del documento, utilizza createddatetimestamp.
  • Per eseguire la suddivisione in base alla data di modifica del documento, utilizza lastmodified.

Interpretazione dei bucket di 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 più frequenti 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 una query sull'API.

Aggiungere suggerimenti

Utilizza l'API suggest per fornire il completamento automatico delle query in base alla cronologia delle query personali dell'utente, nonché ai contatti e al corpus di 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"
  }
}

Potrai quindi visualizzare i suggerimenti risultanti in base alle esigenze della tua applicazione.