Method: query.search

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 (RequestOptions)
  },
  "query": string,
  "pageSize": integer,
  "start": integer,
  "dataSourceRestrictions": [
    {
      object (DataSourceRestriction)
    }
  ],
  "facetOptions": [
    {
      object (FacetOptions)
    }
  ],
  "sortOptions": {
    object (SortOptions)
  },
  "queryInterpretationOptions": {
    object (QueryInterpretationOptions)
  },
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
Felder
requestOptions

object (RequestOptions)

Anfrageoptionen wie die Suchanwendung und die Zeitzone des Nutzers

query

string

Der Rohabfragestring. Unterstützte Suchoperatoren finden Sie unter Suche mit Operatoren eingrenzen

pageSize

integer

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

integer

Startindex der Ergebnisse.

dataSourceRestrictions[]

object (DataSourceRestriction)

Die Quellen, die für die Abfrage verwendet werden sollen. Wenn nicht angegeben, werden alle Datenquellen aus der aktuellen Suchanwendung verwendet.

facetOptions[]

object (FacetOptions)

sortOptions

object (SortOptions)

Optionen zum Sortieren der Suchergebnisse

queryInterpretationOptions

object (QueryInterpretationOptions)

Optionen zum Interpretieren der Nutzeranfrage.

contextAttributes[]

object (ContextAttribute)

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 (QueryInterpretation)
  },
  "results": [
    {
      object (SearchResult)
    }
  ],
  "structuredResults": [
    {
      object (StructuredResult)
    }
  ],
  "spellResults": [
    {
      object (SpellResult)
    }
  ],
  "facetResults": [
    {
      object (FacetResult)
    }
  ],
  "hasMoreResults": boolean,
  "debugInfo": {
    object (ResponseDebugInfo)
  },
  "errorInfo": {
    object (ErrorInfo)
  },
  "resultCounts": {
    object (ResultCounts)
  },

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Felder
queryInterpretation

object (QueryInterpretation)

Ergebnis der Abfrageinterpretation für die Nutzeranfrage. Leer, wenn die Abfrageinterpretation deaktiviert ist.

results[]

object (SearchResult)

Ergebnisse aus einer Suchanfrage.

structuredResults[]

object (StructuredResult)

Strukturierte Ergebnisse für die Nutzeranfrage. Diese Ergebnisse werden für die "pageSize" nicht berücksichtigt.

spellResults[]

object (SpellResult)

Vorgeschlagene Schreibweise für die Suchanfrage.

facetResults[]

object (FacetResult)

Wiederholte Attributergebnisse.

hasMoreResults

boolean

Gibt an, ob es mehr Suchergebnisse gibt, die der Suchanfrage entsprechen.

debugInfo

object (ResponseDebugInfo)

Informationen zur Fehlerbehebung zur Antwort.

errorInfo

object (ErrorInfo)

Fehlerinformationen zur Antwort.

resultCounts

object (ResultCounts)

Informationen zur Anzahl der Ergebnisse maximiert.

Union-Feld result_count. Die Gesamtzahl der Ergebnisse für alle angeforderten Datenquellen. Ausgelassen, wenn die abgefragten Datenquellen vordefinierte Quellen enthalten. Unter folgenden Umständen wird die Ergebnisanzahl möglicherweise als Schätzung zurückgegeben und nicht als exakte Anzahl:

  • Wenn die Suchanfrage mehr als zwei Begriffe in einer Wortgruppe enthält, z. B. „Ergebnisanzahl genau“ in Anführungszeichen.

  • Wenn die Anzahl der auszuwertenden eindeutigen Suchergebnis-ACLs zu groß für eine Berechnung innerhalb einer angemessenen Latenz ist.

In dem seltenen Fall, dass das System nicht alle Dokumente durchsuchen kann, führen Sie die Abfrage noch einmal aus. Für result_count ist nur einer der folgenden Werte zulässig:

resultCountEstimate

string (int64 format)

Die geschätzte Ergebnisanzahl für diese Abfrage.

resultCountExact

string (int64 format)

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

boolean

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

boolean

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

boolean

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 (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Felder
interpretedQuery

string

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

enum (QueryInterpretation.InterpretationType)

reason

enum (QueryInterpretation.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 (Snippet)
  },
  "metadata": {
    object (Metadata)
  },
  "clusteredResults": [
    {
      object (SearchResult)
    }
  ],
  "debugInfo": {
    object (ResultDebugInfo)
  }
}
Felder
title

string

Titel des Suchergebnisses.

url

string

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

object (Snippet)

Die Verkettung aller Snippets (Zusammenfassungen), die für dieses Ergebnis verfügbar sind.

metadata

object (Metadata)

Metadaten des Suchergebnisses.

clusteredResults[]

object (SearchResult)

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

object (ResultDebugInfo)

Debugging-Informationen zu diesem Suchergebnis.

Snippet

Snippet des Suchergebnisses, das den Inhalt der Ergebnisseite zusammenfasst.

JSON-Darstellung
{
  "snippet": string,
  "matchRanges": [
    {
      object (MatchRange)
    }
  ]
}
Felder
snippet

string

Das Snippet des Dokuments. Das Snippet des Dokuments. Kann HTML-Zeichen mit Escape-Zeichen enthalten, die vor dem Rendern nicht maskiert werden sollten.

matchRanges[]

object (MatchRange)

Die übereinstimmenden Bereiche im Snippet.

MatchRange

Übereinstimmender Bereich eines Snippets [Start, Ende).

JSON-Darstellung
{
  "start": integer,
  "end": integer
}
Felder
start

integer

Startposition der Übereinstimmung im Snippet

end

integer

Ende der Übereinstimmung im Snippet.

Metadaten

Metadaten eines übereinstimmenden Suchergebnisses.

JSON-Darstellung
{
  "source": {
    object (Source)
  },
  "mimeType": string,
  "thumbnailUrl": string,
  "owner": {
    object (Person)
  },
  "createTime": string,
  "updateTime": string,
  "fields": [
    {
      object (NamedProperty)
    }
  ],
  "displayOptions": {
    object (ResultDisplayMetadata)
  },
  "objectType": string
}
Felder
source

object (Source)

Die benannte Quelle des Ergebnisses, z. B. Gmail.

mimeType

string

MIME-Typ des Suchergebnisses.

thumbnailUrl

string

Die Miniaturansichts-URL des Ergebnisses.

owner

object (Person)

Eigentümer (normalerweise Ersteller) des Dokuments oder Objekts des Suchergebnisses.

createTime

string (Timestamp format)

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: "2014-10-02T15:01:23Z" und "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Das Datum der letzten Änderung des Objekts im Suchergebnis. Wird der Wert nicht im Element festgelegt, ist der hier zurückgegebene Wert leer. Wenn updateTime zur Berechnung der Aktualität verwendet wird und nicht festgelegt ist, wird standardmäßig ein Zeitraum von 2 Jahren ab der aktuellen Uhrzeit verwendet.

Ein Zeitstempel im Format RFC3339 UTC „Zulu“ mit Nanosekundenauflösung und bis zu neun Nachkommastellen. Beispiele: "2014-10-02T15:01:23Z" und "2014-10-02T15:01:23.045123456Z".

fields[]

object (NamedProperty)

Indexierte Felder in strukturierten Daten, die als generische benannte Property zurückgegeben werden.

displayOptions

object (ResultDisplayMetadata)

Optionen, mit denen festgelegt wird, wie ein Suchergebnis strukturierter Daten angezeigt werden soll.

objectType

string

Objekttyp des Suchergebnisses.

ResultDisplayMetadata

JSON-Darstellung
{
  "objectTypeLabel": string,
  "metalines": [
    {
      object (ResultDisplayMetadata.ResultDisplayLine)
    }
  ]
}
Felder
objectTypeLabel

string

Die Anzeigebezeichnung für das Objekt.

metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

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 (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Felder
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Felder für query.search-Ergebnisse anzeigen

JSON-Darstellung
{
  "label": string,
  "operatorName": string,
  "property": {
    object (NamedProperty)
  }
}
Felder
label

string

Die Anzeige für die Eigenschaft.

operatorName

string

Der Operatorname der Eigenschaft.

property

object (NamedProperty)

Das Name/Wert-Paar für die Eigenschaft.

ResultDebugInfo

Informationen zur Fehlerbehebung zum Ergebnis.

JSON-Darstellung
{
  "formattedDebugInfo": string
}
Felder
formattedDebugInfo

string

Allgemeine für die Anzeige formatierte Informationen zur Fehlerbehebung.

StructuredResult

Strukturierte Ergebnisse, die als Teil der Suchanfrage zurückgegeben werden.

JSON-Darstellung
{
  "person": {
    object (Person)
  }
}
Felder
person

object (Person)

Darstellung einer Person

SpellResult

JSON-Darstellung
{
  "suggestedQuery": string
}
Felder
suggestedQuery

string

Die vorgeschlagene Schreibweise der Abfrage.

FacetResult

Quellspezifische Attributantwort

JSON-Darstellung
{
  "sourceName": string,
  "objectType": string,
  "operatorName": string,
  "buckets": [
    {
      object (FacetBucket)
    }
  ]
}
Felder
sourceName

string

Name der Quelle, für die Attributergebnisse zurückgegeben werden. Der Wert ist nicht leer.

objectType

string

Objekttyp, für den Attributergebnisse zurückgegeben werden. Darf leer sein.

operatorName

string

Der Name des für die Facettierung ausgewählten Operators. @see cloudsearch.SchemaPropertyOptions

buckets[]

object (FacetBucket)

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 (Filter)
  },
  "value": {
    object (Value)
  }
}
Felder
count

integer

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

integer

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

object (Filter)

Filter, der an die Suchanfrage übergeben wird, wenn der entsprechende Bucket ausgewählt ist.

value

object (Value)

ResponseDebugInfo

Informationen zur Fehlerbehebung zur Antwort.

JSON-Darstellung
{
  "formattedDebugInfo": string
}
Felder
formattedDebugInfo

string

Allgemeine für die Anzeige formatierte Informationen zur Fehlerbehebung.

ErrorInfo

Fehlerinformationen zur Antwort.

JSON-Darstellung
{
  "errorMessages": [
    {
      object (ErrorMessage)
    }
  ]
}
Felder
errorMessages[]

object (ErrorMessage)

ErrorMessage

Fehlermeldung pro Quellantwort.

JSON-Darstellung
{
  "source": {
    object (Source)
  },
  "errorMessage": string
}
Felder
source

object (Source)

errorMessage

string

ResultCounts

Informationen zur Ergebnisanzahl

JSON-Darstellung
{
  "sourceResultCounts": [
    {
      object (SourceResultCount)
    }
  ]
}
Felder
sourceResultCounts[]

object (SourceResultCount)

Informationen zur Ergebnisanzahl für jede Quelle mit Ergebnissen.

SourceResultCount

Informationen zur Anzahl der Ergebnisse pro Quelle.

JSON-Darstellung
{
  "source": {
    object (Source)
  },
  "hasMoreResults": boolean,

  // Union field result_count can be only one of the following:
  "resultCountEstimate": string,
  "resultCountExact": string
  // End of list of possible types for union field result_count.
}
Felder
source

object (Source)

Die Quelle, der die Informationen zur Ergebniszahl zugeordnet sind.

hasMoreResults

boolean

Gibt an, ob es mehr Suchergebnisse für diese Quelle gibt.

Union-Feld result_count.

Für result_count ist nur einer der folgenden Werte zulässig:

resultCountEstimate

string (int64 format)

Die geschätzte Ergebnisanzahl für diese Quelle.

resultCountExact

string (int64 format)

Die genaue Ergebnisanzahl für diese Quelle.