Method: spaces.messages.search

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

Wenn Sie in allen Bereichen suchen möchten, auf die der Nutzer Zugriff hat, legen Sie parent auf spaces/- fest. Bei Verwendung eines anderen Werts für parent wird der Fehler INVALID_ARGUMENT zurückgegeben. Im Feld name der zurückgegebenen Nachrichten ist der vollständige Ressourcenname enthalten, einschließlich des spezifischen space, 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 Bereichen oder Gruppenchats gepostet wurden.
  • Nachrichten in einer Direktnachricht einer Chat-App.
  • Nachrichten von blockierten Nutzern.
  • Nachrichten in Bereichen, die der Anrufer stummgeschaltet hat.

Erfordert eine 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 Bereichs, in dem gesucht werden soll.

Wenn Sie in allen Bereichen suchen möchten, auf die der Nutzer Zugriff hat, legen Sie dieses Feld auf spaces/- fest. Bei Verwendung eines anderen Werts für parent wird der Fehler INVALID_ARGUMENT zurückgegeben.

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,
  "view": enum (SearchMessagesView)
}
Felder
filter

string

Erforderlich. Eine Suchanfrage.

Die Abfrage kann einen oder mehrere Suchbegriffe enthalten, mit denen die Ergebnisse gefiltert werden.

Sie können die Ergebnisse auch mit den folgenden Nachrichtenfeldern filtern:

  • createTime: Akzeptiert einen Zeitstempel im RFC-3339-Format. Die unterstützten Vergleichsoperatoren sind < und >=.
  • sender.name: Der Ressourcenname des Absenders (users/{user}). Unterstützt nur =. 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 wurde. (spaces/{space}). Unterstützt nur =. Wenn dieser Filter nicht festgelegt ist, wird die Suche in allen Direktnachrichten und Bereichen durchgeführt, auf die der Nutzer als Bereichsmitglied 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 Bereichsübereinstimmungen beschränkt. Beispiel: space.display_name:Project sucht nach Nachrichten in den fünf besten Bereichen, deren Anzeigenamen das Wort „Project“ enthalten.
  • attachment: Unterstützt den Operator :* (hat beliebige), 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}). Unterstützt nur : (hat). Beispiel: annotations.user_mentions.user.name:"users/1234567890" gibt nur Nachrichten zurück, die eine Erwähnung des angegebenen Nutzers enthalten. Alternativ kann der Alias me verwendet werden, um nach Nachrichten zu filtern, in denen der aufrufende Nutzer 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 eine 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 des Filters space.display_name muss die aufrufende Anmeldekonfiguration 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() muss die aufrufende Anmeldekonfiguration 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 weggelassen wird. Beispiel: sender.name = "users/1234567890" is_unread() ist gültig und entspricht dem vorherigen Beispiel. Ein ungültiges Beispiel ist sender.name = "users/1234567890" OR is_unread(), da OR zwischen verschiedenen Feldern nicht unterstützt wird.

Für dasselbe 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 keine Kombination aus beiden. Beispiel: space.display_name:Project AND space.display_name:Tasks gibt Nachrichten zurück, die sich in Bereichen befinden, deren Anzeigenamen sowohl Project als auch Tasks enthalten. space.display_name:Project OR space.display_name:Tasks gibt Nachrichten zurück, die sich in Bereichen befinden, deren Anzeigenamen entweder Project oder Tasks oder beides enthalten.
  • annotations.user_mentions.user.name unterstützt die Operatoren AND und OR, aber keine Kombination aus beiden. Beispiel: annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" gibt nur Nachrichten zurück, in denen beide Nutzer erwähnt werden. annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" gibt Nachrichten zurück, in denen einer der beiden Nutzer oder beide erwähnt werden.

Klammern sind erforderlich, um die Operatorpriorität zu verdeutlichen, wenn AND- und OR-Operatoren in derselben Abfrage kombiniert werden. Beispiel: (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 Abfragelänge beträgt 1.000 Zeichen.

Ungültige Abfragen 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 Maximalwert ist 100. Wenn Sie einen Wert über 100 verwenden, wird er automatisch auf 100 geändert.
pageToken

string

Optional. Ein Token, das vom vorherigen Aufruf zum Suchen von Nachrichten 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 andere Werte an die anderen Parameter übergeben, kann dies zu unerwarteten Ergebnissen führen.
orderBy

string

Optional. So wird die Ergebnisliste sortiert.

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

  • createTime: Sortiert die Ergebnisse nach der Erstellungszeit der Nachricht. Standardwert.
  • relevance: Sortiert die Ergebnisse nach Relevanz.

Die Standardsortierung ist createTime desc. Pro Abfrage wird nur eine Sortierung (createTime oder relevance) unterstützt. Nur die absteigende Sortierung (desc) wird unterstützt. Sie muss nach dem Sortierattribut angegeben werden.
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, das zum Abrufen der nächsten Seite verwendet 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 teilweise Suchergebnisse unterstützt werden.

Enums
SEARCH_MESSAGES_VIEW_UNSPECIFIED Der Standardwert oder 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. Dies ist der Standardwert.
SEARCH_MESSAGES_VIEW_FULL Enthält alles in den Ergebnissen: die übereinstimmenden Nachrichten und zusätzliche Metadaten.

SearchMessageResult

Ein einzelnes Ergebniselement aus einer Nachrichtensuche.

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

object (Message)

Die übereinstimmende Nachricht.
spaceMuteSetting

enum (MuteSetting)

Die Stummschaltungseinstellung des aufrufenden Nutzers für den Bereich, in dem die Nachricht gepostet wurde. Die aufrufende App kann anhand dieser Informationen entscheiden, wie die Nachricht verarbeitet werden soll, je nachdem, ob der Bereich für den Nutzer stummgeschaltet ist oder nicht.

Wird nur zurückgegeben, wenn die Ansicht der Anfrage SEARCH_MESSAGES_VIEW_FULL ist und die aufrufende Anmeldekonfiguration den folgenden Autorisierungsbereich enthält:

  • 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 Ansicht der Anfrage SEARCH_MESSAGES_VIEW_FULL ist und die aufrufende Anmeldekonfiguration einen der folgenden Autorisierungsbereiche enthält:

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