Đă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 để đă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.

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 API Sự kiện của Google Workspace phân phối sự kiện đến một ứ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 với một ứng dụng Google Chat thông qua một gói thuê bao:

  1. Một ứng dụng Chat đăng ký một phòng Chat.
  2. Phòng Chat thay đổi. Ví dụ: một tin nhắn mới được đăng trong không gian đó.
  3. 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.
  4. Ứ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 Subscription nguồ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 targetResource củ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 Định dạng Sự kiện được hỗ trợ Các giới hạn (nếu có)
Google Chat
Phòng Google Chat

Cách đăng ký theo dõi một không gian cụ thể:

//chat.googleapis.com/spaces/SPACE_ID

Cách đăng ký tất cả không gian nơi người dùng là thành viên:

//chat.googleapis.com/spaces/-
  • Tin nhắn
  • Hội viên
  • Lượt thể hiện cảm xúc
  • Không gian

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký nhận sự kiện trên Google Chat.		 Người dùng Google Chat cho phép gói thuê bao phải trở thành thành viên của không gian thông qua Google Workspace hoặc Google Tài khoản.
Người dùng Google Chat //cloudidentity.googleapis.com/users/USER_ID
  • Hội viên

Để biết thông tin chi tiết, hãy xem bài viết Đăng ký nhận sự kiện trên Google Chat.

Gói thuê bao chỉ nhận được các sự kiện về người dùng đã uỷ quyền cho gói thuê bao đó. Người dùng không thể uỷ quyền một gói thuê bao thay mặt cho người dùng khác.
Google Meet
Không gian họp trên Google Meet //meet.googleapis.com/spaces/SPACE_ID
  • Hội nghị
  • Phiên chia sẻ với người tham gia
  • Bản ghi âm
  • Bản chép lời

Để 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
  • Hội nghị
  • Phiên chia sẻ với người tham gia
  • Bản ghi âm
  • Bản chép lời

Để 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 nhận được các sự kiện về không gian họp có nơi người dùng là một trong những người dùng sau:

  • Chủ sở hữu không gian họp.
  • Người tổ chức về sự kiện trên Lịch Google liên kết với không gian họp.

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:

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ụ:

datacontenttype

Loại dữ liệu đã truyền trong sự kiện.

application/json

id

Giá trị nhận dạng của 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 đượ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, theo đị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à 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ên spaces.message, được định dạng dưới dạng 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.