Method: spaces.messages.search

在调用用户有权访问的 Google Chat 中搜索消息。返回与搜索条件匹配的消息列表。

如需在用户有权访问的所有聊天室中进行搜索，请将 parent 设置为 spaces/-。如果为 parent 使用任何其他值，则会导致 INVALID_ARGUMENT 错误。返回的消息的 name 字段会填充完整资源名称，其中包括消息所在的特定 space。

此 API 不会返回所有消息类型。以下列出的消息类型不包含在响应中。如需列出所有消息，请使用 messages.list。

  • 经过身份验证的用户可见的私信。
  • Chat 应用在聊天室或群聊中发布的消息。
  • Chat 应用私信中的消息。
  • 来自被屏蔽用户的消息。
  • 调用者已静音的聊天室中的消息。

需要使用以下授权范围之一进行用户身份验证：

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

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
parent

string

必需。要在其中进行搜索的聊天室的资源名称。

如需在用户有权访问的所有聊天室中进行搜索，请将此字段设置为 spaces/-。如果为 parent 使用任何其他值，则会导致 INVALID_ARGUMENT 错误。

如需将搜索范围限制为一个或多个聊天室，请在 filter 中使用 space.name 或 space.display_name。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
字段
filter

string

必需。搜索查询。

查询可以指定一个或多个搜索关键字，这些关键字用于过滤结果，

您还可以使用以下消息字段过滤结果：

  • createTime：接受 RFC-3339 格式的时间戳，支持的比较运算符为：< 和 >=。
  • sender.name：发送者的资源名称 (users/{user})。仅支持 =。您可以使用电子邮件地址作为 {user} 的别名。例如，users/example@gmail.com，其中 example@gmail.com 是 Google Chat 用户的电子邮件地址。
  • space.name：发布消息的聊天室的资源名称。 (spaces/{space})。仅支持 =。如果未设置此过滤条件，则会在用户有权访问的所有私信和聊天室（作为聊天室成员）中执行搜索。
  • space.display_name：支持运算符 :（包含），并根据聊天室显示名称的部分匹配项过滤聊天室。结果仅限于前 5 个匹配的聊天室。例如，space.display_name:Project 会在前 5 个聊天室中搜索显示名称中包含“Project”字词的消息。
  • attachment：支持运算符 :*（包含任何内容），以检查是否存在附件。如果指定了 attachment:*，则仅返回包含至少一个附件的消息。
  • annotations.user_mentions.user.name：被提及用户的资源名称 (users/{user})。仅支持 :（包含）。例如：annotations.user_mentions.user.name:"users/1234567890" 仅返回包含提及指定用户的消息。或者，您可以使用别名 me 来过滤提及调用用户的消息，例如：annotations.user_mentions.user.name:users/me。您还可以使用电子邮件地址作为 {user} 的别名，例如 users/example@gmail.com。

如需进行高级过滤，您还可以使用以下函数：

  • has_link()：仅返回消息正文中包含至少一个超链接的消息。
  • is_unread()：过滤掉已被调用用户读取的消息。

使用 space.display_name 过滤条件需要调用凭据包含以下 授权范围 之一：

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

使用 is_unread() 过滤条件需要调用凭据包含以下 授权范围 之一：

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

在不同的字段之间，仅支持 AND 运算符。一个有效的示例是 sender.name = "users/1234567890" AND is_unread()。字词 AND 是可选的，如果省略，则表示隐含。例如，sender.name = "users/1234567890" is_unread() 是有效的，并且等同于上一个示例。一个无效的示例是 sender.name = "users/1234567890" OR is_unread()，因为 OR 在不同的字段之间不受支持。

在同一字段中：

  • createTime 仅支持 AND，并且只能用于表示时间间隔，例如 createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00"。
  • sender.name 仅支持 OR 运算符，例如： sender.name = "users/1234567890" OR sender.name = "users/0987654321"。
  • space.name 仅支持 OR 运算符，例如： space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI"。
  • space.display_name 支持运算符 AND 和 OR，但不支持两者混合使用。例如：space.display_name:Project AND space.display_name:Tasks 返回显示名称中同时包含 Project 和 Tasks 的聊天室中的消息，而 space.display_name:Project OR space.display_name:Tasks 返回显示名称中包含 Project 或 Tasks 或同时包含两者的聊天室中的消息。
  • annotations.user_mentions.user.name 支持运算符 AND 和 OR，但不支持两者混合使用。例如：annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" 仅返回提及这两个用户的消息，而 annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" 返回提及其中一个用户或同时提及两个用户的消息。

在同一查询中组合使用 AND 和 OR 运算符时，需要使用英文括号来消除运算符优先级的歧义。例如：(sender.name="users/me" OR sender.name="users/123456") AND is_unread()。否则，英文括号是可选的。

以下示例查询是有效的：

"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

查询长度上限为 1,000 个字符。

服务器会拒绝无效查询，并返回 INVALID_ARGUMENT 错误。
pageSize

integer

可选。返回的结果数上限。服务返回的值可能小于此值。

如果未指定，则最多返回 25 个结果。

最大值为 100。如果您使用的值超过 100，系统会自动将其更改为 100。
pageToken

string

可选。从之前的搜索消息调用中收到的令牌。提供此参数以检索后续页面。

进行分页时，提供的所有其他参数应与提供页面令牌的调用匹配。向其他参数传递不同的值可能会导致意外的结果。
orderBy

string

可选。结果列表的排序方式。

支持按以下属性排序：

默认排序方式为 createTime desc。每个查询仅支持一种排序方式（createTime 或 relevance）。仅支持降序 (desc)，并且必须在排序属性后指定。
view

enum (SearchMessagesView)

可选。指定要返回的搜索结果视图类型。默认值为 SEARCH_MESSAGES_VIEW_BASIC。

响应正文

用于搜索消息的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
字段
results[]

object (SearchMessageResult)

与查询匹配的搜索结果列表。
nextPageToken

string

可用于检索下一页的令牌。如果此字段为空，则表示没有后续页面。

授权范围

需要以下 OAuth 范围之一：

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

如需了解详情，请参阅授权指南。

SearchMessagesView

部分搜索结果支持的视图类型。

枚举
SEARCH_MESSAGES_VIEW_UNSPECIFIED 默认值 / 未设置的值。API 将默认使用 BASIC 视图。
SEARCH_MESSAGES_VIEW_BASIC 结果中仅包含匹配的消息，但不包含其他元数据。这是默认值。
SEARCH_MESSAGES_VIEW_FULL 结果中包含所有内容：匹配的消息和其他元数据。

SearchMessageResult

消息搜索中的单个结果项。

JSON 表示法 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
字段
message

object (Message)

匹配的消息。
spaceMuteSetting

enum (MuteSetting)

调用用户针对发布消息的聊天室的静音设置。调用方应用可以使用此信息来决定如何处理消息，具体取决于用户是否已将聊天室静音。

仅当请求视图为 SEARCH_MESSAGES_VIEW_FULL 且调用凭据包含以下 授权范围时，才会返回此信息：

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

boolean

指明匹配的消息是否已被调用用户读取。

仅当请求视图为 SEARCH_MESSAGES_VIEW_FULL 且调用凭据包含以下 授权范围之一时，才会返回此信息：

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