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 ein Such-Widget verwenden. Weitere Informationen findest du unter Suchoberfläche mit dem Such-Widget erstellen.

Suchoberfläche erstellen

Das Erstellen einer minimalen Suchoberfläche erfordert mehrere Schritte:

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

Sie können die Suchoberfläche mit Features wie Paging, Sortieren, Filtern, Attributen und automatischer Vorschläge weiter optimieren.

Suchanwendung konfigurieren

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

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

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten in Zugriff auf die Google Cloud Search REST API konfigurieren müssen Sie auch OAuth-Anmeldedaten für die Webanwendung generieren. Der Typ der Anmeldedaten 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 beim Anfordern der Autorisierung den Bereich https://www.googleapis.com/auth/cloud_search.query.

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

Index abfragen

Verwenden Sie die Methode search, um Suchvorgänge im Index auszuführen.

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

Das folgende Snippet zeigt eine Abfrage der Filmdatenquelle für den Film Titanic:

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

Abfrageergebnisse anzeigen

Es wird zumindest erwartet, dass in Suchoberflächen das Element title und ein Link zum ursprünglichen Element angezeigt werden. Du kannst die Anzeige von Suchergebnissen weiter optimieren, indem du zusätzliche Informationen in den Suchergebnissen verwendest, z. B. das Snippet und die Metadaten.

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 vorhanden sind. Das Feld queryInterpretation in der Antwort gibt an, wann zusätzliche Ergebnisse zurückgegeben werden. Wenn nur ergänzende Ergebnisse zurückgegeben werden, ist InterpretationType auf REPLACE gesetzt. Wenn nur einige Ergebnisse der ursprünglichen Abfrage und ergänzende Ergebnisse 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, können Sie einen Text angeben, der angibt, dass zusätzliche Ergebnisse zurückgegeben wurden. Im Fall einer REPLACE können Sie beispielsweise den String searchIhre Suche nach Ihrer ursprünglichen Abfrage ergab keine Übereinstimmung. Ergebnisse für ähnliche Suchanfragen."

Im Fall einer BLEND können Sie den String "Ihre Suche nach Ihrer ursprünglichen Abfrage liefert keine ausreichenden Ergebnisse. einschließlich Ergebnissen für ähnliche Abfragen."

Ergebnisse von Personen verarbeiten

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

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

Optimierungen, einschließlich zusätzlicher Ergebnisse, deaktivieren

Standardmäßig sind Optimierungen wie zusätzliche Ergebnisse aktiviert. Sie können jedoch sowohl auf Such- als auch auf Suchanfragenebene alle Optimierungen oder nur zusätzliche Ergebnisse deaktivieren:

Ausschnitte hervorheben

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

Wenn im Snippet Abfragebegriffe vorhanden sind, wird auch ein oder mehrere Übereinstimmungsbereiche zurückgegeben, die die Position der Begriffe angeben.

Verwende matchRanges, um übereinstimmenden Text beim Rendern der Ergebnisse hervorzuheben. Im folgenden JavaScript-Beispiel wird das Snippet in HTML-Markup konvertiert, wobei jeder übereinstimmende Bereich in ein <span>-Tag eingebunden 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;
}

Anhand des Snippets:

{
  "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 zu dem zurückgegebenen Element anzuzeigen, die für Nutzer relevant sein können. Das Feld metadata enthält die createTime und updateTime des Elements sowie alle strukturierten Daten, die mit dem Element verknüpft sind.

Verwende das Feld displayOptions, um die strukturierten Daten aufzurufen. Das Feld displayOptions enthält das Anzeigelabel für den Objekttyp und den Satz metalines. Jede Metazeile ist ein Array von Displaylabels und Wertpaaren, wie im Schema konfiguriert.

Zusätzliche Ergebnisse abrufen

Wenn Sie weitere Ergebnisse abrufen möchten, legen Sie für das Feld start in der Anfrage den gewünschten Versatz fest. Du kannst 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 zum Durchblättern der zurückgegebenen Elemente anzeigen. 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 für strukturierte Daten, nach dem sortiert werden soll. Bei Attributen mit mehreren Operatoren können Sie nur mit dem Hauptgleichheitsoperator sortieren.
  • sortOrder: Die Sortierreihenfolge, entweder ASCENDING oder DESCENDING.

Die Relevanz wird auch als sekundärer Sortierschlüssel verwendet. Wenn in einer Abfrage keine Sortierfolge 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 Filter sowohl in der Suchanwendung als auch in der Suchanfrage angeben.

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

Datenquellen lassen sich auf zwei Arten weiter filtern:

  • Objektfilter über das Attribut filterOptions[].objectType: Damit werden übereinstimmende Elemente auf den in einem benutzerdefinierten Schema definierten Typ eingeschränkt.
  • Wertfilter: Hiermit werden übereinstimmende Elemente anhand eines Abfrageoperators und des angegebenen Werts eingeschränkt.

Zusammengesetzte Filter ermöglichen es, mehrere Wertfilter zu logischen Ausdrücken zu kombinieren, um komplexere Abfragen zu ermöglichen.

Im Beispiel für das Filmschema können Sie auf Basis des aktuellen Nutzers eine Altersbeschränkung festlegen und die verfügbaren Filme auf Grundlage der MPAA-Altersfreigabe 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 für die Verfeinerung der Suchergebnisse darstellen. Mit Attributen können Sie Nutzern helfen, ihre Abfragen interaktiv zu verfeinern und schneller relevante Elemente zu finden.

Attribute 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 unter den übereinstimmenden Elementen. Diese Werte werden in der Antwort zurückgegeben. Mit diesen Werten können Sie Filter 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. Such- und Attributergebnisse rendern.
  3. Der Nutzer wählt einen oder mehrere Attributwerte aus, um die Ergebnisse einzugrenzen.
  4. Wiederholen Sie die Abfrage mit einem Filter, der auf den ausgewählten Werten basiert.

Wenn Sie beispielsweise Filmabfragen nach Jahr und MPAA-Bewertung verfeinern möchten, nehmen Sie die Property facetOptions in die Abfrage auf.

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

Attribut-Buckets interpretieren

Das Attribut facetResults in der Antwort enthält für jedes angefragte Attribut einen Eintrag. Für jedes Attribut wird eine Liste von Werten oder Bereichen mit dem Namen 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 eine automatische Vervollständigung für Abfragen bereitstellen, die auf dem persönlichen Abfrageverlauf des Nutzers sowie auf Kontakten und seinem Dokumentkorpus basieren.

Der folgende Aufruf liefert beispielsweise Vorschläge für den Teilsatz jo.

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

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