Đăng ký nhận sự kiện bằng Google Workspace Events API

Trang này cung cấp thông tin tổng quan về API Sự kiện của Google Workspace và giải thích cách bạn có thể sử dụng API này để đăng ký các sự kiện trên Google Workspace.

Sự kiện trong Google Workspace thể hiện các thay đổi đối với tài nguyên của Google Workspace, chẳng hạn như thời điểm tài nguyên được tạo, cập nhật hoặc xoá. Ứng dụng của bạn có thể đăng ký một tài nguyên trên Google Workspace để nhận các sự kiện liên quan mà bạn quan tâm.

Cách ứng dụng của bạn nhận sự kiện

Để cho phép ứng dụng của bạn nhận các sự kiện của Google Workspace, bạn phải sử dụng API Sự kiện của Google Workspace để tạo gói thuê bao cho các tài nguyên của Google Workspace.

Hình minh hoạ cách API Sự kiện của Google Workspace phân phối sự kiện.
Hình 1. Ví dụ về cách API Sự kiện của Google Workspace phân phối sự kiện cho ứng dụng Chat.

Trong ví dụ sau, dưới đây là cách API Sự kiện của Google Workspace phân phối các sự kiện đến ứng dụng Google Chat thông qua một gói thuê bao:

  1. Một ứng dụng Chat đăng ký một phòng Chat.
  2. Phòng Chat thay đổi. Ví dụ: một tin nhắn mới được đăng trong không gian.
  3. Chat gửi một sự kiện cho một chủ đề trong Google Cloud Pub/Sub, đóng vai trò là điểm cuối thông báo cho gói thuê bao. Sự kiện này chứa dữ liệu về những nội dung thay đổi. Ví dụ: đối với một sự kiện về một thông báo mới, sự kiện đó chứa thông tin chi tiết về tài nguyên Message đã được tạo.
  4. Ứng dụng Chat sẽ xử lý tin nhắn trên Google Cloud Pub/Sub chứa sự kiện và thực hiện hành động, nếu cần.

Thuật ngữ quan trọng

Sau đây là danh sách các thuật ngữ phổ biến dùng trong API Sự kiện của Google Workspace:

Sự kiện trên Google Workspace

Thay đổi đối với tài nguyên trên Google Workspace. Các sự kiện được định dạng bằng thông số kỹ thuật CloudEvents và có thể là sự kiện đăng ký hoặc sự kiện trong vòng đời:

Sự kiện liên quan đến gói thuê bao
Sự thay đổi đối với tài nguyên trên Google Workspace mà bạn đang giám sát, chẳng hạn như một tin nhắn mới trong phòng Google Chat. Bạn có thể chỉ định mức độ chi tiết mà mình muốn nhận về tài nguyên đã thay đổi. Để biết thông tin chi tiết, hãy xem phần Cấu trúc của các sự kiện trong Google Workspace.
Sự kiện trong vòng đời
Một sự kiện về gói thuê bao của Google Workspace. Các sự kiện trong vòng đời sẽ thông báo cho bạn về các vấn đề và trạng thái của gói thuê bao để bạn có thể tránh bỏ lỡ các sự kiện liên quan đến gói thuê bao. Theo mặc định, gói thuê bao của bạn luôn nhận được các sự kiện trong vòng đời. Để biết thông tin chi tiết, hãy xem bài viết Các sự kiện trong vòng đời của gói thuê bao Google Workspace.
Gói thuê bao của Google Workspace

Một thực thể có tên giám sát một tài nguyên từ một ứng dụng của Google Workspace. Gói thuê bao được biểu thị bằng một tài nguyên Subscription. Một gói thuê bao được xác định dựa trên những thông tin sau:

Tài nguyên mục tiêu
Tài nguyên trên Google Workspace mà bạn muốn theo dõi. Tài nguyên này được thể hiện trong trường targetResource của gói thuê bao Google Workspace. Mỗi gói thuê bao chỉ có thể theo dõi một tài nguyên. Để xem những tài nguyên nào trên Google Workspace mà API Sự kiện của Google Workspace hỗ trợ, hãy xem Các sự kiện được hỗ trợ trên Google Workspace.
Loại sự kiện
Các loại thay đổi mà bạn muốn nhận được thông báo đối với tài nguyên mục tiêu. Ví dụ: nếu đã đăng ký một phòng Google Chat, bạn có thể chọn nhận hoặc không nhận sự kiện về không gian đó và tài nguyên phụ, chẳng hạn như gói thành viên và tin nhắn.
Điểm cuối thông báo
Điểm cuối mà gói thuê bao Google Workspace nhận được sự kiện. API Sự kiện của Google Workspace hỗ trợ các chủ đề của Google Cloud Pub/Sub dưới dạng điểm cuối thông báo. Để tìm hiểu thêm về cách sử dụng Google Cloud Pub/Sub, hãy xem tài liệu về Google Cloud Pub/Sub.
Tuỳ chọn tải trọng
Dữ liệu sự kiện mà bạn muốn nhận về các tài nguyên đã thay đổi.

Các sự kiện được hỗ trợ trong Google Workspace

Các sự kiện mà ứng dụng của bạn có thể nhận được sẽ phụ thuộc vào tài nguyên mục tiêu của gói thuê bao. Bảng sau đây trình bày các sự kiện được hỗ trợ cho mỗi tài nguyên mục tiêu có thể có.

Tài nguyên mục tiêu Định dạng Sự kiện được hỗ trợ Các giới hạn (nếu có)
Google Chat
Phòng Google Chat

Cách đăng ký theo dõi một không gian cụ thể:

//chat.googleapis.com/spaces/SPACE_ID

Cách đăng ký tất cả không gian nơi người dùng là thành viên:

//chat.googleapis.com/spaces/-
  • Tin nhắn
  • Hội viên
  • Lượt thể hiện cảm xúc
  • Không gian

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký nhận sự kiện trên Google Chat.		 Người dùng Google Chat cho phép gói thuê bao phải là thành viên của không gian thông qua Tài khoản Google Workspace hoặc Tài khoản Google của họ.
Người dùng Google Chat //cloudidentity.googleapis.com/users/USER_ID
  • Hội viên

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký nhận sự kiện trên Google Chat.

Gói thuê bao chỉ nhận được các sự kiện về người dùng đã uỷ quyền cho gói thuê bao đó. Người dùng không thể uỷ quyền một gói thuê bao thay mặt cho người dùng khác.
Google Meet
Không gian họp trên Google Meet //meet.googleapis.com/spaces/SPACE_ID
  • Hội nghị
  • Phiên chia sẻ với người tham gia
  • Bản ghi âm
  • Bản chép lời

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký sự kiện trên Google Meet.
Người dùng Google Meet //cloudidentity.googleapis.com/users/USER_ID
  • Hội nghị
  • Phiên chia sẻ với người tham gia
  • Bản ghi âm
  • Bản chép lời

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký sự kiện trên Google Meet.

Gói thuê bao này sẽ nhận được các sự kiện về không gian tổ chức cuộc họp có người dùng là một trong những đối tượng sau đây:

  • Chủ sở hữu không gian họp.
  • Người tổ chức của sự kiện trên Lịch Google được liên kết với không gian họp.

Cấu trúc của các sự kiện trong Google Workspace

Các sự kiện trong Google Workspace tuân theo quy cách của CloudEvents, đây là cách mô tả dữ liệu sự kiện theo tiêu chuẩn ngành. Các sự kiện của Google Workspace chứa những nội dung sau:

Phần sau đây giải thích cấu trúc của các thuộc tính và dữ liệu cho các sự kiện trong Google Workspace.

Thuộc tính CloudEvent

Các sự kiện của Google Workspace chứa các thuộc tính CloudEvents bắt buộc sau đây:

Thuộc tính Nội dung mô tả Ví dụ:

datacontenttype

Loại dữ liệu đã truyền trong sự kiện.

application/json

id

Giá trị nhận dạng của CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

Nguồn của sự kiện. Đối với các sự kiện của Google Workspace, đây là tên tài nguyên đầy đủ của gói thuê bao. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

Phiên bản thông số kỹ thuật CloudEvents được dùng cho sự kiện này.

1.0

subject

Tài nguyên Google Workspace nơi sự kiện xảy ra.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

Dấu thời gian khi sự kiện xảy ra, theo định dạng RFC 3339.

2023-09-07T21:37:36.260127Z

type

Loại sự kiện trên Google Workspace.

google.workspace.chat.message.v1.created

Dữ liệu sự kiện

Dữ liệu sự kiện là một tải trọng thể hiện một thay đổi đối với tài nguyên mục tiêu của gói thuê bao, bao gồm cả tài nguyên con của tài nguyên mục tiêu. Trong gói thuê bao, bạn có thể chỉ định xem bạn muốn tải trọng bao gồm dữ liệu về tài nguyên đã thay đổi hay chỉ tên của tài nguyên đã thay đổi.

Ví dụ: nếu đã đăng ký một phòng Chat, bạn có thể nhận sự kiện về tin nhắn mới trong phòng đó. Đối với các sự kiện về tin nhắn mới, dữ liệu sự kiện sẽ chứa một tải trọng có tài nguyên spaces.message của Chat đã được tạo.

Khi tạo một gói thuê bao, bạn có thể chỉ định lượng dữ liệu tài nguyên được đưa vào các sự kiện mà ứng dụng nhận được:

  • Bao gồm dữ liệu tài nguyên: Chứa một số hoặc tất cả các trường của tài nguyên đã thay đổi. Nếu bạn chọn thêm dữ liệu tài nguyên, thì thời hạn của gói thuê bao sẽ được giới hạn tối đa là 4 giờ, hoặc 24 giờ nếu bạn sử dụng tính năng uỷ quyền trên toàn miền.
  • Loại trừ dữ liệu tài nguyên: Chỉ chứa tên của tài nguyên đã thay đổi. Thời hạn đăng ký của bạn tối đa là 7 ngày. Để biết thông tin chi tiết về sự kiện, bạn có thể truy vấn tài nguyên bằng tên tài nguyên.

Các tuỳ chọn này về dữ liệu sự kiện được biểu thị trong trường payloadOptions của gói thuê bao.

Sự kiện dưới dạng tin nhắn Google Cloud Pub/Sub

Các gói thuê bao Google Workspace Events API sử dụng các chủ đề của Google Cloud Pub/Sub làm điểm cuối thông báo nhận các sự kiện trong Google Workspace. Các sự kiện được mã hoá dưới dạng thông báo của Google Cloud Pub/Sub. Ứng dụng của bạn có thể xử lý thông báo trên Google Cloud Pub/Sub để hành động hoặc phản hồi sự kiện.

Ví dụ sau đây cho thấy một thông báo trên Google Cloud Pub/Sub có chứa sự kiện về một tin nhắn đã cập nhật trong một phòng Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Xin lưu ý các trường sau:

  • attributes: Thuộc tính cho CloudEvent, bao gồm loại sự kiện. Trong trường hợp này, sự kiện liên quan đến một thông báo đã cập nhật trong không gian.
  • data: Dữ liệu sự kiện chứa thông tin chi tiết về tài nguyên spaces.message đã cập nhật, được định dạng dưới dạng chuỗi được mã hoá Base64.
  • messageId: Giá trị nhận dạng của thông báo Google Cloud Pub/Sub.

Để tìm hiểu thêm về cách CloudEvents được chỉ định trong thông báo của Google Cloud Pub/Sub, hãy xem bài viết Liên kết giao thức Google Cloud Pub/Sub cho CloudEvents.