Xử lý các sự kiện trên Google Chat

Trang này giải thích cách các ứng dụng Google Chat có thể nhận và phản hồi các sự kiện trong Google Chat.

Sự kiện trên Google Chat đại diện cho một hoạt động hoặc thay đổi trong Chat, chẳng hạn như tin nhắn mới trong một không gian. Ứng dụng Chat của bạn có thể sử dụng các sự kiện để hiểu rõ những gì đã xảy ra và thực hiện hành động hoặc phản hồi theo cách có ý nghĩa cho người dùng.

Dưới đây là một số ví dụ về cách bạn có thể sử dụng sự kiện:

  • Theo dõi và trả lời tin nhắn mới trong không gian, chẳng hạn như kiểm tra các từ khoá hoặc cụm từ chính.
  • Gửi tin nhắn chào mừng đến người dùng khi họ tham gia không gian để giải thích các nguyên tắc của không gian hoặc chia sẻ mẹo về cách sử dụng ứng dụng Chat một cách hiệu quả.
  • Theo dõi và phân tích hoạt động trên Chat. Ví dụ: để gửi báo cáo hằng tháng về thành viên mới hoặc những tin nhắn nhận được nhiều lượt bày tỏ cảm xúc hoặc lượt trả lời nhất.
  • Giao tiếp trên nhiều nền tảng nhắn tin. Ví dụ: người dùng có thể gửi và nhận tin nhắn từ người dùng trên một nền tảng nhắn tin khác mà không cần rời khỏi Chat.

Cách hoạt động của sự kiện

Bất cứ khi nào có sự kiện xảy ra trong Google Chat, một tài nguyên API Google Chat sẽ được tạo, cập nhật hoặc xoá. Chat sử dụng các sự kiện để cung cấp thông tin cho ứng dụng Chat về loại hoạt động đã xảy ra và tài nguyên API Chat bị ảnh hưởng.

Ví dụ về cách một tin nhắn được đăng lên phòng Google Chat kích hoạt một sự kiện.
Hình 1. Người dùng đăng tin nhắn trong một phòng Chat, từ đó tạo tài nguyên Message. Sau đó, Chat sẽ tạo một sự kiện chứa dữ liệu về tin nhắn mới.

Chat phân loại sự kiện theo loại. Loại sự kiện giúp bạn lọc và chỉ nhận loại thông tin bạn cần, đồng thời cho phép bạn xử lý các hoạt động tương tự theo cùng một cách.

Bảng sau đây cho biết mức độ ảnh hưởng của một hoạt động trong Chat đến tài nguyên API Chat có liên quan và loại sự kiện mà ứng dụng Chat của bạn nhận được:

Hoạt động Tài nguyên API Chat Loại sự kiện
Người dùng đăng tin nhắn trong phòng Chat Tài nguyên Message được tạo. Tin nhắn mới
Một người dùng trở thành người quản lý không gian. Tài nguyên Membership được cập nhật. Gói thành viên đã cập nhật
Người dùng bày tỏ cảm xúc về một tin nhắn. Tài nguyên Reaction được tạo. Lượt thể hiện cảm xúc mới
Người dùng rời khỏi không gian. Tài nguyên Membership bị xoá. Gói thành viên đã bị xoá

Nhận sự kiện từ Google Chat

Để nhận sự kiện, ứng dụng Chat có thể làm một trong hai việc sau:

  • Đăng ký nhận sự kiện bằng API Google Workspace Events để nhận sự kiện khi sự kiện xảy ra.
  • Truy vấn các sự kiện gần đây bằng cách gọi API Chat.

Bảng sau đây giải thích sự khác biệt và lý do để truy vấn hoặc đăng ký nhận sự kiện:

Đăng ký nhận sự kiện Truy vấn sự kiện
Trường hợp sử dụng
  • Xử lý hoặc phản hồi các sự kiện theo thời gian thực.
  • Theo dõi hoạt động của thành viên và khám phá các không gian mới để theo dõi.
  • Xử lý hoặc phản hồi các sự kiện theo định kỳ hoặc thông qua một điều kiện kích hoạt.
  • Tìm nạp các sự kiện bị bỏ lỡ từ một gói thuê bao (do ngừng hoạt động hoặc gói thuê bao không hoạt động).
API Google Workspace Events API Chat API
Nguồn sự kiện Không gian, người dùng và tổ chức Google Workspace ( Bản dùng trước cho nhà phát triển) Chỉ không gian
Sự kiện được hỗ trợ
  • Tin nhắn
  • Gói hội viên
  • Lượt thể hiện cảm xúc
  • Không gian

Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem phần Các loại sự kiện để tạo gói thuê bao trong tài liệu về API Google Workspace Events.
  • Tin nhắn
  • Gói hội viên
  • Lượt thể hiện cảm xúc
  • Không gian

Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem tài nguyên spaceEvents trong tài liệu tham khảo về API Chat.
Định dạng sự kiện Thông báo Google Cloud Pub/Sub, được định dạng theo quy cách của CloudEvent. Để biết thông tin chi tiết, hãy xem bài viết Cấu trúc của sự kiện trên Google Workspace. Tài nguyên API Chat ( spaces.spaceEvent)
Dữ liệu sự kiện Chuỗi được mã hoá Base64 có hoặc không có dữ liệu tài nguyên. Để xem tải trọng mẫu, hãy xem phần Dữ liệu sự kiện. Tải trọng JSON chứa dữ liệu tài nguyên. Một số loại sự kiện chỉ bao gồm một số trường tài nguyên nhất định. Để xem các tải trọng mẫu, hãy xem tài liệu tham khảo.

Ví dụ: Truy vấn hoặc đăng ký nhận thông tin về các sự kiện liên quan đến thành viên trong một không gian

Trong ví dụ này, một ứng dụng Chat muốn nhận thông tin về những thay đổi đối với thành viên của một không gian trong Chat. Trong không gian, hoạt động sau đây của thành viên sẽ diễn ra:

  • Người dùng tham gia không gian, tạo tài nguyên Membership và kích hoạt sự kiện thành viên mới.
  • Người dùng trở thành người quản lý không gian, việc này sẽ cập nhật tài nguyên Membership cho người dùng và kích hoạt sự kiện thành viên được cập nhật.
  • Người dùng rời khỏi không gian, thao tác này sẽ xoá tài nguyên Membership cho người dùng và kích hoạt sự kiện thành viên đã bị xoá.

Đăng ký nhận sự kiện về gói thành viên

Để nhận sự kiện theo thời gian thực, ứng dụng Chat sẽ gọi phương thức subscriptions.create() của API Sự kiện của Google Workspace để đăng ký không gian cho tất cả các loại sự kiện liên quan đến thành viên. Sau khi tạo gói thuê bao, ứng dụng Chat có thể bắt đầu nhận các sự kiện về thành viên.

Ứng dụng Chat đăng ký nhận sự kiện bằng API Google Workspace Events.
Hình 2. Ứng dụng Chat nhận các sự kiện về thành viên thông qua một gói thuê bao bằng API Google Workspace Events.

Trong hình 2, ứng dụng Chat có một gói thuê bao đang hoạt động cho không gian, vì vậy, ứng dụng sẽ nhận được một sự kiện bất cứ khi nào có thay đổi về thành viên trong không gian. Sau đó, ứng dụng Chat có thể xử lý hoặc phản hồi theo thời gian thực đối với bất kỳ hoạt động nào, chẳng hạn như đăng tin nhắn chào mừng riêng tư cho thành viên đã tham gia không gian.

Để tìm hiểu về cách tạo gói thuê bao bằng API Google Workspace Events, hãy xem tài liệu về API Google Workspace Events.

Truy vấn các sự kiện gần đây về gói thành viên

Thay vì nhận các sự kiện về thành viên khi chúng xảy ra, một ứng dụng Chat có thể gọi API Chat để liệt kê các sự kiện gần đây trong không gian liên quan đến hoạt động của thành viên.

Ứng dụng Chat truy vấn các sự kiện bằng API Chat.
Hình 3. Ứng dụng Chat nhận các sự kiện gần đây về thành viên bằng cách truy vấn các sự kiện trong không gian thông qua API Chat.

Trong hình 3, một ứng dụng Chat gọi phương thức spaces.spaceEvents.list() của API Chat sau khi tất cả hoạt động liên quan đến thành viên đã diễn ra, đồng thời lọc truy vấn để tìm các sự kiện thành viên mới, được cập nhật và bị xoá. API Chat sẽ trả về một danh sách tài nguyên spaceEvent đại diện cho từng thay đổi về thành viên. Sau đó, ứng dụng Chat có thể xử lý hoặc phản hồi dựa trên hoạt động gần đây, chẳng hạn như đăng tin nhắn hằng tuần kèm theo thông tin tóm tắt về hoạt động của thành viên trong không gian trong 7 ngày qua.

Để truy vấn sự kiện bằng API Chat, hãy xem bài viết Liệt kê sự kiện trong không gian Google Chat.

Giới hạn và hành vi phân phối

Các hạn chế chung

  • Để nhận sự kiện về thành viên, người dùng hoặc ứng dụng Chat phải là thành viên trực tiếp của không gian. Nếu họ được thêm, cập nhật hoặc xoá gián tiếp khỏi một không gian thông qua một nhóm trên Google Groups, thì gói thuê bao sẽ không nhận được các sự kiện về thành viên đó. Để tìm hiểu cách hoạt động của tư cách thành viên trong nhóm trên Google Groups, hãy xem bài viết Thêm một nhóm trên Google Groups vào một không gian.

Gói thuê bao của người dùng

  • Đối với gói thuê bao cho người dùng, các sự kiện về thành viên mới trong tin nhắn trực tiếp hoặc cuộc trò chuyện nhóm chưa đặt tên (google.workspace.chat.membership.v1.created) chỉ kích hoạt sau khi tin nhắn đầu tiên được đăng.

Gói thuê bao của khách hàng

Đối với gói thuê bao của khách hàng, các giới hạn sau đây sẽ được áp dụng:

  • Tổ chức Google Workspace phải có ít nhất một giấy phép SKU Enterprise.
  • Một ứng dụng Chat chỉ có thể tạo một gói thuê bao khách hàng cho một tổ chức Google Workspace nhất định. Một tổ chức Google Workspace có thể có tổng cộng tối đa 5 gói thuê bao của khách hàng (do các ứng dụng Chat khác nhau tạo).

Đối với gói thuê bao của khách hàng, việc phân phối sự kiện tuân theo các quy tắc chung sau:

  • Sự kiện trong không gian: Chỉ được gửi nếu sự kiện xảy ra trong một không gian do tổ chức Google Workspace của bạn quản lý.
  • Sự kiện của người dùng: Chỉ được gửi nếu sự kiện xảy ra với một người dùng thuộc tổ chức Google Workspace của bạn.

Trường hợp ngoại lệ duy nhất đối với các quy tắc này là sự kiện dành cho hội viên. Gói thuê bao của bạn có thể nhận sự kiện về thành viên từ cả không gian do tổ chức của bạn quản lý và không gian do tổ chức bên ngoài quản lý, nhưng cách phân phối sự kiện phụ thuộc vào tổ chức quản lý không gian:

Không gian do tổ chức Google Workspace của bạn quản lý

Nếu có sự thay đổi về thành viên trong một không gian do tổ chức Google Workspace quản lý, thì sự thay đổi đó sẽ được phân phối dưới dạng sự kiện trong không gian.

Tên tài nguyên của một sự kiện trong không gian sử dụng định dạng sau:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Không gian do các tổ chức bên ngoài quản lý

Nếu tư cách thành viên của một người dùng do tổ chức Google Workspace của bạn quản lý thay đổi trong một không gian do một tổ chức bên ngoài quản lý (ví dụ: một không gian có tên bên ngoài hoặc một tin nhắn trực tiếp do một người dùng bên ngoài tạo), thì gói thuê bao của bạn sẽ nhận được sự kiện này dưới dạng sự kiện của người dùng.

Tên tài nguyên của sự kiện người dùng sử dụng định dạng sau:

users/{userId}/userEvents/{userEventId}