Diese Seite wurde von der Cloud Translation API übersetzt.

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:

Suchanwendung konfigurieren
OAuth-Anmeldedaten für die Anwendung generieren
Index abfragen
Abfrageergebnisse anzeigen lassen

Sie können die Suchoberfläche mit Funktionen wie Paginieren, Sortieren, Filtern, Facetten und automatischen Vorschlägen weiter optimieren.

Suchanwendung konfigurieren

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

Weitere Informationen zu Suchanwendungen finden Sie im Hilfeartikel Suche in Cloud Search anpassen.

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten in der Anleitung zum Konfigurieren des Zugriffs auf die Google Cloud Search API müssen Sie auch die 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 eine Autorisierung im Namen des Nutzers anzufordern. Verwenden Sie dabei 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

Führen Sie beim Autorisieren mithilfe der search-Methode Suchanfragen im Index durch.

Jede Anfrage muss zwei Informationen enthalten: eine Textabfrage (query), mit der Elemente abgeglichen werden, und einen Wert für searchApplicationId, also die ID der zu verwendenden Suchanwendung.

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 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 optimieren, indem Sie zusätzliche Informationen in diesen Ergebnissen nutzen, z. B. Snippets und Metadaten.

Zusätzliche Ergebnisse verarbeiten

Standardmäßig gibt Cloud Search ergänzende Ergebnisse zurück, wenn für die Suchanfrage des Nutzers nicht genügend Ergebnisse vorhanden sind. Das Feld queryInterpretation in der Antwort gibt an, wann ergänzende Ergebnisse zurückgegeben werden. Wenn nur ergänzende Ergebnisse zurückgegeben werden, wird InterpretationType auf REPLACE festgelegt. Wenn für die ursprüngliche Abfrage einige Ergebnisse zusammen mit ergänzenden 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, können Sie Text angeben, der darauf hinweist, dass zusätzliche Ergebnisse zurückgegeben wurden. Bei REPLACE könnten Sie beispielsweise den String „Bei Ihrer Suche nach Ihrer ursprünglichen Abfrage haben keine Ergebnisse gefunden. Es werden Ergebnisse für ähnliche Suchanfragen angezeigt.“

Im Fall von BLEND könnten Sie beispielsweise den String „Ihre Suche nach Ihrer ursprünglichen Abfrage ergab nicht genügend Ergebnisse. einschließlich Ergebnissen für ähnliche Suchanfragen.“

Ergebnisse für Personen verarbeiten

Cloud Search gibt zwei Arten von „Personenergebnissen“ zurück: Dokumente zu einer Person, deren Name in der Suchanfrage verwendet wird, und Mitarbeiterinformationen zu einer Person, deren Name in der Suchanfrage verwendet wird. Letzterer Ergebnistyp ist eine Funktion der Personensuche in Cloud Search. Die Ergebnisse einer solchen Suchanfrage finden Sie im Feld structuredResults einer API-Antwort:

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

Direkt unterstellte Mitarbeiter abgleichen

Die Zuordnung von direkten Mitarbeitern ist eine Funktion der Personensuche in Cloud Search, mit der Nutzer die direkten Mitarbeiter einer Person in ihrer Organisation sehen können. Das Ergebnis ist im Feld structuredResults verfügbar.

Bei Suchanfragen nach dem Vorgesetzten oder den direkten Mitarbeitern einer Person enthält die Antwort ein assistCardProtoHolder in der structuredResults. assistCardProtoHolder hat ein Feld namens cardType, das den Wert RELATED_PEOPLE_ANSWER_CARD hat. assistCardProtoHolder enthält eine Karte mit dem Namen relatedPeopleAnswerCard, die die eigentliche Antwort enthält. Es enthält die subject (die Person, die in die Abfrage einbezogen wurde) und relatedPeople, d. h. die Gruppe von Personen, die mit dem Subjekt in Verbindung stehen. Das Feld relationType gibt den Wert MANAGER oder DIRECT_REPORTS zurück.

Der folgende Code zeigt eine Beispielantwort für eine Abfrage, bei der direkte Berichte abgeglichen werden:

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

Optimierungen deaktivieren, einschließlich ergänzender Ergebnisse

Optimierungen wie ergänzende Ergebnisse sind standardmäßig aktiviert. Sie können jedoch alle Optimierungen oder nur ergänzende Ergebnisse sowohl auf Suchanwendungs- als auch auf Abfrageebene deaktivieren:

Wenn Sie alle Optimierungen auf Suchanwendungsebene deaktivieren möchten, einschließlich ergänzender Ergebnisse, Synonyme und Rechtschreibkorrekturen, setzen Sie in den Suchanwendungen QueryInterpretationConfig.force_verbatim_mode auf true.
Wenn Sie alle Optimierungen auf Suchanfrageebene deaktivieren möchten, einschließlich ergänzender Ergebnisse, Synonyme und Rechtschreibkorrekturen, setzen Sie in der Suchanfrage QueryInterpretationOptions.enableVerbatimMode auf true.
Wenn Sie ergänzende Ergebnisse auf Ebene der Suchanwendung deaktivieren möchten, setzen Sie in der Suchanfrage QueryInterpretationOptions.forceDisableSupplementalResults auf true.
Wenn Sie ergänzende Ergebnisse auf Suchanfrageebene deaktivieren möchten, legen Sie in der Suchanfrage QueryInterpretationOptions.disableSupplementalResults auf true fest.

Snippets hervorheben

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

Wenn im Snippet Suchbegriffe vorhanden sind, wird auch mindestens ein Bereich mit den Stellen zurückgegeben, an denen sich die übereinstimmenden Begriffe befinden.

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

Angenommen, es liegt dieses Snippet vor:

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

Der resultierende HTML-String ist:

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

Angezeigte Metadaten

Mit dem Feld metadata können Sie sich zusätzliche Informationen zum zurückgegebenen Element anzeigen lassen, die für Nutzer relevant sein können. Das Feld metadata enthält die createTime und updateTime des Artikels sowie alle mit dem Artikel verknüpften strukturierten Daten.

Das Feld displayOptions dient zur Anzeige strukturierter Daten. Das Feld displayOptions enthält das Anzeigelabel für den Objekttyp und eine Reihe von metalines. Jede Metazeile ist der Schemakonfiguration entsprechend ein Array von Anzeigelabels und Wertepaaren.

Zusätzliche Ergebnisse abrufen

Sie können weitere Ergebnisse abrufen, indem Sie das Feld start in der Anfrage auf den gewünschten Offset-Wert festlegen. Außerdem haben Sie die Möglichkeit, die Größe jeder Seite mit dem Feld pageSize anzupassen.

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 wichtigsten Gleichheitsoperator sortieren.
sortOrder: die Sortierreihenfolge, entweder ASCENDING oder DESCENDING.

Die Relevanz wird 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 diese sowohl in der Suchanwendung als auch in der Suchanfrage 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: So werden übereinstimmende Elemente auf den angegebenen Typ beschränkt. Dies wird in einem benutzerdefinierten Schema definiert.
Wertefilter: Hiermit werden übereinstimmende Elemente auf Grundlage eines Abfrageoperators und des bereitgestellten Werts eingeschränkt.

Zusammengesetzte Filter ermöglichen es, mehrere Wertfilter zu logischen Ausdrücken zu kombinieren. Auf diese Art können komplexere Abfragen gestellt werden.

Im Beispiel mit dem Filmschema haben Sie z. B. die Möglichkeit, je nach aktuellem Nutzer eine Altersbeschränkung anzuwenden und die verfügbaren Filme auf Grundlage der MPAA-Bewertung einzuschrä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 mithilfe von Facetten verfeinern

Facetten sind indexierte Attribute, also Kategorien. Mithilfe von Facetten können Nutzer Abfragen interaktiv verfeinern und relevante Elemente schneller finden.

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

Beim Anfordern von Facetten werden in Cloud Search diejenigen Werte der angefragten Attribute ermittelt, die in den übereinstimmenden Elementen vorkommen. Diese Werte werden in der Antwort zurückgegeben. Mit diesen Werten können Sie Filter erstellen, die bei nachfolgenden Abfragen die Ergebnisse eingrenzen.

Die Interaktion mit Facetten verläuft üblicherweise so:

Sie erstellen eine erste Abfrage, in der Sie angeben, welche Attribute in den Facetten-Ergebnissen berücksichtigt werden sollen.
Sie rendern die Such- und Facetten-Ergebnisse.
Der Nutzer wählt mindestens einen Facettenwert aus, um die Ergebnisse zu verfeinern.
Sie wiederholen die Abfrage mit einem Filter, der auf den ausgewählten Werten basiert.

Wenn Sie beispielsweise Filmabfragen nach Jahr und MPAA-Bewertung verfeinern möchten, sollte die Abfrage das Attribut facetOptions berücksichtigen.

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

Sie können auch Ergebnisse mit ganzzahlbasierten Feldern anfordern. Sie können beispielsweise eine Ganzzahleigenschaft namens book_pages als facettierbar markieren, um die Ergebnisse für eine Suche nach Büchern mit „100–200“ Seiten einzugrenzen.

Legen Sie beim Einrichten des Feldschemas für Ganzzahleigenschaften isFacetable auf true fest und fügen Sie integerPropertyOptions die entsprechenden Bucketing-Optionen hinzu. So ist für jede Property mit einer facettierten Ganzzahl standardmäßig eine Bucketing-Option definiert.

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

Sie können ganzzahlbasierte Facetten überschreiben, indem Sie in der Anfrage dieselben Bucketing-Optionen für facetOptions definieren. Bei Bedarf verwendet Cloud Search die im Schema definierten Bucketing-Optionen, wenn weder für die Suchanwendung noch die Abfrageanfrage Attributoptionen definiert sind. In der Abfrage definierte Facetten haben Vorrang vor in der Suchanwendung definierten Facetten. In der Suchanwendung definierte Facetten haben Vorrang vor im Schema definierten Facetten.

Sie können reservierte Operatoren verwenden, um die Suchergebnisse nach der Dateigröße des Dokuments, gemessen in Byte oder danach, wann ein Dokument erstellt oder geändert wurde, zu verfeinern. Sie müssen kein benutzerdefiniertes Schema definieren, aber Sie müssen den operatorName-Wert in der FacetOptions Ihrer Suchanwendung angeben.

Wenn Sie nach Dokumentgröße facettieren möchten, verwenden Sie itemsize und definieren Sie Bucketing-Optionen.
Verwenden Sie createddatetimestamp, um nach dem Erstellungsdatum des Dokuments zu facettieren.
Verwenden Sie lastmodified, um nach dem Datum der letzten Änderung des Dokuments zu facettieren.

Facetten-Buckets interpretieren

Das Attribut facetResults in der Antwort auf die Suchanfrage enthält die genaue Filteranfrage des Nutzers im Feld filter für jede bucket.

Bei Facets, die nicht auf Ganzzahlen basieren, enthält facetResults einen Eintrag für jedes angefragte Attribut. Für jedes Attribut ist eine Liste von Werten oder Bereichen angegeben, sogenannte buckets. Die am häufigsten auftretenden 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 Sie die API noch einmal ab.

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 persönlichen Abfrageverlaufs sowie der Kontakte und deren Dokumentenkorpus gemacht.

Der folgende Aufruf führt beispielsweise dazu, dass der Nutzer Vorschläge für die Teilphrase jo erhält.

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

Anschließend können Sie die resultierenden Vorschläge in einer für Ihre Anwendung geeigneten Form anzeigen lassen.