Method: query.search

Die Cloud Search Query API bietet die Methode „search“, die die relevantesten Ergebnisse einer Nutzeranfrage 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 diese API ist ein Standard-Endnutzerkonto erforderlich. Mit einem Dienstkonto können keine Query API-Anfragen direkt ausgeführt werden. Wenn Sie ein Dienstkonto für Abfragen verwenden möchten, richten Sie die domainweite Delegierung von 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 einfache Abfragestring. Unter Suche mit Operatoren eingrenzen finden Sie eine Liste der unterstützten Suchoperatoren.
pageSize

integer

Maximale Anzahl der Suchergebnisse, die auf einer Seite zurückgegeben werden sollen. Gültige Werte liegen im Bereich von 1 bis 100. 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 nichts angegeben ist, werden alle Datenquellen 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 zum Anpassen des Rankings der Suchergebnisse verwendet werden. Die maximale Anzahl von Elementen beträgt 10.

Antworttext

Die Antwort der Search API. NEXT-ID: 19

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

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 Interpretation der Nutzeranfrage. Leer, wenn die Abfrageinterpretation deaktiviert ist.
results[]

object (SearchResult)

Ergebnisse einer Suchanfrage.
structuredResults[]

object (StructuredResult)

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

object (SpellResult)

Vorgeschlagene Schreibweise für die Abfrage.
facetResults[]

object (FacetResult)

Wiederholte Attributergebnisse.
hasMoreResults

boolean

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

object (ResponseDebugInfo)

Informationen zur Fehlerbehebung für die Antwort.
errorInfo

object (ErrorInfo)

Fehlerinformationen zur Antwort.
resultCounts

object (ResultCounts)

Erweiterte Informationen zur Anzahl der Ergebnisse.

Union-Feld result_count. Die Gesamtzahl der Ergebnisse für alle angeforderten Datenquellen. Wird ausgelassen, wenn vordefinierte Quellen in der Menge der abgefragten Datenquellen enthalten sind. Unter den folgenden Umständen kann die Anzahl der Ergebnisse als Schätzung und nicht als exakter Wert zurückgegeben werden:

  • Wenn die Anfrage mehr als zwei Begriffe in einer Wortgruppe enthält, z. B. „Anzahl der Ergebnisse exakt“ 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.

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 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 Autorisierungsleitfaden.

QueryInterpretationOptions

Optionen zum Interpretieren der Nutzeranfrage.

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

boolean

Flag zum Deaktivieren der Interpretation von Anfragen in natürlicher Sprache. Der Standardwert ist „false“. Wenn Sie die Interpretation in natürlicher Sprache deaktivieren möchten, setzen Sie den Wert auf „true“. Die Verarbeitung in natürlicher Sprache wird nur für vordefinierte Datenquellen unterstützt.
enableVerbatimMode

boolean

Wenn Sie dieses Flag aktivieren, werden alle internen Optimierungen deaktiviert, z. B. die Interpretation von Anfragen in natürlicher Sprache, das Abrufen zusätzlicher Ergebnisse und die Verwendung von Synonymen, einschließlich benutzerdefinierter Synonyme. Die Verarbeitung natürlicher Sprache wird deaktiviert, wenn eines der beiden Flags „true“ ist.
disableSupplementalResults

boolean

Mit diesem Flag können Sie zusätzliche Ergebnisse für eine Anfrage deaktivieren. Die auf Ebene der SearchApplication 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),
  "interpretedQueryActualResultCount": integer,
  "interpretedQueryEstimatedResultCount": string
}
Felder
interpretedQuery

string

Die in der Suche verwendete Interpretation der Anfrage. Anfragen 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 ist nicht UNSPECIFIED, wenn der Interpretationstyp nicht NONE ist.
interpretedQueryActualResultCount

integer

Die tatsächliche Anzahl der Ergebnisse, die von der interpretierten Abfrage zurückgegeben wurden.
interpretedQueryEstimatedResultCount

string (int64 format)

Die geschätzte Anzahl der Ergebnisse, die von der interpretierten Abfrage zurückgegeben werden.

QueryInterpretation.InterpretationType

Enums
NONE Weder die Interpretation in natürlicher Sprache noch eine allgemeinere Version der Anfrage 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 „reason“ (Grund) angegeben.
REPLACE Die Ergebnisse der ursprünglichen Abfrage werden ersetzt. Der Grund für den Ersatz der Ergebnisse der ursprünglichen Abfrage wird unten im Feld „reason“ (Grund) angegeben.

QueryInterpretation.Reason

Enums
UNSPECIFIED
QUERY_HAS_NATURAL_LANGUAGE_INTENT Die Interpretation der Anfrage in natürlicher Sprache wird verwendet, um die Suchergebnisse abzurufen.
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY Die Ähnlichkeit von Suchanfrage- und Dokumentbegriffen wird verwendet, um die Suchanfrage selektiv zu erweitern und zusätzliche Suchergebnisse abzurufen, da nicht genügend Ergebnisse für die Nutzeranfrage gefunden wurden. Die interpretierte Anfrage ist in diesem Fall leer.

SearchResult

Ergebnisse mit indexierten Informationen für ein Dokument. Nächste ID: 16

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 für dieses Ergebnis verfügbaren Snippets (Zusammenfassungen).
metadata

object (Metadata)

Metadaten des Suchergebnisses.
clusteredResults[]

object (SearchResult)

Wenn die Quelle gruppiert ist, geben Sie eine Liste der gruppierten Ergebnisse an. Es gibt nur eine Ebene mit gruppierten Ergebnissen. Wenn die aktuelle Quelle nicht für das Clustering 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 entsprechenden Seite zusammengefasst wird.

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

string

Der Ausschnitt des Dokuments. Kann maskierte HTML-Zeichen enthalten, die vor dem Rendern demaskiert werden müssen.
matchRanges[]

object (MatchRange)

Die übereinstimmenden Bereiche im Snippet.

MatchRange

Der übereinstimmende Bereich eines Snippets [start, end).

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

integer

Die Startposition der Übereinstimmung im Snippet.
end

integer

Ende des Spiels 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 Zeitpunkt der Erstellung dieses Dokuments oder Objekts im Suchergebnis.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Das Datum der letzten Änderung des Objekts im Suchergebnis. Wenn der Wert nicht im Artikel 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 ein Wert von 2 Jahren ab dem aktuellen Zeitpunkt verwendet.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
fields[]

object (NamedProperty)

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

object (ResultDisplayMetadata)

Optionen, die angeben, wie ein Suchergebnis für strukturierte Daten angezeigt werden soll.
objectType

string

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

Felder für query.search-Ergebnisse anzeigen

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

string

Das Anzeigelabel für die Property.
operatorName

string

Der Operatorname des Attributs.
property

object (NamedProperty)

Das Name/Wert-Paar für das Attribut.

ResultDebugInfo

Informationen zur Fehlerbehebung für das Ergebnis.

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

string

Allgemeine Debugging-Informationen, die für die Anzeige formatiert sind.

StructuredResult

Strukturierte Ergebnisse, die bei einer Suchanfrage zurückgegeben werden

JSON-Darstellung 
{

  // Union field structured_result can be only one of the following:
  "person": {
    object (Person)
  }
  // End of list of possible types for union field structured_result.
}
Felder

Union-Feld structured_result.

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

object (Person)

Darstellung einer Person

SpellResult

JSON-Darstellung 
{
  "suggestedQuery": string,
  "suggestionType": enum (SpellResult.SuggestionType),
  "suggestedQueryHtml": {
    object (SafeHtmlProto)
  }
}
Felder
suggestedQuery

string

Die vorgeschlagene Schreibweise der Abfrage.
suggestionType

enum (SpellResult.SuggestionType)

Vorschlag für die aktuelle Abfrage ausgelöst.
suggestedQueryHtml

object (SafeHtmlProto)

Das bereinigte HTML, das die korrigierte Anfrage darstellt und in der Benutzeroberfläche verwendet werden kann. In der Regel sind sprachspezifische Tags vorhanden, um Teile der Abfrage zu kennzeichnen, die einer Rechtschreibprüfung unterzogen werden.

SpellResult.SuggestionType

Der Typ des Vorschlags, der für die Abfrage ausgelöst wurde.

Enums
SUGGESTION_TYPE_UNSPECIFIED Standardtyp der Rechtschreibprüfung
NON_EMPTY_RESULTS_SPELL_SUGGESTION Rechtschreibvorschlag ohne geänderte Ergebnisse. Die Ergebnisse werden weiterhin für die ursprüngliche Suchanfrage (mit Ergebnissen ungleich null) angezeigt, zusammen mit einem Vorschlag für eine Schreibweise, die Ergebnisse liefern würde.
ZERO_RESULTS_FULL_PAGE_REPLACEMENT Rechtschreibvorschlag wird ausgelöst, wenn die ursprüngliche Anfrage keine Ergebnisse liefert. Wenn die ursprüngliche Anfrage keine Ergebnisse liefert und die Rechtschreibkorrektur Ergebnisse liefert, werden Ergebnisse für die korrigierte Anfrage ausgelöst.

SafeHtmlProto

WICHTIG: Es ist unsicher, diese Nachricht von einer nicht vertrauenswürdigen Quelle zu akzeptieren, da es für einen Angreifer trivial ist, serialisierte Nachrichten zu fälschen, die den Sicherheitsvertrag des Typs nicht erfüllen. Sie könnten beispielsweise ein vom Angreifer kontrolliertes Skript enthalten. Ein System, das ein SafeHtmlProto empfängt, vertraut dem Ersteller des SafeHtmlProto implizit. Daher ist es in der Regel sicher, diese Nachricht in RPC-Antworten zurückzugeben, aber in der Regel unsicher, sie in RPC-Anfragen zu akzeptieren.

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

string

WICHTIG: Dieses Feld darf niemals festgelegt oder gelesen werden, auch nicht in Tests. Es ist privat. In der Dokumentation oben in der .proto-Datei finden Sie Informationen zu den Programmiersprachenpaketen, mit denen Sie diese Nachricht erstellen oder lesen können.

FacetResult

Quellspezifische Facettenantwort

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

string

Quellname, für den Attributergebnisse zurückgegeben werden. Darf nicht leer sein.
objectType

string

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

string

Der Name des Operators, der für die Facettierung 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 Grundeinheit für Vorgänge. Ein Bucket kann je nach Typ des Felds, das in Buckets unterteilt wird, entweder einen einzelnen Wert oder einen zusammenhängenden Wertebereich umfassen. FacetBucket wird derzeit nur zum Zurückgeben des Antwortobjekts verwendet.

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

  // Union field bucket_value can be only one of the following:
  "value": {
    object (Value)
  }
  // End of list of possible types for union field bucket_value.
}
Felder
count

integer

Anzahl der Ergebnisse, die mit dem Bucket-Wert übereinstimmen. Zahlen werden nur für Suchanfragen zurückgegeben, bei denen die Genauigkeit der Zahlen gewährleistet ist. Cloud Search garantiert keine Anzahl von Facetten für eine Abfrage. Die Anzahl von Facetten ist möglicherweise nur zeitweise vorhanden, auch bei identischen Abfragen. Erstellen Sie keine Abhängigkeiten von der Anzahl der Facetten. Verwenden Sie stattdessen die Prozentsätze der Facettenanzahl, die immer zurückgegeben werden.
percentage

integer

Prozentsatz der Ergebnisse, die mit dem Bucket-Wert übereinstimmen. Der zurückgegebene Wert liegt zwischen 0 und 100 (einschließlich) und wird auf eine Ganzzahl abgerundet, wenn er eine Dezimalzahl ist. Wenn der Wert nicht explizit zurückgegeben wird, stellt er einen Prozentsatz dar, der auf 0 gerundet wird. Prozentsätze werden für alle Suchanfragen zurückgegeben, sind aber Schätzungen. Da immer Prozentsätze 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.
Union-Feld bucket_value. Der Bereich oder Wert des Bucket, der mit bucket_value facettiert wird, kann nur einer der folgenden sein:
value

object (Value)

ResponseDebugInfo

Informationen zur Fehlerbehebung für die Antwort.

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

string

Allgemeine Debugging-Informationen, die für die Anzeige formatiert sind.

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 Anzahl der Ergebnisse

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

object (SourceResultCount)

Informationen zur Anzahl der Ergebnisse 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 Anzahl der Ergebnisse zugeordnet sind.
hasMoreResults

boolean

Gibt an, ob für diese Quelle weitere Suchergebnisse vorhanden sind.

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.