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

URL имеет синтаксис gRPC Transcoding.

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

Параметры
parent

string

Обязательно. Название ресурса чат-группы, в которой нужно выполнить поиск.

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

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

Тело запроса

Ниже приведена структура данных в теле запроса.

JSON-представление 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "markupSyntax": enum (MarkupSyntax),
  "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 – поддерживает оператор : (содержит) и фильтрует чат-группы по частичному совпадению с их отображаемым названием. В результатах показывается до пяти чат-групп. Например, space.display_name:Project ищет сообщения в пяти чат-группах, в отображаемом названии которых есть слово "Проект".
  • space.space_type – тип чат-группы. Поддерживается только =. Например, space.space_type="DIRECT_MESSAGE" возвращает только сообщения из прямых переписок. Допустимые значения: DIRECT_MESSAGE, GROUP_CHAT, SPACE.
  • attachment: поддерживает оператор :* (имеет любой), чтобы проверять наличие прикрепленных файлов. Если указан параметр 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 или space.space_type, учетные данные вызывающей стороны должны включать одну из следующих областей авторизации:

  • 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 или оба слова.
  • space.space_type поддерживает только оператор OR, например space.space_type = "DIRECT_MESSAGE" OR space.space_type = "GROUP_CHAT".
  • 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

Необязательное поле. Токен, полученный из предыдущего вызова search messages. Укажите этот параметр, чтобы получить следующую страницу.

При разбиении на страницы все остальные параметры должны соответствовать вызову, который предоставил токен страницы. Передача других значений в другие параметры может привести к неожиданным результатам.
orderBy

string

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

Поддерживаемые атрибуты для сортировки:

По умолчанию используется createTime desc. В запросе можно указать только один порядок сортировки (createTime или relevance). Поддерживается только сортировка по убыванию (desc), которая должна быть указана после атрибута order.
markupSyntax

enum (MarkupSyntax)

Необязательное поле. Указывает желаемый синтаксис выходных данных для поля formattedText сообщения чата.
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)

Настройка отключения звука для пользователя, который звонит в чат-группу, где опубликовано сообщение. Приложение, вызывающее API, может использовать эту информацию, чтобы решить, как обрабатывать сообщение, в зависимости от того, отключены ли уведомления в чат-группе для пользователя.

Возвращается, только если в запросе указано представление 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