Crea un'interfaccia di ricerca con l'API Query

L'API Query fornisce metodi di ricerca e suggerimenti per creare un'interfaccia di ricerca o incorporare i 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, consulta 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:

  1. Configura un'applicazione di ricerca
  2. Generare le credenziali OAuth per l'applicazione
  3. Eseguire una query sull'indice
  4. Visualizzare i risultati della query

Puoi migliorare ulteriormente l'interfaccia di ricerca con funzionalità come paging, 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 eseguire l'override di questi parametri utilizzando l'API 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 anche generare le credenziali OAuth per l'applicazione web. Il tipo di credenziali che crei dipende dal contesto in cui viene utilizzata l'API.

Utilizzare 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"}.

Eseguire una query sull'indice

Utilizza il metodo search per eseguire ricerche rispetto all'indice.

Ogni richiesta deve includere due informazioni: un testo query a cui abbinare gli elementi e una searchApplicationId che identifica l'ID che l'applicazione di ricerca può 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 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 snippet e metadati.

Gestire risultati supplementari

Per impostazione predefinita, Cloud Search restituisce risultati supplementari quando i risultati non sono sufficienti 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 della query originale insieme a risultati supplementari, 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 del 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 query originale non ha restituito alcun risultato. Risultati relativi a query simili."

Nel caso di un BLEND, potresti visualizzare la stringa "La ricerca della tua query originale non ha fornito 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 sui dipendenti 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 di una query di questo tipo sono disponibili nel campo 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 consente agli utenti di visualizzare i subordinati diretti di una persona nella loro organizzazione. Il risultato è disponibile nel campo structuredResults.

Per le query sul responsabile o sui dipendenti subordinati di una persona, la risposta ha un assistCardProtoHolder all'interno di structuredResults. assistCardProtoHolder ha un campo denominato cardType che sarà uguale a RELATED_PEOPLE_ANSWER_CARD. assistCardProtoHolder contiene una scheda denominata relatedPeopleAnswerCard che contiene la risposta effettiva. Contiene i subject (la persona 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 seguente codice mostra un esempio di risposta per una query di report diretti corrispondente:

{
  "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. Tuttavia, puoi disattivare tutte le ottimizzazioni o solo i risultati supplementari sia a livello di applicazione di ricerca che di query:

Snippet dei momenti salienti

Per gli elementi restituiti che includono 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 codice 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 il campo metadata per visualizzare ulteriori informazioni sull'articolo restituito che potrebbero essere pertinenti per gli utenti. Il campo metadata include i createTime e updateTime dell'articolo, nonché tutti i 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 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 per visualizzare i controlli di paging per mostrare gli elementi restituiti, utilizza il campo resultCount. A seconda delle dimensioni dell'insieme di risultati, viene fornito il valore effettivo o una stima.

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 al quale ordinare la proprietà dei dati strutturati. 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 in una query non viene 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 sia 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:

  • Filtri degli oggetti, tramite la proprietà filterOptions[].objectType, limita gli elementi corrispondenti al tipo specificato, come definito 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 del 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 facet

I facet sono proprietà indicizzate che rappresentano le categorie per perfezionare i risultati di ricerca. Utilizza 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 nell'applicazione di ricerca e sostituiti dalle impostazioni della query.

Quando si richiedono 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 restringano i risultati nelle query successive.

Il modello di interazione tipico con i facet è:

  1. Crea una query iniziale specificando quali proprietà includere nei risultati dei facet.
  2. Eseguire il rendering dei risultati della ricerca e dei facet.
  3. L'utente seleziona uno o più valori dei facet per perfezionare i risultati.
  4. Ripeti la query con un filtro basato sui valori selezionati.

Ad esempio, per consentire il perfezionamento delle query sui film in base all'anno e alla valutazione 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, potresti contrassegnare una proprietà di numeri interi denominata book_pages come facet per perfezionare i risultati di una ricerca di libri con pagine "100-200".

Quando configuri lo schema del campo della proprietà intero, imposta isFacetable su true e aggiungi le opzioni di bucket corrispondenti a integerPropertyOptions. Ciò garantisce che per ogni proprietà con facetable interi siano definite opzioni di bucket predefinite.

Quando definisci la logica delle opzioni di bucket, fornisci un array di valori incrementali che indichino intervalli. Ad esempio, se l'utente finale specifica gli intervalli come 2, 5, 10, 100, vengono calcolati i facet per <2, [2-5), [5-10), [10-100), >=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 le opzioni 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 dimensione o data 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 devi definire uno schema personalizzato, ma devi specificare il valore operatorName nel campo FacetOptions dell'applicazione di ricerca.

  • 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 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 che non sono 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. 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 esegui una nuova query sull'API.

Aggiungi suggerimenti

Utilizza l'API suggest per fornire il completamento automatico delle query basate sulla cronologia delle query personali dell'utente, sui contatti e sul corpus dei documenti.

Ad esempio, la seguente chiamata offre 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 alle tue esigenze.