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 finden Sie unter Mit dem Such-Widget eine Suchoberfläche erstellen.

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. Sehen Sie sich die Abfrageergebnisse an.

Sie können die Oberfläche mit Funktionen wie Paginieren, Sortieren, Filtern, Facetten und automatischer Vervollständigung optimieren.

Suchanwendung konfigurieren

Sie müssen für jede Suchoberfläche mindestens eine Suchanwendung erstellen. Eine Suchanwendung stellt Standardparameter wie Datenquellen, Sortierreihenfolge, Filter und Facetten bereit. Sie können diese Parameter mit der Query API überschreiben.

Die Anzahl der in einer Abfrage verwendeten Datenquellen lässt sich nur auf die in der Suchanwendung konfigurierte Zahl erhöhen – nicht darüber hinaus. Mit dataSourceRestrictions können Sie eine Abfrage auf eine Teilmenge dieser Quellen beschränken.

Weitere Informationen finden Sie unter Suchanwendungen anpassen.

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten im Artikel Zugriff auf die Cloud Search API konfigurieren müssen Sie auch OAuth-Anmeldedaten für Ihre Webanwendung generieren.

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

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

Index abfragen

Verwenden Sie die Methode search, um im Index zu suchen.

Jede Anfrage muss einen Text query und einen searchApplicationId enthalten.

In diesem Beispiel wird eine Filmdatenquelle abgefragt:

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

Abfrageergebnisse anzeigen

In Suchoberflächen sollten das Element title und ein Link zum ursprünglichen Element angezeigt werden. Sie können auch Snippets und Metadaten verwenden, um die Darstellung zu verbessern.

Zusätzliche Ergebnisse verarbeiten

Cloud Search gibt zusätzliche Ergebnisse zurück, wenn es nicht genügend Übereinstimmungen für eine Anfrage gibt. Dies wird durch das Feld queryInterpretation angegeben. Wenn nur zusätzliche Ergebnisse zurückgegeben werden, ist InterpretationType gleich REPLACE. Wenn sie kombiniert sind, ist es BLEND.

Wenn Sie zusätzliche Ergebnisse zurückgeben, sollten Sie den Nutzer darüber informieren. Für a REPLACE könnten Sie Folgendes sagen: „Ihre Suche ergab keine Ergebnisse. Es werden Ergebnisse für ähnliche Anfragen angezeigt.“

Ergebnisse für Personen verarbeiten

Mit der Funktion „Personensuche“ werden in Cloud Search Dokumente zurückgegeben, die sich auf Personen und Mitarbeiterinformationen beziehen. Die Ergebnisse werden im Feld structuredResults angezeigt:

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

Abgleich direkt unterstellter Mitarbeiter

Mit der Funktion „Direkt unterstellte Mitarbeiter abgleichen“ können Nutzer die direkt unterstellten Mitarbeiter einer Person sehen. Die Antwort enthält ein assistCardProtoHolder mit einem cardType von RELATED_PEOPLE_ANSWER_CARD.

Optimierungen deaktivieren

Optimierungen wie zusätzliche Ergebnisse sind standardmäßig aktiviert. So können Sie sie deaktivieren:

Snippets markieren

Cloud Search gibt ein Snippet für indexierten Text oder HTML zurück. Wenn Suchbegriffe vorhanden sind, wird mit matchRanges ihr Standort angegeben. Verwenden Sie diese Bereiche, um Text hervorzuheben.

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

Angezeigte Metadaten

Verwenden Sie das Feld metadata für Informationen wie createTime, updateTime und strukturierte Daten. Verwenden Sie displayOptions, um strukturierte Daten zu präsentieren.

Zusätzliche Ergebnisse abrufen

Wenn Sie weitere Ergebnisse abrufen möchten, legen Sie das Feld start auf den ausgewählten Offset fest. Passen Sie die Seitengröße mit pageSize an. Verwenden Sie resultCount, um die Gesamtzahl der Elemente oder geschätzte Werte anzuzeigen.

Ergebnisse sortieren

Verwenden Sie sortOptions, um die Reihenfolge festzulegen:

  • operatorName: Die Property, nach der sortiert werden soll.
  • sortOrder: ASCENDING oder DESCENDING.

Die Relevanz ist der Standard- und sekundäre Sortierschlüssel.

Filter hinzufügen

Ergebnisse mit Filtern in der Suchanwendung oder Anfrage einschränken Wenn beide Filter für eine Quelle angeben, müssen beide als „true“ ausgewertet werden.

Filter in dataSourceRestrictions.filterOptions[] anwenden Primäre Filtertypen:

  • Objektfilter: Damit werden Übereinstimmungen auf einen bestimmten Typ beschränkt.
  • Wertefilter: Hiermit werden Übereinstimmungen auf Grundlage eines Operators und eines Werts eingeschränkt.

Mit zusammengesetzten Filtern lassen sich mehrere Wertfilter kombinieren.

Ergebnisse mithilfe von Facetten verfeinern

Mithilfe von Facetten können Nutzer Abfragen interaktiv verfeinern. Wenn Sie Facetten anfordern, werden in Cloud Search die häufigsten Werte für diese Attribute berechnet.

Typisches Muster: 1. Abfrage, in der die Facettenattribute angegeben werden. 1. Sie rendern die Such- und Attributergebnisse. 1. Der Nutzer wählt Attributwerte aus. 1. Wiederholen Sie die Abfrage mit einem Filter, der auf den Auswahlmöglichkeiten basiert.

Attributergebnisse mit ganzzahligen Feldern

Markieren Sie eine Ganzzahleigenschaft als „facetable“, um die Ergebnisse nach Bereichen zu filtern, z.B. „100–200“ Seiten. Legen Sie isFacetable auf true fest und definieren Sie Standardoptionen für die Aufteilung in Klassen im Schema.

Attributergebnisse nach Dokumentgröße oder Datum filtern

Reservierte Operatoren verwenden:

  • itemsize: für die Dateigröße in Byte.
  • createddatetimestamp: für das Erstellungsdatum.
  • lastmodified: für das Änderungsdatum.

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 Abfrageverlaufs, der Kontakte und des Dokumentinhalts gemacht.