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 auftrue
.Um alle Optimierungen auf Suchanfragenebene zu deaktivieren, einschließlich zusätzliche Ergebnisse, Synonyme und Rechtschreibkorrekturen,
QueryInterpretationOptions.enableVerbatimMode
antrue
in der Suchanfrage.Um zusätzliche Ergebnisse auf Suchanwendungsebene zu deaktivieren, legen Sie
QueryInterpretationOptions.forceDisableSupplementalResults
antrue
in der Suchanfrage.Um zusätzliche Ergebnisse auf Suchanfragenebene zu deaktivieren,
QueryInterpretationOptions.disableSupplementalResults
antrue
in der Suchanfrage.
Snippets hervorheben
Bei zurückgegebenen Elementen mit indexiertem Text oder HTML-Inhalt wird ein Snippet des Inhalts zurückgegeben. Anhand dieses Inhalts können die Nutzenden feststellen, 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
Zum Abrufen weiterer Ergebnisse 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, entwederASCENDING
oderDESCENDING
.
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, der in einem benutzerdefinierten Schema definiert ist. - 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"
}
]
Attributergebnisse mit auf Ganzzahlen basierenden Feldern
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 die
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.
Attributergebnisse nach Dokumentgröße oder Datum
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 .