Eine Suchoberfläche mit der Query API erstellen

Die Query API bietet Ihnen Zugriff auf Methoden für Suchanfragen und Vorschläge, mit denen Sie eine Suchoberfläche erstellen oder mit denen Suchergebnisse in eine Anwendung eingebettet werden können.

Für Webanwendungen mit minimalen Anforderungen können Sie das Such-Widget verwenden. Weitere Informationen zum Erstellen einer Suchoberfläche mit dem Such-Widget

Suchoberfläche erstellen

So erstellen Sie eine einfache Suchoberfläche:

  1. Suchanwendung konfigurieren
  2. OAuth-Anmeldedaten für die Anwendung generieren
  3. Index abfragen
  4. Abfrageergebnisse anzeigen lassen

Sie können die Suchoberfläche mit Funktionen wie Paginieren, Sortieren, Filtern, Facetten und automatischen Vorschlägen weiter optimieren.

Suchanwendung konfigurieren

Sie müssen mindestens eine Suchanwendung erstellen, die mit jeder Suchoberfläche verknüpft werden muss, die Sie erstellen. Eine Suchanwendung stellt die Standardparameter für eine Abfrage bereit, z. B. die Datenquellen, die berücksichtigt werden sollen, die Sortierreihenfolge, die Filter und die abzufragenden Facetten. Bei Bedarf können Sie diese Parameter mithilfe der Query API überschreiben.

Weitere Informationen finden Sie im Hilfeartikel Benutzerdefinierte Suche erstellen.

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten in der Anleitung zum Konfigurieren des Zugriffs auf die Google Cloud Search REST API müssen Sie auch die OAuth-Anmeldedaten für die Webanwendung generieren. Der Typ der Anmeldedaten hängt vom Kontext ab, in dem die API verwendet wird.

Fordern Sie mithilfe der Anmeldedaten im Namen der Nutzer die Autorisierung an. Verwenden Sie dabei den Bereich https://www.googleapis.com/auth/cloud_search.query.

Weitere Informationen zu den OAuth-Optionen und Clientbibliotheken finden Sie auf der Google Identity Platform.

Index abfragen

Führen Sie beim Autorisieren mithilfe der search-Methode Suchanfragen im Index durch.

Jede Anfrage muss zwei Informationen enthalten: eine Textabfrage (text query), mit der Elemente abgeglichen werden, und einen Wert für searchApplicationId, also die ID der zu verwendenden Suchanwendung.

Im folgenden Snippet wird eine Abfrage der Filmdatenquelle für den Film "Titanic" gezeigt:

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

Abfrageergebnisse anzeigen

Es wird erwartet, dass in Suchoberflächen mindestens der Titel (title) eines Elements sowie ein Link zum ursprünglichen Element angezeigt wird. Sie können die Anzeige von Suchergebnissen optimieren, indem Sie zusätzliche Informationen in diesen Ergebnissen nutzen, z. B. Snippets und Metadaten.

Snippets markieren

Bei Elementen mit indexiertem Text oder HTML-Code wird ein Snippet des Inhalts zurückgegeben. Dies hilft Nutzern, die Relevanz des zurückgegebenen Elements zu bestimmen.

Wenn im Snippet Abfragebegriffe vorhanden sind, wird auch mindestens ein Bereich mit den Stellen zurückgegeben, an denen sich die übereinstimmenden Begriffe befinden.

Mit matchRanges lässt sich übereinstimmender Text beim Rendern der Ergebnisse hervorheben. Im folgenden JavaScript-Beispiel wird das Snippet in HTML-Markup konvertiert, wobei jeder übereinstimmende Bereich in ein <span>-Tag eingeschlossen wird.

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;
}

Bei folgendem Snippet…

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

…lautet der resultierende HTML-String:

This is an <span class="highlight">example</span> snippet...

Metadaten anzeigen

Mit dem metadata-Feld können Sie sich zusätzliche Informationen zum zurückgegebenen Element anzeigen lassen, die für Nutzer relevant sein können. metadata enthält die Werte für createTime und updateTime des Elements sowie alle mit dem Element verknüpften strukturierten Daten.

Das Feld displayOptions dient zur Anzeige strukturierter Daten. Das Feld displayOptions enthält die Anzeigelabel des Objekttyps und eine Reihe von Metazeilen (metalines). Jede Metazeile ist der Schemakonfiguration entsprechend ein Array von Anzeigelabels und Wertepaaren.

Zusätzliche Ergebnisse abrufen

Sie können weitere Ergebnisse abrufen, indem Sie das Feld start in der Anfrage auf den gewünschten Offset-Wert festlegen. Außerdem haben Sie die Möglichkeit, die Größe jeder Seite mit dem Feld pageSize anzupassen.

Mithilfe des Felds resultCount können Sie die Anzahl der zurückgegebenen Elemente oder die Seitensteuerelemente aufrufen, mit denen sich in zurückgegebenen Elementen blättern lässt. Je nach Größe der Ergebnismenge wird entweder der tatsächliche Wert oder ein geschätzter Wert angegeben.

Ergebnisse sortieren

Das Feld sortOptions dient dazu, die Reihenfolge der zurückgegebenen Elemente anzugeben. Der Wert sortOptions ist ein Objekt mit zwei Feldern:

  • operatorName: ein Operator für das Attribut der strukturierten Daten, nach dem sortiert werden soll. Bei Attributen mit mehreren Operatoren können Sie nur mit dem wichtigsten Gleichheitsoperator sortieren.
  • sortOrder: die Sortierreihenfolge, entweder "aufsteigend" (ASCENDING) oder "absteigend" (DESCENDING).

Die Relevanz wird als sekundärer Sortierschlüssel verwendet. Wenn in einer Abfrage keine Sortierreihenfolge angegeben ist, werden die Ergebnisse nur nach Relevanz sortiert.

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

Filter hinzufügen

Zusätzlich zu Abfrageausdrücken lassen sich Suchergebnisse auch mithilfe von Filtern weiter einschränken. Sie können diese sowohl in der Suchanwendung als auch in der Suchanfrage angeben.

Wenn Sie einer Anfrage oder Suchanwendung Filter hinzufügen möchten, fügen Sie sie in das Feld dataSourceRestrictions.filterOptions[] ein.

Es gibt zwei Möglichkeiten, eine Datenquelle weiter zu filtern:

  • Objektfilter, über das Attribut filterOptions[].objectType: So werden übereinstimmende Elemente auf den angegebenen Typ beschränkt. Dies wird in einem benutzerdefinierten Schema definiert.
  • Wertefilter: Hiermit werden übereinstimmende Elemente auf Grundlage eines Abfrageoperators und des bereitgestellten Werts eingeschränkt.

Zusammengesetzte Filter ermöglichen es, mehrere Wertfilter zu logischen Ausdrücken zu kombinieren. Auf diese Art können komplexere Abfragen gestellt werden.

Im Beispiel mit dem Filmschema haben Sie z. B. die Möglichkeit, je nach aktuellem Nutzer eine Altersbeschränkung anzuwenden und die verfügbaren Filme auf Grundlage der MPAA-Bewertung einzuschränken. Diese ist mit der deutschen FSK-Bewertung vergleichbar.

{
  "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"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Ergebnisse mithilfe von Facetten verfeinern

Facetten sind indexierte Attribute, also Kategorien. Mithilfe von Facetten können Nutzer Abfragen interaktiv verfeinern und relevante Elemente schneller finden.

Facetten können in der Suchanwendung definiert und durch Einstellungen in der Abfrage überschrieben werden.

Beim Anfordern von Facetten werden in Cloud Search diejenigen Werte der angefragten Attribute ermittelt, die in den übereinstimmenden Elementen vorkommen. In der Antwort werden diese Werte zurückgegeben. Mit ihnen können Sie Filter erstellen, die bei nachfolgenden Abfragen die Ergebnisse eingrenzen.

Die Interaktion mit Facetten verläuft üblicherweise so:

  1. Sie erstellen eine erste Abfrage, in der Sie angeben, welche Attribute in den Facetten-Ergebnissen berücksichtigt werden sollen.
  2. Sie rendern die Such- und Facetten-Ergebnisse.
  3. Der Nutzer wählt mindestens einen Facettenwert aus, um die Ergebnisse zu verfeinern.
  4. Sie wiederholen die Abfrage mit einem Filter, der auf den ausgewählten Werten basiert.

Wenn Sie beispielsweise Filmabfragen nach Jahr und MPAA-Bewertung verfeinern möchten, sollte die Abfrage das Attribut facetOptions berücksichtigen.

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

Facetten-Buckets interpretieren

Das Attribut facetResults in der Antwort enthält für jedes angefragte Attribut einen Eintrag. Für jedes Attribut ist eine Liste von Werten oder Bereichen angegeben, sogenannte buckets. Die am häufigsten vorkommenden Werte sind zuerst angegeben.

Wenn ein Nutzer mindestens einen Wert auswählt, nach dem gefiltert werden soll, erstellen Sie eine neue Abfrage mit den ausgewählten Filtern und fragen Sie die API noch einmal ab.

Vorschläge hinzufügen

Mit der Suggest API können Sie eine automatische Vervollständigung von Abfragen implementieren. Die Vorschläge werden auf Grundlage des persönlichen Abfrageverlaufs sowie der Kontakte und deren Dokumentenkorpus gemacht.

Der folgende Aufruf führt beispielsweise dazu, dass der Nutzer Vorschläge für die Teilphrase jo erhält.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

Anschließend können Sie die resultierenden Vorschläge in einer für Ihre Anwendung geeigneten Form anzeigen lassen.