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.

Hinweis :Cloud Search aktualisiert Suchanwendungen, wenn Sie ein Schema aktualisieren oder löschen. Wenn Sie beispielsweise einen Schemaoperator umbenennen, wird er auch in der Suchanwendung umbenannt. Wenn ein Update nicht kompatibel ist, schlägt die Schemaaktualisierung fehl.

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 den Index zu durchsuchen.

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.

Hinweis :Wenn keine Ergebnisse angezeigt werden, haben Sie möglicherweise noch keine benutzerdefinierte Suchanwendung erstellt und die Datenquelle dafür aktiviert.

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 ergänzende Ergebnisse zurückgegeben werden, ist InterpretationType gleich REPLACE. Wenn sie zusammengefasst 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 Treffer. Es werden Ergebnisse für ähnliche Anfragen angezeigt.“

Ergebnisse für Personen verarbeiten

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

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

Hinweis :Wenn Sie mehr als 20 benutzerdefinierte Attribute definieren, werden nur 20 davon für die Personensuche verwendet.

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:

• Suchanwendungsebene: Legen Sie force_verbatim_mode auf true fest.
• Abfrageebene: Legen Sie enableVerbatimMode auf true fest.

Snippets markieren

Cloud Search gibt ein Snippet für indexierten Text oder HTML zurück. Wenn Suchbegriffe vorhanden sind, wird ihr Standort durch matchRanges 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 anzugeben:

• 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 in beiden Filtern Filter für eine Quelle angegeben sind, muss die Prüfung gegen beide "true" ergeben.

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

• Objektfilter: Damit können Sie die Übereinstimmungen auf einen bestimmten Typ beschränken.
• Wertefilter: Hiermit werden Übereinstimmungen auf Grundlage eines Operators und eines Werts eingeschränkt.

Zusammengesetzte Filter kombinieren mehrere Wertfilter.

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 Facettenwerte aus. 1. Wiederholen Sie die Abfrage mit einem Filter, der auf den Auswahlmöglichkeiten basiert.

Hinweis: Facetten werden nur für strukturierte Datenattribute unterstützt.

Attributergebnisse mit ganzzahligen Feldern

Markieren Sie eine Ganzzahleigenschaft als facettierbar, 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 Gruppen im Schema.

Attributergebnisse nach Dokumentgröße oder Datum aufschlüsseln

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.