Suchoberfläche mit der Query API erstellen

Die Query API bietet Such- und Vorschlagsmethoden zum Erstellen einer Suchoberfläche oder zum Einbetten von Suchergebnissen in eine Anwendung.

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

Für die Erstellung einer minimalen Suchoberfläche sind mehrere Schritte erforderlich:

  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 Paging, Sortierung, Filterung, Facets und automatischen Vorschlägen noch weiter optimieren.

Suchanwendung konfigurieren

Sie müssen mindestens eine Suchanwendung erstellen, die mit jeder von Ihnen erstellten Suchoberfläche verknüpft werden soll. Eine Suchanwendung stellt die Standardparameter für eine Abfrage bereit, z. B. die zu verwendenden Datenquellen, die Sortierreihenfolge, die Filter und die anzufordernden Attribute. Bei Bedarf können Sie diese Parameter mit der Query API überschreiben.

Weitere Informationen zu Suchanwendungen finden Sie unter Sucherfahrung in Cloud Search anpassen.

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten im Artikel Zugriff auf die Google Cloud Search API konfigurieren müssen Sie auch OAuth-Anmeldedaten für die Webanwendung generieren. Welche Art von Anmeldedaten Sie erstellen, hängt vom Kontext ab, in dem die API verwendet wird.

Verwenden Sie die Anmeldedaten, um die Autorisierung im Namen des Nutzers anzufordern. Verwenden Sie bei der Autorisierungsanfrage den Bereich https://www.googleapis.com/auth/cloud_search.query.

Weitere Informationen zu OAuth-Optionen und Clientbibliotheken finden Sie unter [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"}).

Index abfragen

Verwenden Sie die Methode search, um Suchanfragen im Index durchzuführen.

Jede Anfrage muss zwei Informationen enthalten: einen Text query, mit dem Elemente abgeglichen werden, und einen searchApplicationId, der die ID für die zu verwendende Suchanwendung identifiziert.

Das folgende Snippet zeigt eine Abfrage an die Datenquelle des Films für die Titanic:

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

Abfrageergebnisse anzeigen

Es wird erwartet, dass in Suchoberflächen mindestens das Element title sowie ein Link zum ursprünglichen Element angezeigt wird. Sie können die Anzeige von Suchergebnissen weiter verbessern, indem Sie zusätzliche Informationen wie das Snippet und Metadaten in den Suchergebnissen nutzen.

Zusätzliche Ergebnisse verarbeiten

Standardmäßig gibt Cloud Search ergänzende Ergebnisse zurück, wenn nicht genügend Ergebnisse für die Suchanfrage des Nutzers vorliegen. Das Feld queryInterpretation in der Antwort gibt an, wann ergänzende Ergebnisse zurückgegeben werden. Wenn nur zusätzliche Ergebnisse zurückgegeben werden, wird InterpretationType auf REPLACE gesetzt. Wenn einige Ergebnisse für die ursprüngliche Abfrage zusammen mit zusätzlichen Ergebnissen zurückgegeben werden, wird InterpretationType auf BLEND gesetzt. In beiden Fällen QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Wenn einige ergänzende Ergebnisse zurückgegeben werden, sollten Sie Text angeben, um anzugeben, dass zusätzliche Ergebnisse zurückgegeben wurden. Im Fall eines REPLACE-Objekts könnten Sie beispielsweise den String „Ihre Suche nach der ursprünglichen Abfrage stimmt mit keinem Ergebnis überein. Es werden Ergebnisse für ähnliche Suchanfragen angezeigt.“

Bei einer BLEND können Sie beispielsweise den String „Ihre Suche nach der ursprünglichen Abfrage haben nicht genügend Ergebnisse gefunden. Einschließlich der Ergebnisse für ähnliche Abfragen.“

Umgang mit Personenergebnissen

Cloud Search gibt zwei Arten von Personenergebnissen zurück: Dokumente, die sich auf eine Person beziehen, deren Name in der Abfrage verwendet wird, und Mitarbeiterinformationen zu einer Person, deren Name in einer Abfrage verwendet wird. Der letzte Ergebnistyp ist eine Funktion der People Search-Funktion von Cloud Search. Die Ergebnisse für eine solche Abfrage finden Sie im Feld structuredResults einer Abfrage-API-Antwort:

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

Optimierungen deaktivieren, einschließlich ergänzender Ergebnisse

Optimierungen sind standardmäßig aktiviert, z. B. zusätzliche Ergebnisse. Sie können jedoch alle Optimierungen oder nur zusätzliche Ergebnisse auf Such- und Abfrageebene deaktivieren:

Snippets hervorheben

Bei zurückgegebenen Elementen mit indexiertem Text oder HTML-Inhalt wird ein Snippet des Inhalts zurückgegeben. Anhand dieser Inhalte können Nutzer die Relevanz des zurückgegebenen Artikels ermitteln.

Wenn im Snippet Suchbegriffe enthalten sind, wird auch ein oder mehrere Übereinstimmungsbereiche zurückgegeben, die den Standort der Begriffe angeben.

Mit matchRanges können Sie den übereinstimmenden 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;
}

Beispiel:

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

Der resultierende HTML-String lautet:

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

Metadaten anzeigen

Verwenden Sie das Feld metadata, um zusätzliche Informationen zum zurückgegebenen Element anzuzeigen, die für Nutzer relevant sein könnten. Das Feld metadata enthält die createTime und updateTime des Elements sowie alle mit dem Element verknüpften strukturierten Daten.

Verwende das Feld displayOptions, um die strukturierten Daten anzuzeigen. Das Feld displayOptions enthält das Anzeigelabel für den Objekttyp und eine Reihe von metalines. Jede Metalinie ist ein Array von Anzeigelabels und Wertpaaren, die im Schema konfiguriert wurden.

Zusätzliche Ergebnisse abrufen

Wenn Sie weitere Ergebnisse abrufen möchten, setzen Sie das Feld start in der Anfrage auf den gewünschten Offset. Sie können die Größe jeder Seite mit dem Feld pageSize anpassen.

Mit dem Feld 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

Verwenden Sie das Feld sortOptions, um 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 primären Gleichheitsoperator sortieren.
  • sortOrder: Die Sortierreihenfolge, entweder ASCENDING oder DESCENDING.

Die Relevanz wird auch 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 können Sie die Ergebnisse mithilfe von Filtern weiter einschränken. Sie können sowohl in der Suchanwendung als auch in der Suchanfrage Filter 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: Damit werden übereinstimmende Elemente auf den angegebenen Typ beschränkt, wie in einem benutzerdefinierten Schema definiert.
  • Wertfilter: Damit werden übereinstimmende Elemente basierend auf einem Abfrageoperator und dem angegebenen Wert eingeschränkt.

Mit zusammengesetzten Filtern können Sie mehrere Wertfilter zu logischen Ausdrücken kombinieren, um komplexere Abfragen zu erhalten.

Im Beispiel für ein Filmschema könnten Sie eine Altersbeschränkung auf der Grundlage des aktuellen Nutzers anwenden und die verfügbaren Filme auf Grundlage der MPAA-Bewertung einschränken.

{
  "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 mit Attributen verfeinern

Attribute sind indexierte Attribute, die Kategorien zum Verfeinern von Suchergebnissen darstellen. Mit Attributen können Nutzer ihre Abfragen interaktiv optimieren und relevante Elemente schneller finden.

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

Beim Anfordern von Attributen berechnet Cloud Search die häufigsten Werte für die angeforderten Attribute der übereinstimmenden Elemente. Diese Werte werden in der Antwort zurückgegeben. Verwenden Sie diese Werte, um Filter zu erstellen, die die Ergebnisse bei nachfolgenden Abfragen eingrenzen.

Das typische Interaktionsmuster mit Attributen lautet:

  1. Erstellen Sie eine erste Abfrage, die angibt, welche Attribute in den Attributergebnissen enthalten sein sollen.
  2. Hiermit werden die Such- und Attributergebnisse gerendert.
  3. Der Nutzer wählt einen oder mehrere Attributwerte aus, um die Ergebnisse zu verfeinern.
  4. Wiederholen Sie die Abfrage mit einem Filter, der auf den ausgewählten Werten basiert.

Wenn du beispielsweise Filmabfragen nach Jahr und MPAA-Bewertung verfeinern möchtest, kannst du die Property facetOptions in die Abfrage aufnehmen.

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

Attributergebnisse mit auf Ganzzahlen basierenden Feldern

Sie können auch Anfrageergebnisse mit ganzzahligen Feldern angeben. Sie können beispielsweise eine Ganzzahl-Property mit dem Namen book_pages als facetable kennzeichnen, um die Ergebnisse für eine Suche nach Büchern mit Seiten vom Typ „100–200“ zu verfeinern.

Wenn Sie das Schema des Ganzzahlattribut-Felds festlegen, setzen Sie isFacetable auf true und fügen dem integerPropertyOptions entsprechende Bucketing-Optionen hinzu. Dadurch wird sichergestellt, dass für jedes Attribut mit ganzzahliger Facettierung Standard-Bucketing-Optionen definiert sind.

Geben Sie beim Definieren der Logik für Bucketing-Optionen ein Array von inkrementellen Werten an, die Bereiche kennzeichnen. Wenn der Endnutzer beispielsweise Bereiche als 2, 5, 10, 100 angibt, werden die Attribute für <2, [2-5), [5-10), [10-100), >=100 berechnet.

Sie können ganzzahlige Attribute überschreiben, indem Sie dieselben Bucketing-Optionen für facetOptions in der Anfrage definieren. Cloud Search verwendet bei Bedarf die im Schema definierten Bucketing-Optionen, wenn weder für die Suchanwendung noch für die Abfrage Facet-Optionen definiert sind. In der Abfrage definierte Attribute haben Vorrang vor in der Suchanwendung definierten Attributen und in der Suchanwendung definierte Attribute haben Vorrang vor im Schema definierten Attributen.

Facettenergebnisse nach Dokumentgröße oder Datum

Sie können reservierte Operatoren verwenden, um die Suchergebnisse nach der Dateigröße des Dokuments in Byte oder nach dem Erstellen oder Ändern eines Dokuments zu verfeinern. Sie müssen kein benutzerdefiniertes Schema definieren, aber den Wert operatorName in der FacetOptions Ihrer Suchanwendung angeben.

  • Verwenden Sie itemsize für Facetten nach Dokumentgröße und definieren Sie Bucketing-Optionen.
  • Verwenden Sie createddatetimestamp für das Facetten nach dem Erstellungsdatum des Dokuments.
  • Verwenden Sie lastmodified für das Attribut „Änderungsdatum des Dokuments“.

Attribut-Buckets interpretieren

Die Property facetResults in der Suchanfrage enthält für jedes bucket im Feld filter die genaue Filteranfrage des Nutzers.

Bei Attributen, die nicht auf Ganzzahlen basieren, enthält facetResults für jedes angeforderte Attribut einen Eintrag. Für jedes Attribut wird eine Liste von Werten oder Bereichen namens buckets bereitgestellt. Die am häufigsten vorkommenden Werte werden zuerst angezeigt.

Wenn ein Nutzer einen oder mehrere Werte zum Filtern auswählt, erstellen Sie eine neue Abfrage mit den ausgewählten Filtern und fragen die API noch einmal ab.

Vorschläge hinzufügen

Mit der suggest-API können Sie automatische Vervollständigungen für Abfragen bereitstellen, die auf dem persönlichen Abfrageverlauf des Nutzers sowie auf Kontakten und seinem Dokumentenkorpus basieren.

Der folgende Aufruf schlägt beispielsweise Vorschläge für die Teilwortgruppe jo vor.

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

Sie können dann die entsprechenden Vorschläge für Ihre Anwendung anzeigen lassen.