Method: spaces.messages.search

Sucht nach Nachrichten in Google Chat, auf die der anrufende Nutzer Zugriff hat. Gibt eine Liste von Nachrichten zurück, die den Suchkriterien entsprechen.

Wenn Sie alle Gruppenbereiche durchsuchen möchten, auf die der Nutzer Zugriff hat, legen Sie parent auf spaces/- fest. Die Verwendung eines anderen Werts für parent führt zu einem INVALID_ARGUMENT-Fehler. Bei den zurückgegebenen Nachrichten ist das Feld name mit dem vollständigen Ressourcennamen ausgefüllt, der den spezifischen space enthält, in dem sich die Nachricht befindet.

Diese API gibt nicht alle Nachrichtentypen zurück. Die unten aufgeführten Nachrichtentypen sind nicht in der Antwort enthalten. Verwenden Sie messages.list, um alle Nachrichten aufzulisten.

  • Private Nachrichten, die für den authentifizierten Nutzer sichtbar sind.
  • Nachrichten, die von Chat-Apps in Gruppenbereichen oder Gruppenchats gepostet wurden.
  • Nachrichten in einer Direktnachricht in einer Chat-App.
  • Nachrichten von blockierten Nutzern
  • Nachrichten in Gruppenbereichen, die der Anrufer stummgeschaltet hat.

Erfordert Nutzerauthentifizierung mit einem der folgenden Autorisierungsbereiche:

  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.messages

HTTP-Anfrage

POST https://chat.googleapis.com/v1/{parent=spaces/*}/messages:search

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
parent

string

Erforderlich. Der Ressourcenname des zu durchsuchenden Gruppenbereichs.

Wenn Sie alle Gruppenbereiche durchsuchen möchten, auf die der Nutzer Zugriff hat, legen Sie dieses Feld auf spaces/- fest. Die Verwendung eines anderen Werts für parent führt zu einem INVALID_ARGUMENT-Fehler.

Wenn Sie die Suche auf einen oder mehrere Bereiche beschränken möchten, verwenden Sie space.name oder space.display_name im filter.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

JSON-Darstellung 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "markupSyntax": enum (MarkupSyntax),
  "view": enum (SearchMessagesView)
}
Felder
filter

string

Erforderlich. Eine Suchanfrage.

In der Anfrage können ein oder mehrere Such-Keywords angegeben werden, mit denen die Ergebnisse gefiltert werden.

Sie können die Ergebnisse auch anhand der folgenden Nachrichtenfelder filtern:

  • createTime: Akzeptiert einen Zeitstempel im RFC-3339. Die unterstützten Vergleichsoperatoren sind: < und >=.
  • sender.name: Der Ressourcenname des Absenders (users/{user}). Es wird nur = unterstützt. Sie können die E‑Mail-Adresse als Alias für {user} verwenden. Beispiel: users/example@gmail.com, wobei example@gmail.com die E‑Mail-Adresse des Google Chat-Nutzers ist.
  • space.name: Der Ressourcenname des Bereichs, in dem die Nachricht gepostet wird. (spaces/{space}). Unterstützt nur =. Wenn dieser Filter nicht festgelegt ist, wird die Suche in allen Direktnachrichten und Projektbereichen durchgeführt, auf die der Nutzer als Mitglied eines Projektbereichs Zugriff hat.
  • space.display_name: Unterstützt den Operator : (hat) und filtert Bereiche basierend auf einer teilweisen Übereinstimmung ihres Anzeigenamens. Die Ergebnisse sind auf die fünf besten Übereinstimmungen beschränkt. Mit space.display_name:Project wird beispielsweise nach Nachrichten in den fünf wichtigsten Bereichen gesucht, deren Anzeigenamen das Wort „Projekt“ enthalten.
  • space.space_type: Der Typ des Bereichs. Unterstützt nur =. Mit space.space_type="DIRECT_MESSAGE" werden beispielsweise nur Nachrichten aus Direktnachrichten zurückgegeben. Mögliche Werte sind DIRECT_MESSAGE, GROUP_CHAT und SPACE.
  • attachment: Unterstützt den Operator :* (has any), um nach dem Vorhandensein von Anhängen zu suchen. Wenn attachment:* angegeben ist, werden nur Nachrichten mit mindestens einem Anhang zurückgegeben.
  • annotations.user_mentions.user.name: Der Ressourcenname des erwähnten Nutzers (users/{user}). Es wird nur : (has) unterstützt. Beispiel: annotations.user_mentions.user.name:"users/1234567890" gibt nur Nachrichten zurück, in denen der angegebene Nutzer erwähnt wird. Alternativ kann der Alias me verwendet werden, um nach Nachrichten zu filtern, in denen der Anrufer erwähnt wird, z. B. annotations.user_mentions.user.name:users/me. Sie können die E‑Mail-Adresse auch als Alias für {user} verwenden, z. B. users/example@gmail.com.

Für die erweiterte Filterung sind auch die folgenden Funktionen verfügbar:

  • has_link(): Gibt nur Nachrichten zurück, die mindestens einen Hyperlink im Nachrichtentext enthalten.
  • is_unread(): Filtert Nachrichten heraus, die vom aufrufenden Nutzer gelesen wurden.

Für die Verwendung der Filter space.display_name oder space.space_type müssen die Anmeldedaten des Aufrufers einen der folgenden Autorisierungsbereiche enthalten:

  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.spaces

Für die Verwendung des Filters is_unread() müssen die Anmeldedaten des Aufrufers einen der folgenden Autorisierungsbereiche enthalten:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate

Für verschiedene Felder werden nur AND-Operatoren unterstützt. Ein gültiges Beispiel ist sender.name = "users/1234567890" AND is_unread(). Das Wort AND ist optional und wird impliziert, wenn es nicht angegeben wird. sender.name = "users/1234567890" is_unread() ist beispielsweise gültig und entspricht dem vorherigen Beispiel. Ein ungültiges Beispiel ist sender.name = "users/1234567890" OR is_unread(), da OR nicht zwischen verschiedenen Feldern unterstützt wird.

Im selben Feld:

  • createTime unterstützt nur AND und kann nur verwendet werden, um ein Intervall darzustellen, z. B. createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name unterstützt nur den Operator OR, z. B. sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name unterstützt nur den Operator OR, z. B. space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name unterstützt die Operatoren AND und OR, aber nicht eine Kombination aus beiden. Beispiel: space.display_name:Project AND space.display_name:Tasks gibt Nachrichten zurück, die sich in Bereichen mit Anzeigenamen befinden, die sowohl Project als auch Tasks enthalten. space.display_name:Project OR space.display_name:Tasks gibt Nachrichten zurück, die sich in Bereichen mit Anzeigenamen befinden, die entweder Project oder Tasks oder beides enthalten.
  • space.space_type unterstützt nur den Operator OR, z. B. space.space_type = "DIRECT_MESSAGE" OR space.space_type = "GROUP_CHAT".
  • annotations.user_mentions.user.name unterstützt die Operatoren AND und OR, aber nicht eine Kombination aus beiden. Beispiel: Bei annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" werden nur Nachrichten zurückgegeben, in denen beide Nutzer erwähnt werden, bei annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" werden Nachrichten zurückgegeben, in denen einer oder beide Nutzer erwähnt werden.

Klammern sind erforderlich, um die Operatorrangfolge zu verdeutlichen, wenn die Operatoren AND und OR in derselben Abfrage kombiniert werden. z. B. (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Andernfalls sind Klammern optional.

Die folgenden Beispielabfragen sind gültig:

"Pending reports" AND createTime >= "2023-01-01T00:00:00Z"

sender.name = "users/example@gmail.com"

annotations.user_mentions.user.name:"users/0987654321"

attachment:* AND space.name = "spaces/ABCDEFGH"

tasks AND is_unread() AND sender.name = "users/1234567890"

"things to do" "urgent"

(sender.name = "users/1234567890")
AND (createTime < "2023-05-01T00:00:00Z")

tasks AND space.name = "spaces/ABCDEFGH" AND has_link()

"project one" is_unread()

space.display_name:Project tasks

Die maximale Länge einer Anfrage beträgt 1.000 Zeichen.

Ungültige Anfragen werden vom Server mit dem Fehler INVALID_ARGUMENT abgelehnt.
pageSize

integer

Optional. Die maximale Anzahl von zurückzugebenden Ergebnissen. Der Dienst gibt möglicherweise weniger als diesen Wert zurück.

Wenn nicht angegeben, werden maximal 25 zurückgegeben.

Der Höchstwert ist 100. Wenn Sie einen Wert über 100 verwenden, wird er automatisch in 100 geändert.
pageToken

string

Optional. Ein Token, das vom vorherigen Aufruf von „Nachrichten suchen“ empfangen wurde. Geben Sie diesen Parameter an, um die nachfolgende Seite abzurufen.

Beim Paginieren müssen alle anderen bereitgestellten Parameter mit dem Aufruf übereinstimmen, der das Seitentoken bereitgestellt hat. Wenn Sie für die anderen Parameter unterschiedliche Werte übergeben, kann das zu unerwarteten Ergebnissen führen.
orderBy

string

Optional. Wie die Ergebnisliste sortiert wird.

Folgende Attribute können für die Sortierung verwendet werden:

  • createTime: Sortiert die Ergebnisse nach dem Zeitpunkt der Nachrichtenerstellung. Standardwert.
  • relevance: Sortiert die Ergebnisse nach Relevanz. ( Entwicklervorschau)

Die Standardreihenfolge ist createTime desc. Pro Abfrage (createTime oder relevance) wird nur eine Bestellung unterstützt. Es wird nur die absteigende Reihenfolge (desc) unterstützt. Sie muss nach dem Attribut für die Sortierung angegeben werden.
markupSyntax

enum (MarkupSyntax)

Optional. Gibt die gewünschte Ausgabesyntax für das Feld „Chat-Nachricht“ formattedText an.
view

enum (SearchMessagesView)

Optional. Gibt an, welche Art von Suchergebnisansicht zurückgegeben werden soll. Der Standardwert ist SEARCH_MESSAGES_VIEW_BASIC.

Antworttext

Antwortnachricht für die Suche nach Nachrichten.

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

JSON-Darstellung 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
Felder
results[]

object (SearchMessageResult)

Die Liste der Suchergebnisse, die der Abfrage entsprechen.
nextPageToken

string

Ein Token, mit dem die nächste Seite abgerufen werden kann. Wenn dieses Feld leer ist, gibt es keine nachfolgenden Seiten.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly

Weitere Informationen finden Sie im Autorisierungsleitfaden.

SearchMessagesView

Die Arten von Ansichten, die für Teilergebnisse unterstützt werden.

Enums
SEARCH_MESSAGES_VIEW_UNSPECIFIED Der Standardwert bzw. der nicht festgelegte Wert. Die API verwendet standardmäßig die BASIC-Ansicht.
SEARCH_MESSAGES_VIEW_BASIC Enthält nur die übereinstimmenden Nachrichten in den Ergebnissen, aber keine zusätzlichen Metadaten. „Immer“ ist der Standardwert.
SEARCH_MESSAGES_VIEW_FULL Umfasst alle Elemente in den Ergebnissen: die übereinstimmenden Nachrichten und zusätzliche Metadaten.

SearchMessageResult

Ein einzelnes Ergebnis einer Nachrichtensuche.

JSON-Darstellung 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
Felder
message

object (Message)

Die übereinstimmende Nachricht.
spaceMuteSetting

enum (MuteSetting)

Die Stummschaltung des anrufenden Nutzers für den Gruppenbereich, in dem die Nachricht gepostet wird. Die Anrufer-App kann anhand dieser Informationen entscheiden, wie die Nachricht verarbeitet werden soll, je nachdem, ob der Gruppenbereich für den Nutzer stummgeschaltet ist oder nicht.

Wird nur zurückgegeben, wenn die Ansicht der Anfrage SEARCH_MESSAGES_VIEW_FULL ist und die Anmeldedaten des Aufrufers den folgenden Autorisierungsbereich enthalten:

  • https://www.googleapis.com/auth/chat.users.spacesettings
read

boolean

Gibt an, ob die übereinstimmende Nachricht vom aufrufenden Nutzer gelesen wurde.

Wird nur zurückgegeben, wenn die Anfrageansicht SEARCH_MESSAGES_VIEW_FULL ist und die Anmeldedaten für den Aufruf einen der folgenden Autorisierungsbereiche enthalten:

  • https://www.googleapis.com/auth/chat.users.readstate.readonly
  • https://www.googleapis.com/auth/chat.users.readstate