- HTTP-Anfrage
- Anfragetext
- Antworttext
- Autorisierungsbereiche
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- Snippet
- MatchRange
- Metadaten
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine.
- ResultDisplayMetadata.ResultDisplayField.
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts (Anzahl der Ergebnisse)
- SourceResultCount
- Testen!
Die Cloud Search Query API stellt die Suchmethode bereit, die die relevantesten Ergebnisse einer Nutzeranfrage zurückgibt. Die Ergebnisse können aus Google Workspace-Apps wie Gmail oder Google Drive oder aus Daten stammen, die Sie von einem Drittanbieter indexiert haben.
Hinweis:Für die Ausführung dieser API ist ein Standard-Endnutzerkonto erforderlich. Ein Dienstkonto kann Query API-Anfragen nicht direkt ausführen. Wenn Sie über ein Dienstkonto Abfragen ausführen möchten, müssen Sie die domainweite Delegierung von Befugnissen in Google Workspace einrichten.
HTTP-Anfrage
POST https://cloudsearch.googleapis.com/v1/query/search
Die URL verwendet die Syntax der gRPC-Transcodierung.
Anfragetext
Der Anfragetext enthält Daten mit folgender Struktur:
JSON-Darstellung |
---|
{ "requestOptions": { object ( |
Felder | |
---|---|
requestOptions |
Anfrageoptionen wie die Suchanwendung und die Zeitzone des Nutzers |
query |
Der Rohabfragestring. Unterstützte Suchoperatoren finden Sie unter Suche mit Operatoren eingrenzen |
pageSize |
Maximale Anzahl von Suchergebnissen, die auf einer Seite zurückgegeben werden sollen. Gültige Werte liegen zwischen 1 und 100 (einschließlich). Der Standardwert ist 10. Der Mindestwert ist 50, wenn Ergebnisse über 2.000 angefordert werden. |
start |
Startindex der Ergebnisse. |
dataSourceRestrictions[] |
Die Quellen, die für die Abfrage verwendet werden sollen. Wenn nicht angegeben, werden alle Datenquellen aus der aktuellen Suchanwendung verwendet. |
facetOptions[] |
|
sortOptions |
Optionen zum Sortieren der Suchergebnisse |
queryInterpretationOptions |
Optionen zum Interpretieren der Nutzeranfrage. |
contextAttributes[] |
Kontextattribute für die Anfrage, die verwendet werden, um das Ranking der Suchergebnisse anzupassen. Es sind maximal 10 Elemente zulässig. |
Antworttext
Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:
Die Antwort der Search API.
JSON-Darstellung |
---|
{ "queryInterpretation": { object ( |
Felder | |
---|---|
queryInterpretation |
Ergebnis der Abfrageinterpretation für die Nutzeranfrage. Leer, wenn die Abfrageinterpretation deaktiviert ist. |
results[] |
Ergebnisse aus einer Suchanfrage. |
structuredResults[] |
Strukturierte Ergebnisse für die Nutzeranfrage. Diese Ergebnisse werden für die "pageSize" nicht berücksichtigt. |
spellResults[] |
Vorgeschlagene Schreibweise für die Suchanfrage. |
facetResults[] |
Wiederholte Attributergebnisse. |
hasMoreResults |
Gibt an, ob es mehr Suchergebnisse gibt, die der Suchanfrage entsprechen. |
debugInfo |
Informationen zur Fehlerbehebung zur Antwort. |
errorInfo |
Fehlerinformationen zur Antwort. |
resultCounts |
Informationen zur Anzahl der Ergebnisse maximiert. |
Union-Feld
In dem seltenen Fall, dass das System nicht alle Dokumente durchsuchen kann, führen Sie die Abfrage noch einmal aus. Für |
|
resultCountEstimate |
Die geschätzte Ergebnisanzahl für diese Abfrage. |
resultCountExact |
Die genaue Ergebnisanzahl für diese Abfrage. |
Autorisierungsbereiche
Erfordert einen der folgenden OAuth-Bereiche:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
Weitere Informationen finden Sie im Leitfaden zur Autorisierung.
QueryInterpretationOptions
Optionen zum Interpretieren der Nutzeranfrage.
JSON-Darstellung |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
Felder | |
---|---|
disableNlInterpretation |
Flag zum Deaktivieren der Interpretation in natürlicher Sprache (NL) von Abfragen. Der Standardwert ist „false“. Setzen Sie ihn auf „true“, um die Interpretation natürlicher Sprache zu deaktivieren. Die Interpretation für die Niederlande gilt nur für vordefinierte Datenquellen. |
enableVerbatimMode |
Aktivieren Sie dieses Flag, um alle internen Optimierungen wie die Interpretation von Anfragen in natürlicher Sprache (NL), das Abrufen zusätzlicher Ergebnisse und die Verwendung von Synonymen, einschließlich benutzerdefinierter, zu deaktivieren. Die NL-Interpretation wird deaktiviert, wenn eines der beiden Flags wahr ist. |
disableSupplementalResults |
Verwenden Sie dieses Flag, um zusätzliche Ergebnisse für eine Abfrage zu deaktivieren. Die auf SearchApplication-Ebene ausgewählte Einstellung für zusätzliche Ergebnisse hat Vorrang, wenn sie auf „True“ gesetzt ist. |
QueryInterpretation
JSON-Darstellung |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
Felder | |
---|---|
interpretedQuery |
Die Interpretation der in der Suche verwendeten Abfrage. Abfragen mit natürlicher Sprache wie "email from john" werden als "from:john source:mail" interpretiert. Dieses Feld wird nicht ausgefüllt, wenn der Grund NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY lautet. |
interpretationType |
|
reason |
Der Grund für die Interpretation der Abfrage. Dieses Feld ist nicht UNSPECIFIED, wenn der Interpretationstyp nicht NONE lautet. |
QueryInterpretation.InterpretationType
Enums | |
---|---|
NONE |
Zum Abrufen der Suchergebnisse werden weder die natürliche Sprachinterpretation noch eine breiter gefasste Version der Suchanfrage verwendet. |
BLEND |
Die Ergebnisse der ursprünglichen Suchanfrage werden mit anderen Ergebnissen zusammengeführt. Der Grund für die Zusammenführung dieser anderen Ergebnisse mit den Ergebnissen der ursprünglichen Suchanfrage wird im Feld „Grund“ unten angegeben. |
REPLACE |
Die Ergebnisse der ursprünglichen Abfrage werden ersetzt. Der Grund für das Ersetzen der Ergebnisse der ursprünglichen Abfrage wird im Feld „Grund“ unten angegeben. |
QueryInterpretation.Reason
Enums | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
Zum Abrufen der Suchergebnisse wird die natürliche Sprachinterpretation der Anfrage verwendet. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
Die Ähnlichkeit von Suchbegriffen und Dokumentbegriffen wird verwendet, um die Suchanfrage selektiv zu erweitern, um zusätzliche Suchergebnisse abzurufen, da für die Suchanfrage nicht genügend Ergebnisse gefunden wurden. Die interpretierte Abfrage ist in diesem Fall leer. |
SearchResult
Ergebnisse mit indexierten Informationen für ein Dokument.
JSON-Darstellung |
---|
{ "title": string, "url": string, "snippet": { object ( |
Felder | |
---|---|
title |
Titel des Suchergebnisses. |
url |
Die URL des Suchergebnisses. Die URL enthält eine Google-Weiterleitung zum eigentlichen Artikel. Diese URL ist signiert und darf nicht geändert werden. |
snippet |
Die Verkettung aller Snippets (Zusammenfassungen), die für dieses Ergebnis verfügbar sind. |
metadata |
Metadaten des Suchergebnisses. |
clusteredResults[] |
Wenn die Quelle geclustert ist, geben Sie eine Liste der geclusterten Ergebnisse an. Es wird nur eine Ebene von gruppierten Ergebnissen geben. Wenn die aktuelle Quelle nicht für das Clustering aktiviert ist, ist dieses Feld leer. |
debugInfo |
Debugging-Informationen zu diesem Suchergebnis. |
Snippet
Snippet des Suchergebnisses, das den Inhalt der Ergebnisseite zusammenfasst.
JSON-Darstellung |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
Felder | |
---|---|
snippet |
Das Snippet des Dokuments. Das Snippet des Dokuments. Kann HTML-Zeichen mit Escape-Zeichen enthalten, die vor dem Rendern nicht maskiert werden sollten. |
matchRanges[] |
Die übereinstimmenden Bereiche im Snippet. |
MatchRange
Übereinstimmender Bereich eines Snippets [Start, Ende).
JSON-Darstellung |
---|
{ "start": integer, "end": integer } |
Felder | |
---|---|
start |
Startposition der Übereinstimmung im Snippet |
end |
Ende der Übereinstimmung im Snippet. |
Metadaten
Metadaten eines übereinstimmenden Suchergebnisses.
JSON-Darstellung |
---|
{ "source": { object ( |
Felder | |
---|---|
source |
Die benannte Quelle des Ergebnisses, z. B. Gmail. |
mimeType |
MIME-Typ des Suchergebnisses. |
thumbnailUrl |
Die Miniaturansichts-URL des Ergebnisses. |
owner |
Eigentümer (normalerweise Ersteller) des Dokuments oder Objekts des Suchergebnisses. |
createTime |
Die Erstellungszeit für dieses Dokument oder Objekt im Suchergebnis. Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: |
updateTime |
Das Datum der letzten Änderung des Objekts im Suchergebnis. Wird der Wert nicht im Element festgelegt, ist der hier zurückgegebene Wert leer. Wenn Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: |
fields[] |
Indexierte Felder in strukturierten Daten, die als generische benannte Property zurückgegeben werden. |
displayOptions |
Optionen, mit denen festgelegt wird, wie ein Suchergebnis strukturierter Daten angezeigt werden soll. |
objectType |
Objekttyp des Suchergebnisses. |
ResultDisplayMetadata
JSON-Darstellung |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
Felder | |
---|---|
objectTypeLabel |
Die Anzeigebezeichnung für das Objekt. |
metalines[] |
Der Inhalt der Metazeilen, der mit dem Ergebnis angezeigt werden soll. |
ResultDisplayMetadata.ResultDisplayLine
Die Felder, aus denen eine angezeigte Linie besteht
JSON-Darstellung |
---|
{
"fields": [
{
object ( |
Felder | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
Felder für query.search-Ergebnisse anzeigen
JSON-Darstellung |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
Felder | |
---|---|
label |
Die Anzeige für die Eigenschaft. |
operatorName |
Der Operatorname der Eigenschaft. |
property |
Das Name/Wert-Paar für die Eigenschaft. |
ResultDebugInfo
Informationen zur Fehlerbehebung zum Ergebnis.
JSON-Darstellung |
---|
{ "formattedDebugInfo": string } |
Felder | |
---|---|
formattedDebugInfo |
Allgemeine für die Anzeige formatierte Informationen zur Fehlerbehebung. |
StructuredResult
Strukturierte Ergebnisse, die als Teil der Suchanfrage zurückgegeben werden.
JSON-Darstellung |
---|
{
"person": {
object ( |
Felder | |
---|---|
person |
Darstellung einer Person |
SpellResult
JSON-Darstellung |
---|
{ "suggestedQuery": string } |
Felder | |
---|---|
suggestedQuery |
Die vorgeschlagene Schreibweise der Abfrage. |
FacetResult
Quellspezifische Attributantwort
JSON-Darstellung |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
Felder | |
---|---|
sourceName |
Name der Quelle, für die Attributergebnisse zurückgegeben werden. Der Wert ist nicht leer. |
objectType |
Objekttyp, für den Attributergebnisse zurückgegeben werden. Darf leer sein. |
operatorName |
Der Name des für die Facettierung ausgewählten Operators. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
FacetBuckets für Werte in einer Antwort, die mindestens ein einzelnes Ergebnis mit dem entsprechenden Filter enthält. |
FacetBucket
Ein Bucket in einem Attribut ist die grundlegende Vorgangseinheit. Ein Bucket kann entweder einen einzelnen Wert ODER einen zusammenhängenden Wertebereich enthalten, je nach Typ des zusammengefassten Felds. FacetBucket wird derzeit nur für die Rückgabe des Antwortobjekts verwendet.
JSON-Darstellung |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
Felder | |
---|---|
count |
Anzahl der Ergebnisse, die dem Bucket-Wert entsprechen. Zählungen werden nur für Suchvorgänge zurückgegeben, wenn die Zählungsgenauigkeit sichergestellt ist. Cloud Search garantiert keine Attributanzahl für Abfragen. Die Attributanzahl kann selbst bei identischen Abfragen nur zeitweise vorliegen. Erstellen Sie keine Abhängigkeiten vom Vorhandensein der Attributanzahl. Verwenden Sie stattdessen Prozentsätze der Attributanzahl, die immer zurückgegeben werden. |
percentage |
Prozentsatz der Ergebnisse, die dem Bucket-Wert entsprechen. Der zurückgegebene Wert liegt zwischen 0 und 100 und wird auf eine ganze Zahl abgerundet, falls eine Bruchzahl ist. Wenn der Wert nicht explizit zurückgegeben wird, stellt er einen Prozentwert dar, der auf 0 rundet. Für alle Suchanfragen werden Prozentwerte zurückgegeben, allerdings handelt es sich dabei um eine Schätzung. Da Prozentsätze immer zurückgegeben werden, sollten Sie Prozentsätze statt Anzahlen rendern. |
filter |
Filter, der an die Suchanfrage übergeben wird, wenn der entsprechende Bucket ausgewählt ist. |
value |
|
ResponseDebugInfo
Informationen zur Fehlerbehebung zur Antwort.
JSON-Darstellung |
---|
{ "formattedDebugInfo": string } |
Felder | |
---|---|
formattedDebugInfo |
Allgemeine für die Anzeige formatierte Informationen zur Fehlerbehebung. |
ErrorInfo
Fehlerinformationen zur Antwort.
JSON-Darstellung |
---|
{
"errorMessages": [
{
object ( |
Felder | |
---|---|
errorMessages[] |
|
ErrorMessage
Fehlermeldung pro Quellantwort.
JSON-Darstellung |
---|
{
"source": {
object ( |
Felder | |
---|---|
source |
|
errorMessage |
|
ResultCounts
Informationen zur Ergebnisanzahl
JSON-Darstellung |
---|
{
"sourceResultCounts": [
{
object ( |
Felder | |
---|---|
sourceResultCounts[] |
Informationen zur Ergebnisanzahl für jede Quelle mit Ergebnissen. |
SourceResultCount
Informationen zur Anzahl der Ergebnisse pro Quelle.
JSON-Darstellung |
---|
{ "source": { object ( |
Felder | |
---|---|
source |
Die Quelle, der die Informationen zur Ergebniszahl zugeordnet sind. |
hasMoreResults |
Gibt an, ob es mehr Suchergebnisse für diese Quelle gibt. |
Union-Feld Für |
|
resultCountEstimate |
Die geschätzte Ergebnisanzahl für diese Quelle. |
resultCountExact |
Die genaue Ergebnisanzahl für diese Quelle. |