Đă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ề Google Workspace Events API và giải thích cách sử dụng API để đăng ký nhận sự kiện trên Google Workspace.

Sự kiện Google Workspace thể hiện những thay đổi đối với tài nguyên Google Workspace, chẳng hạn như khi tài nguyên được tạo, cập nhật hoặc xoá. Hãy sử dụng Google Workspace Events API để đăng ký nhận tài nguyên Google Workspace và nhận các sự kiện có liên quan.

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 sự kiện Google Workspace, hãy sử dụng Google Workspace Events API để tạo gói thuê bao cho tài nguyên Google Workspace.

Hình minh hoạ cách Google Workspace Events API phân phối các sự kiện. — **Hình 1.** Ví dụ về cách Google Workspace Events API gửi sự kiện đến một ứng dụng Google Chat.

Ví dụ sau đây mô tả cách Google Workspace Events API gửi sự kiện đến một ứng dụng Chat thông qua gói thuê bao:

Một ứng dụng Chat đăng ký nhận một không gian Google Chat.
Phòng Chat thay đổi. Ví dụ: một tin nhắn mới được đăng trong không gian.
Chat gửi một sự kiện đến 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ề tin nhắn mới, sự kiện này chứa thông tin chi tiết về tài nguyên Message được tạo.
Ứng dụng Chat xử lý thông báo 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

Các thuật ngữ thường dùng trong Google Workspace Events API bao gồm:

Sự kiện Google Workspace

Một thay đổi đối với tài nguyên Google Workspace. Các sự kiện được định dạng bằng cách sử dụng thông số kỹ thuật CloudEvents và có thể là một sự kiện gói thuê bao hoặc một sự kiện trong vòng đời:

Sự kiện gói thuê bao: Một thay đổi đối với tài nguyên Google Workspace mà bạn đang theo dõi, chẳng hạn như một tin nhắn mới trong phòng Chat. Bạn có thể chỉ định mức độ chi tiết mà bạn muốn nhận về tài nguyên đã thay đổi. Để biết thông tin chi tiết, hãy xem Cấu trúc của sự kiện Google Workspace.
Sự kiện trong vòng đời: Một sự kiện về gói thuê bao của Google Workspace. Sự kiện vòng đời 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 không bỏ lỡ sự kiện gói thuê bao. Theo mặc định, gói thuê bao của bạn luôn nhận được sự kiện vòng đời. Để biết thông tin chi tiết, hãy xem phần Sự kiện vòng đời cho gói thuê bao Google Workspace.

Gói thuê bao của Google Workspace

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

Tài nguyên mục tiêu: Tài nguyên Google Workspace mà bạn muốn theo dõi. Tài nguyên này được biểu thị trong trường targetResource của Gói thuê bao của 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 Google Workspace mà Google Workspace Events API hỗ trợ, hãy xem phần Sự kiện Google Workspace được hỗ trợ.
Loại sự kiện: Các loại thay đổi mà bạn muốn nhận thông báo về tài nguyên mục tiêu. Ví dụ: nếu đã đăng ký nhận một phòng Chat, bạn có thể chọn nhận sự kiện về phòng Chat và tài nguyên con của phòng Chat đó, chẳng hạn như thành viên và tin nhắn.
Điểm cuối thông báo: Điểm cuối nơi gói thuê bao Google Workspace nhận sự kiện. Google Workspace Events API hỗ trợ các chủ đề Google Cloud Pub/Sub làm đ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.

Sự kiện Google Workspace được hỗ trợ

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

Tài nguyên mục tiêu	Sự kiện được hỗ trợ
Không gian Chat	Tin nhắn Hội viên Lượt thể hiện cảm xúc Không gian
Người dùng Chat	Hội viên
Tệp Google Drive hoặc tệp trong bộ nhớ dùng chung	Đề xuất quyền truy cập Phê duyệt Bình luận Tệp Số lượt trả lời
Không gian họp và người dùng Google Meet	Hội nghị Phiên của người tham gia Bản ghi âm Ghi chú thông minh Bản dùng trước cho nhà phát triển Bản chép lời

Để tìm hiểu thêm, hãy xem các hướng dẫn sau:

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

Sự kiện Google Workspace tuân theo thông số kỹ thuật CloudEvents, đây là một cách mô tả dữ liệu sự kiện theo tiêu chuẩn ngành. Sự kiện Google Workspace chứa những nội dung sau:

Thuộc tính của CloudEvent.
Dữ liệu về tài nguyên Google Workspace đã thay đổi do sự kiện

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 sự kiện Google Workspace.

Thuộc tính CloudEvent

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

Thuộc tính	Mô tả	Ví dụ:
`datacontenttype`	Loại dữ liệu đã được truyền trong sự kiện.	`application/json`
`id`	Giá trị nhận dạng cho CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	Nguồn của sự kiện. Đối với sự kiện 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, ở định dạng RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	Loại sự kiệ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 sự 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 có gói thuê bao cho 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 sự kiện về tin nhắn mới, dữ liệu sự kiện chứa một tải trọng với tài nguyên spaces.message Chat đã được tạo.

Khi tạo 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 của bạn nhận được.

Dữ liệu tài nguyên	Tải trọng	Thời gian hết hạn của gói thuê bao
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.	Tối đa 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.	Tối đa 7 ngày

Các tuỳ chọn này cho 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 thông báo Google Cloud Pub/Sub

Gói thuê bao Google Workspace Events API sử dụng các chủ đề Google Cloud Pub/Sub làm điểm cuối thông báo nhận sự kiện Google Workspace. Các sự kiện được mã hoá dưới dạng thông báo Google Cloud Pub/Sub. Ứng dụng của bạn có thể xử lý thông báo Google Cloud Pub/Sub để thực hiện 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 Google Cloud Pub/Sub chứa một sự kiện về tin nhắn đã cập nhật trong 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"
    }
}

Ví dụ này chứa 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 là về một tin nhắn đã cập nhật trong không gian.
data: Dữ liệu sự kiện có thông tin chi tiết về tài nguyên đã cập nhật, được định dạng dưới dạng chuỗi được mã hoá Base64.spaces.message
messageId: Giá trị nhận dạng cho thông báo Google Cloud Pub/Sub.

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

Đăng ký nhận sự kiện bằng Google Workspace Events API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.