Method: query.search

Die Cloud Search Query API stellt die Suchmethode bereit, mit der die relevantesten Ergebnisse einer Nutzeranfrage zurückgegeben werden. 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:Zum Ausführen dieser API ist ein standardmäßiges Endnutzerkonto erforderlich. Ein Dienstkonto kann Query API-Anfragen nicht direkt ausführen. Wenn Sie ein Dienstkonto für Abfragen verwenden möchten, richten Sie die domainweite Delegierung von Befugnissen in Google Workspace ein.

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 im Artikel 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 (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 der aktuellen Suchanwendung verwendet.
facetOptions[]

object (FacetOptions)
sortOptions

object (SortOptions)

Die Optionen zum Sortieren der Suchergebnisse
queryInterpretationOptions

object (QueryInterpretationOptions)

zur Interpretation der Nutzeranfrage.
contextAttributes[]

object (ContextAttribute)

Kontextattribute für die Anfrage, die zum Anpassen der Rangfolge der Suchergebnisse verwendet werden. Es sind maximal 10 Elemente zulässig.

Antworttext

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

Die Search API-Antwort.

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)

Interpretationsergebnis der Abfrage für 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 nicht auf „pageSize“ angerechnet.
spellResults[]

object (SpellResult)

Vorgeschlagene Schreibweise für die Abfrage.
facetResults[]

object (FacetResult)

Wiederholte Attributergebnisse.
hasMoreResults

boolean

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

object (ResponseDebugInfo)

Debugging-Informationen zur Antwort
errorInfo

object (ErrorInfo)

Fehlerinformationen zur Antwort.
resultCounts

object (ResultCounts)

Erweiterte Informationen zur Ergebnisanzahl.

Union-Feld result_count. Die Gesamtzahl der Ergebnisse für alle angeforderten Datenquellen. Wird ausgelassen, wenn vordefinierte Quellen in den abgefragten Datenquellen enthalten sind. In den folgenden Fällen wird die Ergebnisanzahl möglicherweise als Schätzung statt als exakt zurückgegeben:

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

  • Wenn die Anzahl der auszuwertenden eindeutigen Suchergebnis-ACLs zu groß ist, um sie innerhalb einer angemessenen Latenz zu berechnen.

Im 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 Anzahl der Ergebnisse 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 von Abfragen in natürlicher Sprache (NL). Der Standardwert ist „false“. Wenn Sie ihn auf „true“ setzen, wird die Interpretation natürlicher Sprache deaktiviert. Die NL-Interpretation gilt nur für vordefinierte Datenquellen.
enableVerbatimMode

boolean

Aktivieren Sie dieses Flag, um alle internen Optimierungen zu deaktivieren, z. B. die Interpretation von Suchanfragen in natürlicher Sprache (NL), das zusätzliche Abrufen von Ergebnissen und die Verwendung von Synonymen, einschließlich benutzerdefinierter. 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 Suchanfrage. Beispielsweise werden Suchanfragen in natürlicher Sprache wie „E-Mail von Johannes“ gestellt. als „from:john 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 Abfrage. Dieses Feld ist nicht UNSPECIFIED, wenn der Interpretationstyp nicht NONE lautet.

QueryInterpretation.InterpretationType

Enums
NONE Zum Abrufen der Suchergebnisse wird weder die Interpretation natürlicher Sprache noch eine umfassendere Version der Abfrage verwendet.
BLEND Die Ergebnisse der ursprünglichen Abfrage werden mit anderen Ergebnissen zusammengeführt. Der Grund für das Zusammenführen dieser anderen Ergebnisse mit den Ergebnissen der ursprünglichen Suchanfrage wird im Feld „Grund“ angegeben. unten ein.
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“ angegeben. unten ein.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Zum Abrufen der Suchergebnisse wird die Abfrage in natürlicher Sprache interpretiert.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Mit der Ähnlichkeit von Suchbegriffen und Dokumenten wird die Suchanfrage selektiv erweitert, um zusätzliche Suchergebnisse abzurufen, da nicht genügend Ergebnisse für die Nutzeranfrage gefunden wurden. Die interpretierte Abfrage ist für diesen Fall leer.

SearchResult

Ergebnisse mit indexierten Informationen zu einem 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 sollte 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, stellen Sie eine Liste der geclusterten Ergebnisse bereit. Es gibt nur eine Ebene von geclusterten Ergebnissen. Wenn die aktuelle Quelle nicht für Clustering aktiviert ist, ist dieses Feld leer.
debugInfo

object (ResultDebugInfo)

Informationen zu diesem Suchergebnis werden korrigiert.

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 ein maskiertes HTML-Zeichen enthalten, das vor dem Rendern nicht maskiert werden muss.
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 für das Ergebnis, z. B. Gmail.
mimeType

string

MIME-Typ des Suchergebnisses.
thumbnailUrl

string

Die Miniaturansicht-URL des Ergebnisses.
owner

object (Person)

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

string (Timestamp format)

Der Erstellungszeitpunkt für dieses Dokument oder Objekt 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 für das Objekt im Suchergebnis. Wenn nicht im Element festgelegt, ist der hier zurückgegebene Wert leer. Wenn updateTime zur Berechnung der Aktualität verwendet und nicht festgelegt ist, wird dieser Wert standardmäßig auf 2 Jahre ab der aktuellen Uhrzeit festgelegt.

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, zurückgegeben als generisches benanntes Attribut.
displayOptions

object (ResultDisplayMetadata)

Optionen zum Angeben, wie ein Suchergebnis mit strukturierten 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 Sammlung der Felder, aus denen eine angezeigte Zeile 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 Anzeigebezeichnung der Unterkunft.
operatorName

string

Der Operatorname der Eigenschaft.
property

object (NamedProperty)

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

ResultDebugInfo

Informationen zum Ergebnis debuggen.

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

string

Zur Anzeige formatierte allgemeine Informationen zur Fehlerbehebung.

StructuredResult

Strukturierte Ergebnisse, die im Rahmen 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. Das Feld ist nicht leer.
objectType

string

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

string

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

object (FacetBucket)

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

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 gruppierten Felds. 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 dem Bucket-Wert entsprechen. Zählungen werden nur für Suchanfragen zurückgegeben, wenn die Genauigkeit der Zählung sichergestellt ist. Cloud Search garantiert nicht, dass Attribute für Abfragen vorhanden sind und dass die Attributanzahl auch bei identischen Abfragen möglicherweise nur zeitweise vorhanden ist. Erstellen Sie keine Abhängigkeiten von der Existenz der Attributanzahl. verwenden Sie stattdessen Facettenprozentsätze, die immer zurückgegeben werden.
percentage

integer

Prozentsatz der Ergebnisse, die dem Bucket-Wert entsprechen. Der zurückgegebene Wert liegt zwischen (0-100] und wird, falls zutreffend, auf eine Ganzzahl abgerundet. Wenn der Wert nicht explizit zurückgegeben wird, stellt er einen Prozentwert dar, der auf 0 rundet. Prozentsätze werden für alle Suchanfragen zurückgegeben, sind aber eine Schätzung. Da Prozentsätze immer zurückgegeben werden, sollten Sie Prozentsätze anstelle von Anzahlen rendern.
filter

object (Filter)

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

object (Value)

ResponseDebugInfo

Debugging-Informationen zur Antwort

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

string

Zur Anzeige formatierte allgemeine Informationen zur Fehlerbehebung.

Fehlerinformation

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 Ergebnisanzahl 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 Anzahl der Ergebnisse für diese Quelle.
resultCountExact

string (int64 format)

Die genaue Ergebnisanzahl für diese Quelle.