Method: spaces.messages.search

Выполняет поиск сообщений в Google Chat, к которым имеет доступ вызывающий пользователь. Возвращает список сообщений, соответствующих критериям поиска.

Для поиска по всем пространствам, к которым пользователь имеет доступ, установите parent в spaces/- . Использование любого другого значения для parent приведет к ошибке INVALID_ARGUMENT . В возвращаемых сообщениях поле name заполняется полным именем ресурса, включая конкретное space , в котором находится сообщение.

Этот API не возвращает все типы сообщений. Типы сообщений, перечисленные ниже, не включены в ответ. Используйте messages.list для вывода списка всех сообщений.

  • Личные сообщения, видимые авторизованному пользователю.
  • Сообщения, размещенные приложениями для чата в отдельных пространствах или групповых чатах.
  • Сообщения в личных сообщениях в чат-приложении.
  • Сообщения от заблокированных пользователей.
  • Сообщения в местах, которые звонящий отключил.

Требуется аутентификация пользователя с использованием одной из следующих областей авторизации :

  • 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

В URL-адресе используется синтаксис транскодирования gRPC .

Параметры пути

Параметры
parent

string

Обязательно. Название ресурса пространства, в котором будет производиться поиск.

Для поиска по всем пространствам, к которым пользователь имеет доступ, установите для этого поля значение spaces/- . Использование любого другого значения для parent приведет к ошибке INVALID_ARGUMENT .

Чтобы ограничить поиск одним или несколькими пробелами, используйте space.name или space.display_name в filter .

Текст запроса

Тело запроса содержит данные следующей структуры:

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 : Поддерживает оператор : (has) и фильтрует пространства на основе частичного совпадения их отображаемого имени. Результаты ограничены пятью наиболее часто встречающимися пространствами. Например, space.display_name:Project ищет сообщения в пяти наиболее часто встречающихся пространствах, которые содержат слово "Project" в своих отображаемых именах.
  • attachment : Поддерживает оператор :* (has any) для проверки наличия вложений. Если указан attachment:* , возвращаются только сообщения, имеющие хотя бы одно вложение.
  • annotations.user_mentions.user.name : Имя ресурса упомянутого пользователя ( users/{user} ). Поддерживается только : (has). Например: 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

Максимальная длина запроса составляет 1000 символов.

Сервер отклоняет некорректные запросы с ошибкой 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