Trang này cung cấp thông tin tổng quan về API Sự kiện trên 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 trên Google Workspace cho biết các thay đổi đối với tài nguyên trên Google Workspace, chẳng hạn như thời điểm tạo, cập nhật hoặc xoá tài nguyên. Ứ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á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 nhận các sự kiện trên Google Workspace, hãy sử dụng API Sự kiện Google Workspace để tạo gói thuê bao cho các tài nguyên của Google Workspace.
Sau đây là cách API Sự kiện của Google Workspace phân phối sự kiện đến ứng dụng của bạn thông qua một gói thuê bao:
- Ứng dụng của bạn đăng ký một tài nguyên trong một ứng dụng của Google Workspace, chẳng hạn như không gian Google Chat.
- Tài nguyên bạn đã đăng ký sẽ thay đổi.
- Ứng dụng Google Workspace phân phối sự kiện về 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 Google Workspace của bạn. Sự kiện này chứa dữ liệu về những nội dung đã thay đổi trong tài nguyên.
- Ứng dụng của bạn sẽ xử lý thông báo 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ữ thường dùng trong API Sự kiện của Google Workspace:
- Sự kiện liên quan đế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à một sự kiện thuê bao hoặc một sự kiện trong vòng đời:
- Sự kiện đăng ký
- Thay đổi đối với tài nguyê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à 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 các sự kiện trên Google Workspace.
- Sự kiện trong vòng đời
- Một sự kiện về 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, nhờ đó, bạn có thể tránh bỏ lỡ các sự kiện của gói thuê bao. Theo mặc định, gói thuê bao của bạn sẽ 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 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 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. Gói thuê bao được xác định bởi những thông tin sau:- Tài nguyên mục tiêu
- Tài nguyên Google Workspace mà bạn muốn giám sát.
Tài nguyên này được thể hiện trong trường
targetResourcecủa gói thuê bao Google Workspace. Mỗi gói thuê bao chỉ có thể giám sát một tài nguyên. Để xem những tài nguyên của Google Workspace mà API Sự kiện Google Workspace hỗ trợ, hãy xem phần 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 thông báo về tài nguyên mục tiêu. Ví dụ: Nếu đã đăng ký một không gian Google Chat, bạn có thể chọn có nhận các sự kiện về không gian đó và tài nguyên con của không gian đó hay không, 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 mà gói thuê bao Google Workspace nhận sự kiện. API Sự kiện của Google Workspace hỗ trợ các chủ đề trên Google Cloud Pub/Sub dưới dạng một đ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 Google Workspace được hỗ trợ
Các 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 mục tiêu | Định dạng | Sự kiện được hỗ trợ | Giới hạn (nếu có) | |
|---|---|---|---|---|
| Google Chat | ||||
| Phòng Google Chat | //chat.googleapis.com/spaces/SPACE_ID |
Để biết thông tin chi tiết, hãy xem bài viết Đăng ký sự kiện trên Google Chat. |
Người dùng Google Chat uỷ quyền cho gói thuê bao phải là thành viên của không gian thông qua Google Workspace hoặc Tài khoản Google. | |
| Người dùng Google Chat | //cloudidentity.googleapis.com/users/USER_ID |
Để biết thông tin chi tiết, hãy xem bài viết Đăng ký sự kiện trên Google Chat. |
Gói thuê bao chỉ nhận các sự kiện về người dùng đã uỷ quyền gói thuê bao. Người dùng không thể thay mặt người dùng khác uỷ quyền cho gói thuê bao. |
|
| Google Meet | ||||
| Không gian họp trên Google Meet | //meet.googleapis.com/spaces/SPACE_ID |
Để 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 |
Để 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 sự kiện về không gian họp, trong đó người dùng là một trong những đối tượng 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 của CloudEvents. Đây là cách thức tiêu chuẩn của ngành để mô tả dữ liệu sự kiện. Các sự kiện Google Workspace bao gồm:
- Thuộc tính của CloudEvent.
- Dữ liệu về tài nguyên Google Workspace đã thay đổi do sự kiện này
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 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ụ: |
|---|---|---|
|
Loại dữ liệu đã được truyền trong sự kiện. |
|
|
Giá trị nhận dạng của CloudEvent. |
|
|
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
|
|
Phiên bản thông số kỹ thuật của CloudEvents được dùng cho sự kiện này. |
|
|
Tài nguyên của Google Workspace nơi diễn ra sự kiện. |
|
|
Dấu thời gian khi sự kiện diễn ra, ở định dạng RFC 3339. |
|
|
Loại sự kiện trên Google Workspace. |
|
Dữ liệu sự kiện
Dữ liệu sự kiện là tải trọng đại diện cho sự thay đổi đối với tài nguyên mục tiêu của gói thuê bao, bao gồm cả cá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 chứa dữ liệu về tài nguyên đã thay đổi hay chỉ nêu 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 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 tải trọng có tài nguyên spaces.message 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 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 bạn chọn đưa dữ liệu tài nguyên vào, thời hạn của gói thuê bao sẽ bị 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 của gói thuê bao 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 cách sử dụng tên tài nguyên.
Các lựa chọn này cho dữ liệu sự kiện được trình bày trong trường payloadOptions của gói thuê bao.
Sự kiện dưới dạng tin nhắn trên Google Cloud Pub/Sub
Các gói thuê bao API Sự kiện của Google Workspace sử dụng các chủ đề trên Google Cloud Pub/Sub làm điểm cuối thông báo sẽ nhận các sự kiện Google Workspace. Các sự kiện được mã hoá dưới dạng tin nhắn Google Cloud Pub/Sub. Ứng dụng của bạn có thể xử lý thông báo của 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 trên Google Cloud Pub/Sub chứa sự kiện về 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"
}
}
Lưu ý các trường sau:
attributes: 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 thông báo cập nhật trong không gian.data: Dữ liệu sự kiện với thông tin chi tiết về tài nguyênspaces.messageđã cập nhật, có định dạng dưới dạng chuỗi mã hoá Base64.messageId: Giá trị nhận dạng cho thông báo trên Google Cloud Pub/Sub.
Để tìm hiểu thêm về cách chỉ định CloudEvents trong các 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.
Chủ đề có liên quan
- Đăng ký sự kiện trên Google Chat
- Sự kiện trong vòng đời của gói thuê bao Google Workspace
- Chọn phạm vi API Sự kiện trên Google Workspace
- Tạo gói thuê bao của Google Workspace