Trang này được dịch bởi Cloud Translation API.

Đă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 bạn có thể sử dụng API này để đă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 các tài nguyên của Google Workspace, chẳng hạn như khi 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 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 các sự kiện

Để cho phép ứng dụng của bạn nhận các sự kiện trên Google Workspace, bạn có thể dùng Google Workspace Events API để tạo các gói thuê bao cho tài nguyên trê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 các sự kiện đến một ứng dụng Chat.

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

Một ứng dụng Chat đăng ký theo dõi một phòng Chat.
Những thay đổi đối với không gian trên Chat. Ví dụ: một tin nhắn mới được đăng trong phòng.
Chat gửi một sự kiện đến một chủ đề trong Google Cloud Pub/Sub. Chủ đề này đó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 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

Sau đây là danh sách các thuật ngữ thường dùng trong Google Workspace Events API:

Sự kiện Google Workspace

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

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

Tài nguyên đích đến: 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 Google Workspace. Mỗi thuê bao chỉ có thể giám sát một tài nguyên. Để biết API Sự kiện của Google Workspace hỗ trợ những tài nguyên nào của Google Workspace, hãy xem phần Các sự kiện được hỗ trợ của 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 về tài nguyên đích. Ví dụ: nếu đã đăng ký theo dõi một không gian trên Google Chat, bạn có thể chọn nhận hoặc không nhận các sự kiện về không gian đó và các tài nguyên con của không gian đó, chẳng hạn như tư cách 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 được các 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.
Các lựa chọn về 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ợ trên Google Workspace

Những sự kiện mà ứng dụng của bạn có thể nhận được phụ thuộc vào tài nguyên mục tiêu của gói thuê bao. Bảng sau đây cho thấy 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 đích đến	Sự kiện được hỗ trợ
Phòng Google Chat	Tin nhắn Hội viên Lượt thể hiện cảm xúc Không gian
Người dùng Google Chat	Hội viên
Tệp trên Google Drive	Tệp Đề xuất cấp quyền truy cập
Bộ nhớ dùng chung trên Google Drive	Tệp Đề xuất cấp quyền truy cập
Không gian họp trên Google Meet	Hội nghị Phiên của người tham gia Bản ghi âm Bản chép lời
Người dùng Google Meet	Hội nghị Phiên của người tham gia Bản ghi âm 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 các sự kiện trên Google Workspace

Các sự kiện trên Google Workspace tuân theo quy cách CloudEvents, đây là một cách mô tả dữ liệu sự kiện theo tiêu chuẩn ngành. Các sự kiện trên Google Workspace có những thông tin 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 các sự kiện trên Google Workspace.

Thuộc tính CloudEvent

Các sự kiện trên Google Workspace có những 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 các sự kiện trê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 đặc 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 diễn ra.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Dấu thời gian khi sự kiện diễn 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 đăng ký theo dõi một không gian trên Chat, bạn có thể nhận được các sự kiện về tin nhắn mới trong không gian đó. Đối với các sự kiện về tin nhắn mới, dữ liệu sự kiện chứa một tải trọng có tài nguyên spaces.message Chat đã được tạo.

Khi tạo một 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:

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 chọn thêm dữ liệu tài nguyên, thì thời hạn đăng ký của bạn sẽ bị giới hạn tối đa là 4 giờ hoặc 24 giờ nếu bạn sử dụng quyền uỷ 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 thuê bao của bạn là tối đa 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 lựa chọn này cho dữ liệu sự kiện được thể hiện 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

Các 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 các 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 minh hoạ 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 một không gian 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"
    }
}

Lưu ý các trường sau:

attributes: Các thuộc tính cho CloudEvent, bao gồm cả loại sự kiện. Trong trường hợp này, sự kiện là về một tin nhắn mới trong không gian.
data: Dữ liệu sự kiện có 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 một chuỗi được mã hoá Base64.
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 của 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.