Diese Seite wurde von der Cloud Translation API übersetzt.

Suchoberfläche mit der Query API erstellen

Die Query API bietet Such- und Vorschlagsmethoden, mit denen Sie eine Suchoberfläche erstellen oder Suchergebnisse in eine Anwendung einbetten 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

Für das Erstellen einer minimalen Suchoberfläche sind mehrere Schritte erforderlich:

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

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

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, Filter und anzufordernde Attribute. Bei Bedarf können Sie diese Parameter mit der Query API überschreiben.

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

OAuth-Anmeldedaten für die Anwendung generieren

Zusätzlich zu den Schritten unter 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 im Namen des Nutzers eine Autorisierung 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 durchzuführen.

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

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 werden. Sie können die Anzeige von Suchergebnissen weiter verbessern, indem Sie zusätzliche Informationen in den Suchergebnissen nutzen, z. B. das Snippet und die Metadaten.

Zusätzliche Ergebnisse verarbeiten

Standardmäßig gibt Cloud Search zusätzliche 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 zusätzliche Ergebnisse zurückgegeben werden. Wenn nur ergänzende Ergebnisse zurückgegeben werden, wird InterpretationType auf REPLACE gesetzt. 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. Ergebnisse für ähnliche Suchanfragen werden angezeigt.“

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

Personenergebnisse verarbeiten

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 letztere Ergebnistyp ist eine Funktion der People Search-Funktion von Cloud Search. Die Ergebnisse für eine solche Abfrage finden Sie im Feld structuredResults einer Query API-Antwort:

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

Übereinstimmende Berichte

Der direkte Berichtabgleich ist eine People Search-Funktion von Cloud Search, mit der Nutzer die direkt unterstellten Mitarbeiter einer Person in ihrer Organisation sehen können. Das Ergebnis ist im Feld structuredResults verfügbar.

Bei Abfragen zum Vorgesetzten oder zu direkt unterstellten Mitarbeitern einer Person enthält die Antwort ein assistCardProtoHolder im 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. Sie enthält die subject (die Person, die in der Abfrage enthalten war) und relatedPeople, d. h. die Gruppe von Personen, die mit dem Subjekt verbunden sind. Das Feld relationType gibt den Wert MANAGER oder DIRECT_REPORTS zurück.

Der folgende Code zeigt eine Beispielantwort für eine übereinstimmende Abfrage direkt unterstellter Mitarbeiter:

{
  "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

Standardmäßig sind Optimierungen, z. B. zusätzliche Ergebnisse, aktiviert. Sie haben jedoch die Möglichkeit, alle Optimierungen oder nur ergänzende Ergebnisse sowohl auf Suchanwendungs- als auch auf Abfrageebene zu deaktivieren:

Wenn Sie alle Optimierungen auf Suchanwendungsebene deaktivieren möchten, einschließlich ergänzender Ergebnisse, Synonymen und Rechtschreibkorrekturen, setzen Sie QueryInterpretationConfig.force_verbatim_mode in den Suchanwendungen auf true.
Wenn Sie alle Optimierungen auf Suchanfragenebene deaktivieren möchten, einschließlich ergänzender Ergebnisse, Synonymen und Rechtschreibkorrekturen, setzen Sie QueryInterpretationOptions.enableVerbatimMode in der Suchanfrage auf true.
Wenn Sie zusätzliche Ergebnisse auf Suchanwendungsebene deaktivieren möchten, setzen Sie QueryInterpretationOptions.forceDisableSupplementalResults in der Suchanfrage auf true.
Wenn Sie zusätzliche Ergebnisse auf Suchanfrageebene deaktivieren möchten, setzen Sie QueryInterpretationOptions.disableSupplementalResults in der Suchanfrage auf true.

Snippets hervorheben

Bei 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 Suchbegriffe vorhanden sind, werden auch ein oder mehrere Übereinstimmungsbereiche zurückgegeben, die die Position 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 ist.

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

Für das Snippet:

{
  "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...

Angezeigte Metadaten

Mit dem Feld metadata kannst du 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.

Verwende das Feld displayOptions, um die strukturierten Daten aufzurufen. Das Feld displayOptions enthält die Anzeigebezeichnung für den Objekttyp und eine Reihe von metalines. Jede Metazeile ist ein Array von Anzeigelabels und Wertepaaren, wie im Schema konfiguriert.

Zusätzliche Ergebnisse abrufen

Wenn Sie weitere Ergebnisse abrufen möchten, legen Sie im Feld start in der Anfrage den gewünschten Offset fest. Die Größe jeder Seite lässt sich über das 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 Haupt-Gleichheitsoperator sortieren.
sortOrder: Die Sortierrichtung, 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 Filter 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, Datenquellen weiter zu filtern:

Objektfilter über das Attribut filterOptions[].objectType – schränken übereinstimmende Elemente auf den angegebenen Typ ein, wie in einem benutzerdefinierten Schema definiert.
Wertfilter: 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, um komplexere Abfragen zu erhalten.

Im Beispiel für das Filmschema könnten Sie eine Altersbeschränkung basierend auf dem aktuellen Nutzer anwenden und die verfügbaren Filme anhand 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

Facetten sind indexierte Attribute, die Kategorien zum Verfeinern von Suchergebnissen darstellen. Mithilfe von Attributen 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 Attributen berechnet Cloud Search die häufigsten Werte für die angeforderten Attribute aus den übereinstimmenden Elementen. Diese Werte werden in der Antwort zurückgegeben. Erstellen Sie anhand dieser Werte Filter, die die Ergebnisse bei nachfolgenden Abfragen eingrenzen.

Das typische Interaktionsmuster mit Attributen sieht so aus:

Erstellen Sie eine erste Abfrage und geben Sie an, welche Attribute in die Attributergebnisse einbezogen werden sollen.
Rendern Sie die Such- und Facettenergebnisse.
Der Nutzer wählt einen oder mehrere Attributwerte aus, um die Ergebnisse zu verfeinern.
Wiederholen Sie die Abfrage mit einem Filter, der auf den ausgewählten Werten basiert.

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

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

Sie können Anfrageergebnisse auch mit auf Ganzzahlen basierenden Feldern facettieren. Sie können beispielsweise eine Ganzzahl-Property namens book_pages als facettierbar kennzeichnen, um die Ergebnisse für eine Suche nach Büchern mit Seiten mit der Bezeichnung „100–200“ einzugrenzen.

Legen Sie beim Einrichten des Schemas für das ganzzahlige Attributfeld für isFacetable den Wert true fest und fügen Sie dem integerPropertyOptions entsprechende Bucketing-Optionen hinzu. Damit wird sichergestellt, dass für jedes Attribut, das Ganzzahlen facettieren kann, Standard-Bucketing-Optionen definiert sind.

Geben Sie beim Definieren der Logik für Bucketing-Optionen ein Array von 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 Attribute überschreiben, indem Sie in der Anfrage dieselben Bucketing-Optionen für facetOptions festlegen. Bei Bedarf verwendet Cloud Search die im Schema definierten Bucketing-Optionen, wenn weder für die Suchanwendung noch die Abfrageanfrage Attributoptionen definiert sind. Die in der Abfrage definierten Attribute haben Vorrang vor den in der Suchanwendung definierten Attributen. Die in der Suchanwendung definierten Attribute haben Vorrang vor den im Schema definierten Attributen.

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

Verwenden Sie für Facetten nach Dokumentgröße itemsize und definieren Sie Bucketing-Optionen.
Verwenden Sie createddatetimestamp für die Facettierung nach dem Erstellungsdatum des Dokuments.
Verwenden Sie lastmodified für die Facettierung nach dem Änderungsdatum des Dokuments.

Attribut-Buckets interpretieren

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

Bei Attributen, die nicht auf Ganzzahlen basieren, enthält facetResults einen Eintrag für jedes angeforderte Attribut. Für jedes Attribut wird eine Liste von Werten oder Bereichen mit dem Namen buckets bereitgestellt. 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 Abfragen automatisch vervollständigen lassen, die auf dem persönlichen Abfrageverlauf sowie den Kontakten und deren Dokumentenkorpus basiert.

Der folgende Aufruf liefert beispielsweise Vorschläge für die Teilphrase jo.

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

Anschließend können Sie die resultierenden Vorschläge entsprechend Ihrer Anwendung anzeigen.