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 个空间中搜索消息。
  • 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：按消息创建时间对结果进行排序。默认值。
  • relevance：按相关性对结果进行排序。

默认排序为 createTime desc。每个查询仅支持一个排序顺序（createTime 或 relevance）。仅支持降序 (desc)，并且必须在 order 属性之后指定。
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