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 Suchoberfläche mit dem Such-Widget 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. Abfrageergebnisse anzeigen

Sie können die Oberfläche mit Funktionen wie Paginierung, Sortierung, Filterung, Facetten und automatischer Vervollständigung optimieren.

Suchanwendung konfigurieren

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

Die Anzahl der in einer Abfrage verwendeten Datenquellen kann nicht über die in der Suchanwendung konfigurierte Anzahl hinaus erhöht werden. 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 eine Aktualisierung nicht kompatibel ist, schlägt die Schemaaktualisierung fehl.

Weitere Informationen finden Sie unter Sucherlebnis anpassen.

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten unter 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 search Methode, um den Index zu durchsuchen.

Jede Anfrage muss eine query und eine searchApplicationId enthalten.

In diesem Beispiel wird eine Filmdatenquelle abgefragt:

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

Abfrageergebnisse anzeigen

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

Hinweis: Wenn keine Ergebnisse angezeigt werden, prüfen Sie, ob Sie eine benutzerdefinierte Such anwendung erstellt und die Datenquelle dafür aktiviert haben.

Zusätzliche Ergebnisse verarbeiten

Cloud Search gibt zusätzliche Ergebnisse zurück, wenn nicht genügend Übereinstimmungen für eine Abfrage vorhanden sind. Das queryInterpretation Feld gibt dies an. Wenn nur zusätzliche Ergebnisse zurückgegeben werden, ist InterpretationType auf REPLACE gesetzt. Wenn sie kombiniert werden, ist es BLEND.

Wenn Sie zusätzliche Ergebnisse zurückgeben, sollten Sie den Nutzer darüber informieren. Bei einem REPLACE können Sie beispielsweise Folgendes sagen: „Ihre Suche hat keine Ergebnisse geliefert. Es werden Ergebnisse für ähnliche Suchanfragen angezeigt.“

Ergebnisse für Personen verarbeiten

Mit der Funktion „Personensuche“ gibt Cloud Search Dokumente zu Personen und Mitarbeiterinformationen zurück. Die Ergebnisse befinden sich im structuredResults Feld:

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

Hinweis: Wenn Sie mehr als 20 benutzerdefinierte Attribute definieren, werden bei der Personensuche nur 20 verwendet.

Übereinstimmungen für direkt unterstellte Mitarbeiter

Mit der Funktion „Übereinstimmungen für direkt unterstellte Mitarbeiter“ können Nutzer die direkt unterstellten Mitarbeiter einer Person sehen. Die Antwort enthält einen assistCardProtoHolder mit einem cardType von RELATED_PEOPLE_ANSWER_CARD.

Optimierungen deaktivieren

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

• Ebene der Suchanwendung: Setzen Sie force_verbatim_mode auf true.
• Ebene der Abfrage: Setzen Sie enableVerbatimMode auf true.

Snippets markieren

Cloud Search gibt ein Snippet für indexierten Text oder HTML zurück. Wenn Suchbegriffe vorhanden sind, gibt matchRanges ihre Position an. Verwenden Sie diese Bereiche, um Text zu markieren.

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

Beispiel für ein 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

Verwenden Sie das metadata Feld für Informationen wie createTime, updateTime und strukturierte Daten. Verwenden Sie displayOptions zum Anzeigen strukturierter Daten.

Zusätzliche Ergebnisse abrufen

Wenn Sie weitere Ergebnisse abrufen möchten, setzen Sie das start Feld auf den ausgewählten Offset. Passen Sie die Seitengröße mit pageSize an. Mit resultCount können Sie die Gesamtzahl der Elemente oder geschätzte Anzahlen anzeigen.

Ergebnisse sortieren

Verwenden Sie sortOptions , um die Reihenfolge anzugeben:

• operatorName: Das Attribut, nach dem sortiert werden soll.
• sortOrder: ASCENDING oder DESCENDING.

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

Filter hinzufügen

Sie können die Ergebnisse mit Filtern in der Suchanwendung oder Anfrage einschränken. Wenn in beiden Filtern für eine Quelle angegeben sind, muss die Prüfung gegen beide „true“ ergeben.

Wenden Sie Filter in dataSourceRestrictions.filterOptions[] an. Primäre Filtertypen:

• Objektfilter: Beschränken Sie die Übereinstimmungen auf einen bestimmten Typ.
• Wertefilter: Beschränken Sie die Übereinstimmungen auf Grundlage eines Operators und eines Werts.

Zusammengesetzte Filter kombinieren mehrere Wertefilter.

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 mit Angabe der Facettenattribute. 1. Such- und Facetten-Ergebnisse rendern. 1. Nutzer wählt Facettenwerte aus. 1. Abfrage mit einem Filter wiederholen, der auf den ausgewählten Werten basiert.

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

Facetten-Ergebnisse mit ganzzahlbasierten Feldern

Markieren Sie ein ganzzahliges Attribut als facettierbar, um die Ergebnisse nach Bereichen zu verfeinern (z.B. „100–200“ Seiten). Setzen Sie isFacetable auf true und definieren Sie im Schema Standardoptionen für die Gruppierung.

Facetten-Ergebnisse nach Dokumentgröße oder Datum

Verwenden Sie reservierte Operatoren:

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

Vorschläge hinzufügen

Verwenden Sie die Suggest API für die automatische Vervollständigung auf Grundlage des Abfrageverlaufs, der Kontakte und des Dokumenteninhalts.