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ề 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 Google Workspace thể hiện các 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á. Ứ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 sự kiện

Để cho phép ứng dụng nhận sự kiện Google Workspace, bạn sử dụng API Sự kiện Google Workspace để tạo gói thuê bao cho tài nguyên 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 Google Workspace Events API phân phối sự kiện đến ứng dụng Chat.

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

Ứng dụng Chat đăng ký một phòng Chat.
Không gian Chat thay đổi. Ví dụ: một tin nhắn mới được đăng trong không gian.
Chat sẽ phân phố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ề nội dung đã thay đổi. Ví dụ: đối với một sự kiện về thông báo mới, sự kiện đó sẽ 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ữ phổ biến được 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 Google Workspace. 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 vòng đời:

Sự kiện đăng ký: Thay đổi đối với tài nguyên Google Workspace mà bạn đang theo dõi, chẳng hạn như tin nhắn mới trong không gian 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 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 để 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 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 theo dõi tài nguyên từ ứng dụng Google Workspace. Gói thuê bao được biểu thị bằng 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 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 Google Workspace. Mỗi gói thuê bao chỉ có thể giám sát một tài nguyên. Để biết API Sự kiện Google Workspace hỗ trợ tài nguyên Google Workspace nào, hãy xem phần Các sự kiện Google Workspace được hỗ trợ.
Loại sự kiện: Các loại thay đổi mà bạn muốn được thông báo về tài nguyên mục tiêu. Ví dụ: nếu đã đăng ký một không gian trên Google Chat, bạn có thể chọn nhận hoặc không nhận 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ư gói 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. API Sự kiện Google Workspace hỗ trợ các chủ đề 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.
Các tuỳ 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

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	Các sự kiện được hỗ trợ
Phòng trên 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
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 sự kiện trên Google Workspace

Các sự kiện của Google Workspace tuân theo quy cách 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 trong Google Workspace chứa 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 Google Workspace chứa các thuộc tính CloudEvents bắt buộc sau:

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 thông số kỹ thuật CloudEvents 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 trên Google Workspace.	`google.workspace.chat.message.v1.created`

Dữ liệu sự kiện

Dữ liệu sự kiện là 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ý một không gian 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 với tài nguyên Chat spaces.message đã đượ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ó 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 tài nguyên đã thay đổi. Nếu bạn chọn đưa dữ liệu tài nguyên vào, thì thời hạn thuê bao sẽ bị giới hạn ở 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. Thời hạn gói 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 tuỳ 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 API Sự kiện của Google Workspace sử dụng chủ đề Google Cloud Pub/Sub làm điểm cuối thông báo nhận sự kiện của 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ề thông báo đã cập nhật trong 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"
    }
}

Hãy 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 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 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 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 bài viết Liên kết giao thức Google Cloud Pub/Sub cho CloudEvents.

Đăng ký sự kiện trên Google Chat
Đăng ký sự kiện trên Google Meet
Sự kiện trong vòng đời của gói thuê bao Google Workspace
Chọn phạm vi Google Workspace Events API
Tạo gói thuê bao Google Workspace