Diese Seite wurde von der Cloud Translation API übersetzt.

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 sollten Sie das Such-Widget verwenden. Weitere Informationen finden Sie unter Suchoberfläche mit dem Such-Widget erstellen.

Suchoberfläche erstellen

Das Erstellen einer minimalen Suchoberfläche erfordert mehrere Schritte:

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

Sie können die Suchoberfläche mit Funktionen wie Paginierung, Sortierung, Filterung, Facetten und automatischen Vorschlägen weiter optimieren.

Suchanwendung konfigurieren

Sie müssen mindestens eine Suchanwendung erstellen, die mit jeder Suchoberfläche verknüpft werden soll, 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 Abfrage-API überschreiben.

Weitere Informationen zu Suchanwendungen finden Sie im Hilfeartikel Suchfunktion 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. Die Art der Anmeldedaten, die 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 den Bereich https://www.googleapis.com/auth/cloud_search.query, wenn Sie eine Autorisierung anfordern.

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 im Index zu suchen.

Jede Anfrage muss zwei Informationen enthalten: den 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 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 der Suchergebnisse weiter verbessern, indem Sie zusätzliche Informationen in den Suchergebnissen nutzen, z. B. das Snippet und die Metadaten.

Umgang mit zusätzlichen Ergebnissen

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, 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 ist QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY.

Wenn einige ergänzende Ergebnisse zurückgegeben werden, sollten Sie Text angeben, der darauf hinweist, dass zusätzliche Ergebnisse zurückgegeben wurden. Im Fall von REPLACE könnten Sie beispielsweise den String „Ihre Suche nach Ihrer ursprünglichen Abfrage ergab keine Ergebnisse. Es werden Ergebnisse für ähnliche Suchanfragen angezeigt.“

Bei einem BLEND wird möglicherweise der String „Ihre Suche nach Ihrer ursprünglichen Abfrage stimmte nicht mit genügend Ergebnissen überein. Dazu gehören auch Ergebnisse 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 für eine Person, deren Name in einer Abfrage verwendet wird. Die letztere Art von Ergebnis ist eine Funktion der People Search-Funktion von Cloud Search. Die Ergebnisse für eine solche Abfrage finden Sie im Feld structuredResults einer API-Abfrageantwort:

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

Übereinstimmung für direkte Berichte

„Direct Report Matching“ 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 direkt unterstellten Mitarbeitern einer Person enthält die Antwort ein assistCardProtoHolder innerhalb von structuredResults. assistCardProtoHolder hat ein Feld namens cardType, das gleich RELATED_PEOPLE_ANSWER_CARD ist. assistCardProtoHolder enthält eine Karte mit dem Namen relatedPeopleAnswerCard, die die tatsächliche Antwort enthält. Sie enthält subject (die Person, die in der Abfrage enthalten war) und relatedPeople, also die Personen, die mit dem Betreff in Zusammenhang stehen. Das Feld relationType gibt den Wert MANAGER oder DIRECT_REPORTS zurück.

Der folgende Code zeigt eine Beispielantwort für eine übereinstimmende Abfrage für direkte Berichte:

{
  "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, z. B. 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 Ebene der Suchanwendung deaktivieren möchten, einschließlich zusätzlicher Ergebnisse, Synonyme 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, Synonyme und Rechtschreibkorrekturen, setzen Sie QueryInterpretationOptions.enableVerbatimMode in der Suchanfrage auf true.
Wenn Sie zusätzliche Ergebnisse auf Ebene der Suchanwendung deaktivieren möchten, setzen Sie QueryInterpretationOptions.forceDisableSupplementalResults in der Suchanfrage auf true.
Wenn Sie zusätzliche Ergebnisse auf Suchanfragenebene deaktivieren möchten, setzen Sie QueryInterpretationOptions.disableSupplementalResults in der Suchanfrage auf true.

Snippets markieren

Bei Elementen mit indexiertem Text oder HTML-Inhalt wird ein Snippet des Inhalts zurückgegeben. Anhand dieses Inhalts können Nutzer die Relevanz des zurückgegebenen Elements bestimmen.

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

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

Aufgrund des 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...

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 Artikels sowie alle mit dem Artikel verknüpften strukturierten Daten, die zurückgegeben werden können.

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

Zusätzliche Ergebnisse abrufen

Wenn Sie zusätzliche Ergebnisse abrufen möchten, legen Sie für das Feld start in der Anfrage den gewünschten Offset fest. Die Größe der einzelnen Seiten lässt sich mit dem Feld pageSize anpassen.

Mit dem Feld resultCount können Sie die Anzahl der zurückgegebenen Elemente oder die Seitensteuerelemente aufrufen, mit denen Sie in zurückgegebenen Elementen blättern können. 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 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 auch 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 den Filter in das Feld dataSourceRestrictions.filterOptions[] ein.

Es gibt zwei grundlegende Möglichkeiten, eine Datenquelle weiter zu filtern:

Objektfilter, über das Attribut filterOptions[].objectType: beschränkt übereinstimmende Elemente auf den angegebenen Typ, wie in einem benutzerdefinierten Schema definiert.
Wertfilter: Damit werden übereinstimmende Elemente basierend auf einem Abfrageoperator und dem bereitgestellten Wert eingeschränkt.

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

Im Beispiel für das Filmschema können Sie eine Altersbeschränkung auf Basis des aktuellen Nutzers anwenden 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

Facetten sind indexierte Attribute, die Kategorien zur Verfeinerung von Suchergebnissen darstellen. Mit 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 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. Verwenden Sie diese Werte, um Filter zu erstellen, mit denen die Ergebnisse bei nachfolgenden Abfragen eingegrenzt werden.

Ein typisches Interaktionsmuster mit Facetten sieht so aus:

Führen Sie eine erste Abfrage aus, um anzugeben, welche Attribute in den Attributergebnissen enthalten sein sollen.
Rendern Sie die Such- und Attributergebnisse.
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 Ergebnisse auch mit ganzzahligen Feldern facettieren. Sie können beispielsweise ein Ganzzahlattribut namens book_pages als facettierbar markieren, um die Ergebnisse für eine Suche zu Büchern mit den Seiten „100–200“ zu verfeinern.

Wenn Sie das Schema für das Ganzzahlattributfeld einrichten, legen Sie isFacetable auf true fest und fügen Sie dem integerPropertyOptions die entsprechenden Bucketing-Optionen hinzu. Dadurch wird sichergestellt, dass für jedes Attribut, das mit Ganzzahlen verknüpft ist, Standard-Bucketing-Optionen definiert sind.

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

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

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

Verwenden Sie itemsize und definieren Sie Bucketing-Optionen, um die Attribute nach Dokumentgröße zu erstellen.
Verwenden Sie createddatetimestamp, um die Attribute nach dem Erstellungsdatum des Dokuments zu kennzeichnen.
Verwenden Sie lastmodified, um die Attribute nach dem Änderungsdatum des Dokuments zu facettieren.

Attribut-Buckets interpretieren

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

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 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 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 des Nutzers sowie auf Kontakten und deren Dokumentenkorpus basieren.

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

Die resultierenden Vorschläge können dann entsprechend Ihrer Anwendung angezeigt werden.