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 Suche. oder das Einbetten von Suchergebnissen in einer Anwendung.

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 automatische Vorschläge.

Suchanwendung konfigurieren

Sie müssen mindestens eine Suchanwendung erstellen, die mit jeder verknüpft werden kann Suchoberfläche, die Sie erstellt haben. Eine Suchanwendung stellt die Standardeinstellungen Parameter für eine Abfrage, wie die zu verwendenden Datenquellen, die Sortierreihenfolge, Filter und Attribute, die angefordert werden sollen. Bei Bedarf können Sie diese Parameter mithilfe der Query API.

Weitere Informationen zu Suchanwendungen finden Sie unter Suche in Cloud Search anpassen

OAuth-Anmeldedaten für die Anwendung generieren

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

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

Index abfragen

Verwenden Sie den search. , um Suchvorgänge im Index durchzuführen.

Jeder Antrag muss zwei Informationen enthalten: query mit denen Artikel abgeglichen werden sollen, sowie ein searchApplicationId, das die ID für die zu verwendende Suchanwendung.

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

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

Abfrageergebnisse anzeigen

In Suchoberflächen wird mindestens das Element title so angezeigt: sowie einen Link zum ursprünglichen Element. Sie können die Darstellung von durch die Nutzung zusätzlicher Informationen in den Suchergebnissen etwa das Snippet und die Metadaten.

Zusätzliche Ergebnisse verarbeiten

Standardmäßig gibt Cloud Search zusätzliche Ergebnisse zurück, wenn unzureichende Ergebnisse für die Suchanfrage des Nutzers. Die queryInterpretation in der Antwort gibt an, wann zusätzliche Ergebnisse zurückgegeben werden. Wenn nur werden zusätzliche Ergebnisse zurückgegeben, InterpretationType ist auf REPLACE gesetzt. Wenn werden einige Ergebnisse für die ursprüngliche Abfrage und zusätzliche wird InterpretationType auf BLEND gesetzt. In beiden Fällen QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY

Wenn ergänzende Ergebnisse zurückgegeben werden, sollten Sie Text bereitstellen. um anzuzeigen, dass zusätzliche Ergebnisse zurückgegeben wurden. Handelt es sich beispielsweise um eine REPLACE angezeigt wird, können Sie Folgendes anzeigen: „Ihre Suche nach Ihrer ursprünglichen Suchanfrage hat stimmt mit keinem Ergebnis überein. Ergebnisse für ähnliche Suchanfragen werden angezeigt.“

Im Fall von BLEND können Sie beispielsweise den String „Ihre Suche nach Ihren Die ursprüngliche Suchanfrage entsprach nicht genügend Ergebnissen. Einschließlich Ergebnissen für ähnliche Suchanfragen.“

Personenergebnisse verarbeiten

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

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

Übereinstimmende Berichte

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

Bei Fragen zum Vorgesetzten oder zu direkt unterstellten Mitarbeitern einer Person enthält die Antwort einen assistCardProtoHolder innerhalb von structuredResults. Die assistCardProtoHolder hat ein Feld namens cardType, das gleich RELATED_PEOPLE_ANSWER_CARD assistCardProtoHolder enthält eine Karte mit dem Namen relatedPeopleAnswerCard, der die eigentliche Antwort enthält. Sie enthält die subject (die Person, die in der Abfrage enthalten war) und relatedPeople: die Gruppe von Personen, die mit dem Thema in Verbindung stehen. Die Das Feld relationType gibt den Wert MANAGER oder DIRECT_REPORTS zurück.

Der folgende Code zeigt eine Beispielantwort für einen Abgleich mit direkt unterstellten Mitarbeitern Suchanfrage:

{
  "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 können: Deaktivieren Sie jedoch alle Optimierungen oder nur ergänzende Ergebnisse Suchanwendungs- und Suchanfragenebene:

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

Snippets hervorheben

Bei zurückgegebenen Elementen mit indexiertem Text oder HTML-Inhalt wird ein Snippet des Inhalts zurückgegeben. Dieser Inhalt hilft den Nutzenden bei der Entscheidung, Relevanz des zurückgegebenen Artikels.

Wenn im Snippet Suchbegriffe vorhanden sind, werden in einem oder mehreren Übereinstimmungsbereichen die Position der Begriffe zurückgegeben.

Mit matchRanges den übereinstimmenden Text beim Rendern hervorheben die Ergebnisse. Im folgenden JavaScript-Beispiel wird das Snippet in HTML-Markup, bei dem 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

Verwenden Sie den metadata. , um zusätzliche Informationen zum zurückgegebenen Artikel anzuzeigen, die relevant sein könnten. für Nutzende zu machen. Das Feld metadata enthält createTime und updateTime des Artikels sowie alle zugehörigen strukturierten Daten für die Rückgabe mit dem Artikel.

Verwende zum Anzeigen der strukturierten Daten den displayOptions. ein. Das Feld displayOptions enthält die Anzeigebezeichnung für den Objekttyp und einen Satz von metalines. Jede Metazeile ist ein Array von Anzeigelabels und wie im Schema konfiguriert.

Zusätzliche Ergebnisse abrufen

Wenn Sie zusätzliche Ergebnisse abrufen möchten, legen Sie den start fest. in der Anfrage mit dem gewünschten Offset. Sie können die Größe jeder Seite mit dem pageSize ein.

Um die Anzahl der zurückgegebenen Elemente oder Seitensteuerelemente anzuzeigen, zurückgegebene Artikel blättern möchten, verwenden Sie resultCount ein. Je nach Größe der Ergebnismenge wird entweder der tatsächliche Wert oder wird ein geschätzter Wert angegeben.

Ergebnisse sortieren

Verwenden Sie den 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 der primären Gleichheit sortieren. .
sortOrder: Die Sortierrichtung, entweder ASCENDING oder DESCENDING.

Die Relevanz wird auch als sekundärer Sortierschlüssel verwendet. Wenn keine Sortierreihenfolge angegeben ist werden die Ergebnisse nur nach Relevanz sortiert.

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

Filter hinzufügen

Neben Abfrageausdrücken können Sie Ergebnisse weiter einschränken, indem Sie Filter. Sie können Filter sowohl im Suchanwendung und in der Suchanfrage.

Um in einer Anfrage oder Suchanwendung Filter hinzuzufügen, fügen Sie den Filter in der dataSourceRestrictions.filterOptions[]-Feld.

Es gibt zwei Möglichkeiten, Datenquellen weiter zu filtern:

Objektfilter über das Attribut filterOptions[].objectType – Einschränkungen Abgleich von Elementen mit dem angegebenen Typ, wie in einem benutzerdefinierten Schema definiert.
Wertefilter — schränkt übereinstimmende Elemente auf Basis einer Abfrageoperator und den angegebenen Wert.

Zusammengesetzte Filter ermöglichen es Ihnen, mehrere Wertfilter zu logischen Ausdrücken zu kombinieren, und komplexe Abfragen erstellen.

Im Beispiel für das Filmschema könnten Sie eine Altersbeschränkung anwenden, die auf den aktuellen Nutzer und schränken die verfügbaren Filme gemäß der MPAA-Altersfreigabe ein.

{
  "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 der Suche darstellen Ergebnisse. Mithilfe von Attributen können Nutzer Suchanfragen interaktiv verfeinern und schneller auf relevante Elemente zugreifen.

Facetten können in Ihrem Suchanwendung. und durch Einstellungen in Ihrer Abfrage überschrieben werden.

Beim Anfordern von Attributen berechnet Cloud Search die häufigsten Werte für die die angeforderten Eigenschaften unter den übereinstimmenden Elementen angezeigt. Diese werden in der Antwort zurückgegeben. Mit diesen Werten können Sie Filter erstellen mit denen die Ergebnisse bei nachfolgenden Suchanfragen eingegrenzt werden.

Das typische Interaktionsmuster mit Attributen sieht so aus:

Erstellen Sie eine erste Abfrage, die angibt, welche Attribute in das Attribut einbezogen werden sollen Ergebnisse.
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.

Um beispielsweise Filmanfragen nach Jahr und MPAA-Altersfreigabe zu verfeinern, Fügen Sie das Attribut facetOptions in die Abfrage ein.

"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. Zum Beispiel haben Sie kann ein ganzzahliges Attribut namens book_pages als anpassbar markieren, um Ergebnisse für eine Suche nach Büchern mit „100-200“ Seiten.

Legen Sie beim Einrichten des Schemas für das ganzzahlige Attributfeld fest: isFacetable true und fügen Sie entsprechende Bucketing-Optionen zum integerPropertyOptions Damit wird sichergestellt, dass für jedes Attribut, das ganzzahlig sein kann, das Standard-Bucketing verwendet wird. Optionen definiert.

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

Sie können ganzzahlbasierte Attribute überschreiben, indem Sie dieselben Bucketing-Optionen definieren, facetOptions in der Anfrage. Bei Bedarf verwendet Cloud Search die Bucketing-Optionen, die in Das Schema, wenn weder die Suchanwendung noch die Abfrageanfrage ein Attribut haben Optionen definiert. In der Abfrage definierte Attribute haben Vorrang vor definierten Attributen und die in der Suchanwendung definierten Facetten Vorrang gegenüber den im Schema definierten Attributen.

Sie können reservierte Operatoren um Suchergebnisse nach der Dateigröße des Dokuments, in Byte oder nach dem Zeitpunkt ein Dokument erstellt oder geändert wurde. Sie müssen kein benutzerdefiniertes Schema definieren, Sie müssen jedoch den Wert operatorName im Feld FacetOptions

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

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

Bei Attributen, die nicht auf Ganzzahlen basieren, enthält facetResults einen Eintrag für jede angeforderte Property. Für jede Eigenschaft eine Liste von Werten oder Bereichen, die buckets ist angegeben. 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 die ausgewählten Filter und fragen Sie die API noch einmal ab.

Vorschläge hinzufügen

Verwenden Sie die suggest API. , um Suchanfragen anhand der persönlichen Daten des Nutzers automatisch zu vervollständigen. Abfrageverlauf sowie Kontakte und deren Dokumentenkorpus.

Der folgende Aufruf gibt beispielsweise Vorschläge für die partielle Wortgruppe jo.

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

Anschließend können Sie die angezeigten Vorschläge .