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 để đăng ký các sự kiện trên Google Workspace.
Sự kiện trong Google Workspace thể hiện những thay đổi đối với tài nguyên trong 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ý vào một tài nguyên của Google Workspace để bạn nhận được các sự kiện liên quan 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 sự kiện trên Google Workspace, bạn hãy sử dụng Google Workspace Events API để tạo gói thuê bao cho Google Workspace của chúng tôi.
Trong ví dụ sau, đây là cách API Sự kiện của Google Workspace phân phối sự kiện với một ứng dụng Google Chat thông qua một gói thuê bao:
- Một ứng dụng Chat đăng ký một phòng Chat.
- Phòng Chat thay đổi. Ví dụ: một tin nhắn mới được đăng trong không gian đó.
- Chat cung cấp 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. Sự kiện
chứa dữ liệu về những nội dung đã thay đổi. Ví dụ: đối với sự kiện về
thông báo, sự kiện chứa thông tin chi tiết về tài nguyên
Messageđã tạo. - Ứng dụng Chat sẽ xử lý Google Cloud Thông báo 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 được sử 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. Sự kiện được định dạng bằng cách sử dụng CloudEvents và có thể là sự kiện đăng ký hoặc một 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 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 giá trị thông tin 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 trong 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 trong 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 có thể để tránh bỏ lỡ các sự kiện đăng ký. Theo mặc định, gói thuê bao của bạn luôn nhận 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 một tài nguyên trong Google Workspace . Mỗi gói thuê bao được biểu thị bằng một
Subscriptionnguồn. 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 biểu thị trong trường
targetResourcecủa Gói thuê bao của Google Workspace. Mỗi gói thuê bao chỉ có thể giám sát một tài nguyên. Để xem tài nguyên nào của Google Workspace API Sự kiện của Google Workspace được hỗ trợ, hãy xem bài viết sau 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 được thông báo tài nguyên mục tiêu. Ví dụ: nếu bạn đã đăng ký một phòng Google Chat, bạn có thể chọn có nhận sự kiện về không gian và tài nguyên con của không gian đó, chẳng hạn như gói thành viên và thông báo.
- Điểm cuối thông báo
- Điểm cuối mà Gói thuê bao của Google Workspace nhận được sự kiện. Chiến lược phát hành đĩa đơn API Sự kiện của Google Workspace hỗ trợ các chủ đề trong Google Cloud Pub/Sub như 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, 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 của bạn. 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 tiềm năng.
| Tài nguyên mục tiêu | Sự kiện được hỗ trợ |
|---|---|
| Phòng Google Chat |
|
| Người dùng Google Chat |
|
| Không gian họp trên Google Meet |
|
| Người dùng Google Meet |
|
Để 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 trong Google Workspace
Các sự kiện trên Google Workspace tuân theo nội dung CloudEvents quy cách, là cách mô tả dữ liệu sự kiện theo tiêu chuẩn của ngành. Google Workspace sự kiện chứa các 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 Sự kiện trên Google Workspace.
Thuộc tính CloudEvent
Sự kiện trong Google Workspace có những thông tin bắt buộc sau Các thuộc tính CloudEvents:
| Thuộc tính | Mô tả | Ví dụ: |
|---|---|---|
|
Loại dữ liệu đã 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 CloudEvents được dùng cho sự kiện này. |
|
|
Tài nguyên Google Workspace nơi sự kiện xảy ra. |
|
|
Dấu thời gian khi sự kiện xảy ra, theo đị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à một tải trọng thể hiện một thay đổi đối với mục tiêu của gói thuê bao tài nguyên của bạn, 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 có muốn tải trọng bao gồm dữ liệu về tài nguyên đã thay đổi hay chỉ là 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 không gian. Đố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 dữ liệu với Chat
Tài nguyên spaces.message đã đượ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 bao gồm trong 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 nội dung đã thay đổi nguồn. Nếu bạn chọn bao gồm dữ liệu tài nguyên, gói thuê bao của bạn thời lượng bị giới hạn ở mức tối đa 4 giờ hoặc 24 giờ nếu bạn sử dụng toàn miền uỷ quyền.
- Loại trừ dữ liệu tài nguyên: Chỉ chứa tên của nội dung thay đổi nguồn. Thời hạn đăng ký của bạn tối đa là 7 ngày. Để xem 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 tuỳ chọn này đối với dữ liệu sự kiện được thể hiện trong 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 Google Cloud Pub/Sub chủ đề làm điểm cuối thông báo nhận Google Workspace sự kiện. 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ý tin nhắn 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 của Google Cloud Pub/Sub có chứa sự kiện về một 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"
}
}
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 là về một thông báo đã cập nhật trong .data: Dữ liệu sự kiện chứa thông tin chi tiết về sự kiện đã cập nhật Tài nguyênspaces.message, có định dạng là một 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 chỉ định CloudEvents trong Google Cloud Pub/Sub hãy xem phần Liên kết giao thức Google Cloud Pub/Sub cho CloudEvents.