Method: spaces.messages.search

Tìm kiếm những tin nhắn trong Google Chat mà người dùng gọi có quyền truy cập. Trả về danh sách các thư phù hợp với tiêu chí tìm kiếm.

Để tìm kiếm trong tất cả các không gian mà người dùng có quyền truy cập, hãy đặt parent thành spaces/-. Việc sử dụng bất kỳ giá trị nào khác cho parent sẽ dẫn đến lỗi INVALID_ARGUMENT. Các thông báo được trả về có trường name được điền tên tài nguyên đầy đủ, bao gồm cả space cụ thể mà thông báo đó nằm trong.

API này không trả về tất cả các loại thông báo. Các loại thông báo được liệt kê bên dưới sẽ không có trong phản hồi. Sử dụng messages.list để liệt kê tất cả thông báo.

  • Tin nhắn riêng tư mà người dùng đã xác thực có thể nhìn thấy.
  • Tin nhắn do các ứng dụng Chat đăng trong không gian hoặc cuộc trò chuyện nhóm.
  • Tin nhắn trong tin nhắn trực tiếp của ứng dụng Chat.
  • Tin nhắn của người dùng bị chặn.
  • Tin nhắn trong các không gian mà người gọi đã tắt tiếng.

Yêu cầu xác thực người dùng bằng một trong các phạm vi uỷ quyền sau:

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

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Tham số
parent

string

Bắt buộc. Tên tài nguyên của không gian cần tìm kiếm.

Để tìm kiếm trong tất cả các không gian mà người dùng có quyền truy cập, hãy đặt trường này thành spaces/-. Việc sử dụng bất kỳ giá trị nào khác cho parent sẽ dẫn đến lỗi INVALID_ARGUMENT.

Để giới hạn phạm vi tìm kiếm trong một hoặc nhiều không gian, hãy sử dụng space.name hoặc space.display_name trong filter.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu với cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "filter": string,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "view": enum (SearchMessagesView)
}
Trường
filter

string

Bắt buộc. Cụm từ tìm kiếm.

Cụm từ tìm kiếm có thể chỉ định một hoặc nhiều từ khoá tìm kiếm. Các từ khoá này được dùng để lọc kết quả,

Bạn cũng có thể lọc kết quả bằng các trường thông báo sau:

  • createTime: Chấp nhận dấu thời gian ở định dạng RFC-3339 và các toán tử so sánh được hỗ trợ là: < và >=.
  • sender.name: Tên tài nguyên của người gửi (users/{user}). Chỉ hỗ trợ =. Bạn có thể sử dụng email này làm email đại diện cho {user}. Ví dụ: users/example@gmail.com, trong đó example@gmail.com là email của người dùng Google Chat.
  • space.name: Tên tài nguyên của không gian nơi đăng thông báo. (spaces/{space}). Chỉ hỗ trợ =. Nếu bạn không đặt bộ lọc này, thì nội dung tìm kiếm sẽ được thực hiện trên tất cả tin nhắn trực tiếp và không gian mà người dùng có quyền truy cập với tư cách là thành viên của không gian.
  • space.display_name: Hỗ trợ toán tử : (có) và lọc các không gian dựa trên một phần tên hiển thị khớp. Kết quả chỉ bao gồm 5 không gian phù hợp nhất. Ví dụ: space.display_name:Project tìm kiếm những tin nhắn trong 5 không gian hàng đầu có chứa từ "Dự án" trong tên hiển thị.
  • attachment: Hỗ trợ toán tử :* (có bất kỳ) để kiểm tra sự hiện diện của tệp đính kèm. Nếu bạn chỉ định attachment:*, thì chỉ những thông báo có ít nhất một tệp đính kèm mới được trả về.
  • annotations.user_mentions.user.name: Tên tài nguyên của người dùng được đề cập (users/{user}). Chỉ hỗ trợ : (có). Ví dụ: annotations.user_mentions.user.name:"users/1234567890" chỉ trả về những thông báo có nội dung đề cập đến người dùng được chỉ định. Ngoài ra, bạn có thể dùng bí danh me để lọc những tin nhắn đề cập đến người dùng gọi, ví dụ: annotations.user_mentions.user.name:users/me. Bạn cũng có thể sử dụng email này làm email đại diện cho {user}, ví dụ: users/example@gmail.com.

Để lọc nâng cao, bạn cũng có thể dùng các hàm sau:

  • has_link(): Chỉ trả về những tin nhắn có ít nhất một siêu liên kết trong nội dung tin nhắn.
  • is_unread(): Lọc bỏ những tin nhắn mà người dùng gọi đã đọc.

Để sử dụng bộ lọc space.display_name, thông tin đăng nhập gọi phải có một trong các phạm vi uỷ quyền sau:

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

Để sử dụng bộ lọc is_unread(), thông tin đăng nhập gọi phải có một trong các phạm vi uỷ quyền sau:

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

Trên nhiều trường, hệ thống chỉ hỗ trợ toán tử AND. Ví dụ hợp lệ là sender.name = "users/1234567890" AND is_unread(). Bạn không bắt buộc phải dùng từ AND và từ này sẽ được ngầm hiểu nếu bạn bỏ qua. Ví dụ: sender.name = "users/1234567890" is_unread() là hợp lệ và tương đương với ví dụ trước. Ví dụ không hợp lệ là sender.name = "users/1234567890" OR is_unread() vì OR không được hỗ trợ giữa các trường khác nhau.

Trong cùng một trường:

  • createTime chỉ hỗ trợ AND và chỉ có thể dùng để biểu thị một khoảng thời gian, chẳng hạn như createTime >= "2022-01-01T00:00:00+00:00" AND createTime < "2023-01-01T00:00:00+00:00".
  • sender.name chỉ hỗ trợ toán tử OR, ví dụ: sender.name = "users/1234567890" OR sender.name = "users/0987654321".
  • space.name chỉ hỗ trợ toán tử OR, ví dụ: space.name = "spaces/ABCDEFGH" OR space.name = "spaces/QWERTYUI".
  • space.display_name hỗ trợ các toán tử AND và OR, nhưng không hỗ trợ kết hợp cả hai. Ví dụ: space.display_name:Project AND space.display_name:Tasks trả về những tin nhắn trong các không gian có tên hiển thị chứa cả Project và Tasks, trong khi space.display_name:Project OR space.display_name:Tasks trả về những tin nhắn trong các không gian có tên hiển thị chứa Project hoặc Tasks hoặc cả hai.
  • annotations.user_mentions.user.name hỗ trợ các toán tử AND và OR, nhưng không hỗ trợ kết hợp cả hai. Ví dụ: annotations.user_mentions.user.name:"users/1234567890" AND annotations.user_mentions.user.name:"users/0987654321" chỉ trả về những tin nhắn đề cập đến cả hai người dùng, trong khi annotations.user_mentions.user.name:"users/1234567890" OR annotations.user_mentions.user.name:"users/0987654321" trả về những tin nhắn đề cập đến một hoặc cả hai người dùng.

Bạn phải dùng dấu ngoặc đơn để phân biệt thứ tự ưu tiên của toán tử khi kết hợp toán tử AND và OR trong cùng một truy vấn. Ví dụ: (sender.name="users/me" OR sender.name="users/123456") AND is_unread(). Nếu không, bạn không bắt buộc phải dùng dấu ngoặc đơn.

Các truy vấn mẫu sau đây là hợp lệ:

"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

Độ dài tối đa của cụm từ tìm kiếm là 1.000 ký tự.

Máy chủ sẽ từ chối các truy vấn không hợp lệ bằng lỗi INVALID_ARGUMENT.
pageSize

integer

Không bắt buộc. Số lượng kết quả tối đa cần trả về. Dịch vụ có thể trả về ít hơn giá trị này.

Nếu không chỉ định, tối đa 25 kết quả sẽ được trả về.

Giá trị tối đa là 100. Nếu bạn sử dụng giá trị lớn hơn 100, giá trị đó sẽ tự động thay đổi thành 100.
pageToken

string

Không bắt buộc. Một mã thông báo nhận được từ lệnh gọi tìm kiếm tin nhắn trước đó. Cung cấp thông số này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác được cung cấp phải khớp với lệnh gọi đã cung cấp mã thông báo trang. Việc truyền các giá trị khác nhau cho các tham số khác có thể dẫn đến kết quả không mong muốn.
orderBy

string

Không bắt buộc. Cách sắp xếp danh sách kết quả.

Các thuộc tính được hỗ trợ để sắp xếp theo là:

  • createTime: Sắp xếp kết quả theo thời gian tạo thông báo. Giá trị mặc định.
  • relevance: Sắp xếp kết quả theo mức độ liên quan.

Thứ tự mặc định là createTime desc. Chỉ hỗ trợ một thứ tự cho mỗi truy vấn (createTime hoặc relevance). Chỉ hỗ trợ thứ tự giảm dần (desc) và bạn phải chỉ định thứ tự này sau thuộc tính order.
view

enum (SearchMessagesView)

Không bắt buộc. Chỉ định loại chế độ xem kết quả tìm kiếm sẽ trả về. Mặc định là SEARCH_MESSAGES_VIEW_BASIC.

Nội dung phản hồi

Thông báo phản hồi cho việc tìm kiếm tin nhắn.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "results": [
    {
      object (SearchMessageResult)
    }
  ],
  "nextPageToken": string
}
Trường
results[]

object (SearchMessageResult)

Danh sách kết quả tìm kiếm khớp với cụm từ tìm kiếm.
nextPageToken

string

Một mã thông báo có thể dùng để truy xuất trang tiếp theo. Nếu trường này trống, tức là không có trang tiếp theo.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.

SearchMessagesView

Các loại khung hiển thị được hỗ trợ cho kết quả tìm kiếm một phần.

Enum
SEARCH_MESSAGES_VIEW_UNSPECIFIED Giá trị mặc định / chưa đặt. API sẽ mặc định ở chế độ xem CƠ BẢN.
SEARCH_MESSAGES_VIEW_BASIC Chỉ bao gồm những tin nhắn trùng khớp trong kết quả, nhưng không có siêu dữ liệu bổ sung. Đây là giá trị mặc định.
SEARCH_MESSAGES_VIEW_FULL Bao gồm mọi thứ trong kết quả: thư trùng khớp và siêu dữ liệu bổ sung.

SearchMessageResult

Một mục kết quả duy nhất từ một cụm từ tìm kiếm tin nhắn.

Biểu diễn dưới dạng JSON 
{
  "message": {
    object (Message)
  },
  "spaceMuteSetting": enum (MuteSetting),
  "read": boolean
}
Trường
message

object (Message)

Tin nhắn trùng khớp.
spaceMuteSetting

enum (MuteSetting)

Chế độ tắt tiếng của người dùng gọi cho không gian nơi tin nhắn được đăng. Ứng dụng gọi có thể dùng thông tin này để quyết định cách xử lý thông báo, tuỳ thuộc vào việc không gian có bị tắt tiếng đối với người dùng hay không.

Chỉ được trả về nếu chế độ xem yêu cầu là SEARCH_MESSAGES_VIEW_FULL và thông tin đăng nhập gọi bao gồm phạm vi uỷ quyền sau đây:

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

boolean

Cho biết liệu người dùng gọi có đọc được thông báo trùng khớp hay không.

Chỉ được trả về nếu chế độ xem yêu cầu là SEARCH_MESSAGES_VIEW_FULL và thông tin đăng nhập gọi bao gồm một trong các phạm vi uỷ quyền sau đây:

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