Method: query.search

Die Cloud Search Query API bietet die Suchmethode, die die relevantesten Ergebnisse aus einer Nutzerabfrage zurückgibt. Die Ergebnisse können aus Google Workspace-Apps wie Gmail oder Google Drive stammen oder aus Daten, die Sie von einem Drittanbieter indexiert haben.

Hinweis:Für die Ausführung dieser API ist ein Standardendnutzerkonto erforderlich. Ein Dienstkonto kann keine Query API-Anfragen direkt ausführen. Wenn Sie ein Dienstkonto für Abfragen verwenden möchten, müssen Sie die domainweite Delegierung von Berechtigungen 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. Informationen zu unterstützten Suchoperatoren finden Sie unter Suche mit Operatoren eingrenzen.
pageSize

integer

Maximale Anzahl der Suchergebnisse, die auf einer Seite zurückgegeben werden sollen. Gültige Werte liegen zwischen 1 und 100. Der Standardwert ist 10. Der Mindestwert beträgt 50, wenn mehr als 2.000 Ergebnisse 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 zur Interpretation der Nutzerabfrage.
contextAttributes[]

object (ContextAttribute)

Kontextattribute für die Anfrage, die zum Anpassen des Rankings der Suchergebnisse verwendet werden. Die maximale Anzahl von Elementen ist 10.

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 Abfrageauswertung für die Nutzerabfrage. Leer, wenn die Abfrageauswertung deaktiviert ist.
results[]

object (SearchResult)

Ergebnisse einer Suchanfrage.
structuredResults[]

object (StructuredResult)

Strukturierte Ergebnisse für die Nutzerabfrage. Diese Ergebnisse werden nicht auf die pageSize angerechnet.
spellResults[]

object (SpellResult)

Vorgeschlagene Schreibweise für die Suchanfrage.
facetResults[]

object (FacetResult)

Wiederholte Attributergebnisse.
hasMoreResults

boolean

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

object (ResponseDebugInfo)

Informationen zur Fehlerbehebung bei der Antwort.
errorInfo

object (ErrorInfo)

Fehlerinformationen zur Antwort.
resultCounts

object (ResultCounts)

Maximierte Informationen zur Ergebnisanzahl.

Union-Feld result_count. Die Gesamtzahl der Ergebnisse aller angeforderten Datenquellen. Wird weggelassen, wenn vordefinierte Quellen in den abgefragten Datenquellen enthalten sind. In den folgenden Fällen werden die Ergebnisse möglicherweise als Schätzung statt als genaue Anzahl zurückgegeben:

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

  • Wenn die Anzahl der zu bewertenden eindeutigen ACLs für Suchergebnisse zu groß ist, um sie innerhalb einer angemessenen Latenz zu berechnen.

Sollte das System in seltenen Fällen nicht alle Dokumente durchsuchen können, 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 Anzahl der Ergebnisse für diese Abfrage.
resultCountExact

string (int64 format)

Die genaue Anzahl der Ergebnisse 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 zur Interpretation der Nutzerabfrage.

JSON-Darstellung 
{
  "disableNlInterpretation": boolean,
  "enableVerbatimMode": boolean,
  "disableSupplementalResults": boolean
}
Felder
disableNlInterpretation

boolean

Mit diesem Flag wird die Interpretation von Abfragen in natürlicher Sprache deaktiviert. Standardmäßig ist „false“ festgelegt. Legen Sie „true“ fest, um die Interpretation natürlicher Sprache zu deaktivieren. Die NL-Interpretation gilt nur für vordefinierte Datenquellen.
enableVerbatimMode

boolean

Wenn Sie dieses Flag aktivieren, werden alle internen Optimierungen deaktiviert, z. B. die Interpretation von Suchanfragen in natürlicher Sprache, die Abfrage ergänzender Ergebnisse und die Verwendung von Synonyme, einschließlich benutzerdefinierter Synonyme. Die Nl-Interpretation wird deaktiviert, wenn eine der beiden Flags wahr ist.
disableSupplementalResults

boolean

Mit diesem Flag können Sie ergänzende Ergebnisse für eine Suchanfrage deaktivieren. Die Einstellung für ergänzende Ergebnisse, die auf Ebene der Suchanwendung ausgewählt wurde, hat Vorrang, wenn sie auf „Wahr“ gesetzt ist.

QueryInterpretation

JSON-Darstellung 
{
  "interpretedQuery": string,
  "interpretationType": enum (QueryInterpretation.InterpretationType),
  "reason": enum (QueryInterpretation.Reason)
}
Felder
interpretedQuery

string

Die Interpretation der Suchanfrage. Suchanfragen mit natürlicher Sprache wie „E-Mail von Max“ werden beispielsweise als „from:max source:mail“ interpretiert. Dieses Feld wird nicht ausgefüllt, wenn der Grund NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY ist.
interpretationType

enum (QueryInterpretation.InterpretationType)
reason

enum (QueryInterpretation.Reason)

Der Grund für die Interpretation der Anfrage. Dieses Feld hat nicht den Wert „UNBESCHRIEBEN“, wenn der Interpretationstyp nicht „NONE“ ist.

QueryInterpretation.InterpretationType

Enums
NONE Weder die Interpretation in natürlicher Sprache noch eine allgemeinere Version der Suchanfrage werden verwendet, um die Suchergebnisse abzurufen.
BLEND Die Ergebnisse der ursprünglichen Abfrage werden mit anderen Ergebnissen kombiniert. Der Grund für die Zusammenführung dieser anderen Ergebnisse mit den Ergebnissen der ursprünglichen Abfrage wird unten im Feld „Grund“ angegeben.
REPLACE Die Ergebnisse der ursprünglichen Abfrage werden ersetzt. Der Grund für das Ersetzen der Ergebnisse aus der ursprünglichen Abfrage wird unten im Feld „Grund“ angegeben.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Die Suchergebnisse werden anhand der Interpretation der Suchanfrage in natürlicher Sprache abgerufen.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Die Ähnlichkeit von Suchanfrage und Dokumentbegriffen wird verwendet, um die Suchanfrage selektiv zu erweitern und so zusätzliche Suchergebnisse abzurufen, da für die Suchanfrage des Nutzers 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 tatsächlichen Artikel. Diese URL ist signiert und sollte nicht geändert werden.
snippet

object (Snippet)

Die Konkatenierung 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 gibt nur eine Ebene mit geclusterten Ergebnissen. Wenn die aktuelle Quelle nicht für das Clustern aktiviert ist, ist dieses Feld leer.
debugInfo

object (ResultDebugInfo)

Informationen zur Fehlerbehebung für dieses Suchergebnis.

Snippet

Snippet des Suchergebnisses, in dem der Inhalt der Ergebnisseite zusammengefasst wird.

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

string

Das Snippet des Dokuments. Das Snippet des Dokuments. Kann maskierte HTML-Zeichen enthalten, die vor dem Rendern entkommentiert werden müssen.
matchRanges[]

object (MatchRange)

Die übereinstimmenden Bereiche im Snippet.

MatchRange

Übereinstimmender Bereich eines Snippets [start, end].

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 für das Ergebnis, z. B. Gmail.
mimeType

string

MIME-Typ des Suchergebnisses.
thumbnailUrl

string

Die Thumbnail-URL des Ergebnisses.
owner

object (Person)

Eigentümer (in der Regel Ersteller) des Dokuments oder Objekts des Suchergebnisses.
createTime

string (Timestamp format)

Der Erstellungszeitpunkt dieses Dokuments oder Objekts im Suchergebnis.

Ein Zeitstempel im Format RFC3339 UTC "Zulu" mit einer Auflösung im Nanosekundenbereich 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. Wenn der Wert im Artikel nicht festgelegt ist, ist der hier zurückgegebene Wert leer. Wenn updateTime für die Berechnung der Aktualität verwendet wird und nicht festgelegt ist, wird standardmäßig der Wert „2 Jahre nach der aktuellen Zeit“ verwendet.

Ein Zeitstempel im Format RFC3339 UTC "Zulu" mit einer Auflösung im Nanosekundenbereich 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, die festlegen, wie ein Suchergebnis mit strukturierten Daten angezeigt wird.
objectType

string

Der Objekttyp des Suchergebnisses.

ResultDisplayMetadata

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

string

Das Anzeigelabel für das Objekt.
metalines[]

object (ResultDisplayMetadata.ResultDisplayLine)

Der Inhalt der Metazeilen, der mit dem Ergebnis angezeigt werden soll.

ResultDisplayMetadata.ResultDisplayLine

Die Sammlung von Feldern, aus denen eine angezeigte Zeile besteht

JSON-Darstellung 
{
  "fields": [
    {
      object (ResultDisplayMetadata.ResultDisplayField)
    }
  ]
}
Felder
fields[]

object (ResultDisplayMetadata.ResultDisplayField)

ResultDisplayMetadata.ResultDisplayField

Anzeigefelder für query.search-Ergebnisse

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

string

Das Anzeigelabel für die Property.
operatorName

string

Der Name des Betreibers der Unterkunft.
property

object (NamedProperty)

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

ResultDebugInfo

Informationen zur Fehlerbehebung beim Ergebnis.

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

string

Allgemeine Informationen zur Fehlerbehebung, die für die Anzeige formatiert sind.

StructuredResult

Strukturierte Ergebnisse, die im Rahmen einer 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 Suchanfrage.

FacetResult

Quellspezifische Antwort für Facetten

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

string

Name der Quelle, für die die Ergebnisse zurückgegeben werden. Dieses Feld darf nicht leer sein.
objectType

string

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

string

Der Name des Operators, der für die Facetten ausgewählt wurde. @see cloudsearch.SchemaPropertyOptions
buckets[]

object (FacetBucket)

FacetBuckets für Werte in der Antwort, die mindestens ein Ergebnis mit dem entsprechenden Filter enthalten.

FacetBucket

Ein Bucket in einer Facette ist die grundlegende Einheit. Ein Bucket kann je nach Feldtyp entweder einen einzelnen Wert ODER einen zusammenhängenden Wertebereich enthalten. FacetBucket wird derzeit nur zum Zurückgeben des Antwortobjekts verwendet.

JSON-Darstellung 
{
  "count": integer,
  "percentage": integer,
  "filter": {
    object (Filter)
  },
  "value": {
    object (Value)
  }
}
Felder
count

integer

Anzahl der Ergebnisse, die mit dem Bucket-Wert übereinstimmen. Die Anzahl der Ergebnisse wird nur für Suchanfragen zurückgegeben, wenn die Genauigkeit der Anzahl gewährleistet ist. Cloud Search kann die Anzahl der Facetten für keine Abfrage garantieren. Die Anzahl der Facetten ist möglicherweise nur sporadisch verfügbar, auch bei identischen Abfragen. Legen Sie keine Abhängigkeiten von der Existenz der Facettenanzahl fest. Verwenden Sie stattdessen Prozentsätze für die Facettenanzahl, die immer zurückgegeben werden.
percentage

integer

Prozentsatz der Ergebnisse, die mit dem Bucket-Wert übereinstimmen. Der Rückgabewert liegt zwischen 0 und 100 und wird bei Dezimalwerten auf eine Ganzzahl abgerundet. Wenn der Wert nicht explizit zurückgegeben wird, entspricht er einem Prozentsatz, der auf 0 gerundet wird. Prozentsätze werden für alle Suchanfragen zurückgegeben, sind aber nur eine Schätzung. Da immer Prozentsätze zurückgegeben werden, sollten Sie Prozentsätze anstelle von Stückzahlen verwenden.
filter

object (Filter)

Filter, der in der Suchanfrage übergeben wird, wenn der entsprechende Bucket ausgewählt ist.
value

object (Value)

ResponseDebugInfo

Informationen zur Fehlerbehebung bei der Antwort.

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

string

Allgemeine Informationen zur Fehlerbehebung, die für die Anzeige formatiert sind.

Fehlerinformation

Fehlerinformationen zur Antwort.

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

object (ErrorMessage)

ErrorMessage

Fehlermeldung pro Antwort der Quelle.

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 Ergebnisanzahl zugeordnet sind.
hasMoreResults

boolean

Gibt an, ob es weitere 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 Anzahl der Ergebnisse für diese Quelle.
resultCountExact

string (int64 format)

Die genaue Anzahl der Ergebnisse für diese Quelle.