Tạo gói thuê bao của Google Workspace

Trang này giải thích cách sử dụng API Google Workspace Events để tạo gói thuê bao cho một tài nguyên của Google Workspace. Gói thuê bao Google Workspace cho phép ứng dụng của bạn nhận thông tin về các sự kiện trên Google Workspace, thể hiện những thay đổi đối với tài nguyên của Google Workspace. Để tìm hiểu về những tài nguyên và loại sự kiện mà Google Workspace Events API hỗ trợ, hãy xem bài viết Tổng quan về Google Workspace Events API.

Trang này bao gồm các bước sau để tạo gói thuê bao Google Workspace:

  1. Thiết lập môi trường.
  2. Tạo và đăng ký một chủ đề Google Cloud Pub/Sub. Hãy sử dụng tài liệu này làm điểm cuối để nhận các sự kiện của Google Workspace.
  3. Gọi phương thức create của Google Workspace Events API trên tài nguyên Subscription.
  4. Kiểm tra gói thuê bao Google Workspace để xác minh rằng chủ đề Pub/Sub của bạn nhận được các sự kiện mà bạn đã đăng ký.
  5. Bạn có thể định cấu hình cách đẩy sự kiện đến một điểm cuối cho ứng dụng của mình để ứng dụng có thể xử lý sự kiện và thực hiện hành động nếu cần.

Điều kiện tiên quyết

Apps Script

  • Cách sử dụng các lệnh Google Cloud CLI trong hướng dẫn này:
    1. Cài đặt Google Cloud CLI.
    2. Để khởi động CLI gcloud, hãy chạy mã sau:
      3.   gcloud init
  • Một dự án Apps Script:
    • Sử dụng dự án trên đám mây của Google thay vì dự án mặc định do Apps Script tự động tạo.
    • Đối với tất cả phạm vi mà bạn đã thêm để định cấu hình màn hình xin phép bằng OAuth, bạn cũng phải thêm các phạm vi đó vào tệp appsscript.json trong dự án Apps Script. Ví dụ: nếu bạn đã chỉ định phạm vi chat.messages, hãy thêm phạm vi sau: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • Bật dịch vụ nâng cao Google Workspace Events.

Python

  • Python 3.6 trở lên
  • Công cụ quản lý gói pip
  • Thư viện ứng dụng mới nhất của Google cho Python. Để cài đặt hoặc cập nhật các công cụ này, hãy chạy lệnh sau trong giao diện dòng lệnh: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • Cách sử dụng các lệnh Google Cloud CLI trong hướng dẫn này:
    1. Cài đặt Google Cloud CLI.
    2. Để khởi động CLI gcloud, hãy chạy mã sau:
      3.   gcloud init

Thiết lập môi trường

Phần sau đây giải thích cách thiết lập môi trường trước khi tạo gói thuê bao Google Workspace.

Bật Google Workspace Events API và Google Cloud Pub/Sub API

Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.

Google Cloud Console

Trong Google Cloud Console, hãy mở dự án trên đám mây của Google cho ứng dụng của bạn rồi bật API Google Workspace Events và API Pub/Sub:

Bật API

gcloud

  1. Trong thư mục đang làm việc, hãy đăng nhập vào Tài khoản Google của bạn:

    gcloud auth login

  2. Đặt dự án của bạn thành dự án trên đám mây cho ứng dụng:

    gcloud config set project PROJECT_ID

    Thay thế PROJECT_ID bằng mã dự án cho dự án trên đám mây cho ứng dụng của bạn.

  3. Bật Google Workspace Events API và Google Cloud Pub/Sub API:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

Tạo thông tin đăng nhập mã ứng dụng khách OAuth

Chọn loại ứng dụng để xem hướng dẫn cụ thể về cách tạo mã ứng dụng khách OAuth:

Ứng dụng web

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Application type (Loại ứng dụng) > Web application (Ứng dụng web).
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Thêm các URI được uỷ quyền liên quan đến ứng dụng của bạn:
    • Ứng dụng phía máy khách (JavaScript) – Trong phần Nguồn gốc JavaScript được uỷ quyền, hãy nhấp vào Thêm URI. Sau đó, hãy nhập một URI để dùng cho các yêu cầu của trình duyệt. Thông tin này xác định những miền mà ứng dụng của bạn có thể gửi yêu cầu API đến máy chủ OAuth 2.0.
    • Ứng dụng phía máy chủ (Java, Python, v.v.) – Trong phần URI chuyển hướng được uỷ quyền, hãy nhấp vào Thêm URI. Sau đó, hãy nhập một URI điểm cuối mà máy chủ OAuth 2.0 có thể gửi phản hồi.
  6. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  7. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần Mã ứng dụng khách OAuth 2.0.

    Xin lưu ý rằng khoá bí mật của ứng dụng khách không được dùng cho ứng dụng web.

Android

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Loại ứng dụng > Android.
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Trong trường Tên gói, hãy nhập tên gói từ tệp AndroidManifest.xml.
  6. Trong trường Dấu vân tay chứng chỉ SHA-1, hãy nhập dấu vân tay chứng chỉ SHA-1 đã tạo.
  7. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  8. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

iOS

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Loại ứng dụng > iOS.
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Trong trường Mã nhận dạng gói, hãy nhập giá trị nhận dạng gói như được liệt kê trong tệp Info.plist của ứng dụng.
  6. Không bắt buộc: Nếu ứng dụng của bạn xuất hiện trong Apple App Store, hãy nhập mã App Store.
  7. Không bắt buộc: Trong trường Mã nhóm, hãy nhập chuỗi 10 ký tự duy nhất do Apple tạo và chỉ định cho nhóm của bạn.
  8. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  9. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

Ứng dụng Chrome

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Loại ứng dụng > tiện ích Chrome.
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Trong trường Mã mặt hàng, hãy nhập chuỗi mã nhận dạng duy nhất gồm 32 ký tự của ứng dụng. Bạn có thể tìm thấy giá trị mã nhận dạng này trong URL của ứng dụng trên Cửa hàng Chrome trực tuyến và trong Trang tổng quan dành cho nhà phát triển Cửa hàng Chrome trực tuyến.
  6. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  7. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

Ứng dụng dành cho máy tính

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Loại ứng dụng > Ứng dụng dành cho máy tính.
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  6. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

TV và thiết bị đầu vào hạn chế

  1. Trong Google Cloud Console, hãy chuyển đến Trình đơn > Nền tảng xác thực của Google > Ứng dụng.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Loại ứng dụng > TV và thiết bị đầu vào hạn chế.
  4. Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google Cloud Console.
  5. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  6. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

Universal Windows Platform (UWP)

  1. Trong Google API Console, hãy chuyển đến biểu tượng Trình đơn > > Ứng dụng khách.

    Chuyển đến mục Ứng dụng

  2. Nhấp vào Create Client (Tạo ứng dụng).
  3. Nhấp vào Application type (Loại ứng dụng) > Universal Windows Platform (UWP) (Nền tảng Windows chung (UWP)).
  4. Trong trường "Tên", hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google API Console.
  5. Trong trường "Mã cửa hàng", hãy nhập giá trị Mã cửa hàng Microsoft gồm 12 ký tự duy nhất của ứng dụng. Bạn có thể tìm thấy mã nhận dạng này trong URL của ứng dụng trên Microsoft Store và trong Partner Center.
  6. Không bắt buộc: Nếu ứng dụng của bạn là một tác nhân AI thực hiện hành động thay mặt cho người dùng, hãy chọn Sử dụng ứng dụng khách này cho tác nhân dựa trên AI. Nếu ứng dụng của bạn hỗ trợ cả quy trình của tác nhân AI và các tính năng tiêu chuẩn cho người dùng, hãy tạo ứng dụng OAuth riêng cho từng quy trình. Bạn không thể thay đổi chế độ cài đặt này sau khi tạo ứng dụng.
  7. Nhấp vào Tạo.

    Thông tin xác thực mới tạo sẽ xuất hiện trong phần "Mã ứng dụng khách OAuth 2.0".

Tải tệp JSON chứa mật khẩu ứng dụng khách xuống

Tệp khoá bí mật của ứng dụng khách là một bản trình bày JSON của thông tin đăng nhập mã ứng dụng khách OAuth mà ứng dụng của bạn có thể tham chiếu khi cung cấp thông tin đăng nhập.

  1. Trong Google API Console, hãy chuyển đến biểu tượng Trình đơn > API và dịch vụ > Thông tin xác thực.

    Chuyển đến trang Thông tin xác thực

  2. Trong phần Mã ứng dụng khách OAuth 2.0, hãy nhấp vào mã ứng dụng khách mà bạn đã tạo.

  3. Nhấp vào Tải tệp JSON xuống.

  4. Lưu tệp dưới dạng credentials.json.

Tạo và đăng ký một chủ đề Pub/Sub

Trong phần này, bạn sẽ tạo một chủ đề Pub/Sub và gói thuê bao cho chủ đề đó. Chủ đề Pub/Sub đóng vai trò là điểm cuối thông báo, nơi gói thuê bao Google Workspace của bạn nhận được các sự kiện.

Để tìm hiểu thêm về cách tạo và quản lý chủ đề Pub/Sub, hãy xem tài liệu về Pub/Sub.

Cách tạo và đăng ký một chủ đề Pub/Sub:

Bảng điều khiển API của Google

  1. Trong Google API Console, hãy chuyển đến trang Pub/Sub:

    Chuyển đến Google Cloud Pub/Sub

    Đảm bảo bạn đã chọn dự án trên đám mây cho ứng dụng của mình.

  2. Nhấp vào Tạo chủ đề rồi làm như sau:

    1. Nhập tên cho chủ đề, chẳng hạn như workspace-events-topic.
    2. Chọn Thêm gói thuê bao mặc định. Pub/Sub đặt tên cho gói thuê bao mặc định này tương tự như tên chủ đề của bạn, chẳng hạn như workspace-events-topic-sub.
    3. Không bắt buộc: Cập nhật hoặc định cấu hình thêm thuộc tính cho chủ đề.

  3. Nhấp vào Tạo. Tên đầy đủ của chủ đề có định dạng là projects/PROJECT_ID/topics/TOPIC_ID. Sử dụng tên đầy đủ này trong bước sau.

  4. Cấp quyền truy cập để xuất bản thông báo Pub/Sub cho chủ đề của bạn:

    1. Trên trang của chủ đề, hãy chuyển đến bảng điều khiển bên rồi mở thẻ Quyền.
    2. Nhấp vào Add Principal (Thêm người dùng chính).
    3. Trong trường Thêm người dùng chính, hãy thêm tài khoản dịch vụ cho ứng dụng Google Workspace phân phối sự kiện đến gói thuê bao của bạn:
      1. Đối với các sự kiện trong Chat, hãy xem chat-api-push@system.gserviceaccount.com.
      2. Đối với các sự kiện trên Drive, hãy xem drive-api-event-push@system.gserviceaccount.com.
      3. Đối với sự kiện trên Meet, hãy xem meet-api-event-push@system.gserviceaccount.com.
    4. Trong trình đơn Chỉ định vai trò, hãy chọn Pub/Sub Publisher.
    5. Nhấp vào Lưu. Có thể mất vài phút để cập nhật quyền cho chủ đề của bạn.

gcloud

  1. Trong dự án trên đám mây, hãy tạo một chủ đề bằng cách chạy lệnh sau:

    gcloud pubsub topics create TOPIC_ID

    Thay thế TOPIC_ID bằng một mã nhận dạng duy nhất cho chủ đề của bạn, chẳng hạn như workspace-events-topic.

    Kết quả sẽ hiển thị tên đầy đủ của chủ đề, được định dạng là projects/PROJECT_ID/topics/TOPIC_ID. Ghi lại tên và đảm bảo giá trị cho PROJECT_ID là mã dự án trên đám mây cho ứng dụng của bạn. Sử dụng tên chủ đề trong bước sau và để tạo gói thuê bao Google Workspace sau này.

  2. Cấp quyền xuất bản thông báo cho chủ đề của bạn:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

    Thay thế nội dung sau:

    • TOPIC_NAME: Tên đầy đủ của chủ đề, là kết quả của bước trước. Định dạng là projects/PROJECT_ID/topics/TOPIC_ID.

    • GOOGLE_WORKSPACE_APPLICATION: Ứng dụng Google Workspace phải phân phối sự kiện đến gói thuê bao của bạn:

      • Để nhận sự kiện từ Chat, hãy sử dụng một trong các tài khoản dịch vụ sau:
      • Để nhận sự kiện từ Drive, hãy sử dụng drive-api-event-push@system.gserviceaccount.com.
      • Để nhận sự kiện từ Meet, hãy sử dụng meet-api-event-push@system.gserviceaccount.com.

    Có thể mất vài phút để cập nhật quyền cho chủ đề của bạn.

  3. Tạo gói thuê bao Pub/Sub cho chủ đề:

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

    Thay thế nội dung sau:

    • SUBSCRIPTION_NAME: Tên cho gói thuê bao của bạn, chẳng hạn như workspace-events-subscription.
    • TOPIC_NAME: Tên chủ đề mà bạn đã tạo ở bước trước.

Đăng ký tài nguyên của Google Workspace

Trong phần này, bạn đăng ký tài nguyên Google Workspace mà bạn muốn theo dõi sự kiện.

Chọn và xác định tài nguyên mục tiêu

Trong gói thuê bao Google Workspace, tài nguyên mục tiêu là tài nguyên Google Workspace mà bạn theo dõi để biết các sự kiện. Tài nguyên mục tiêu được thể hiện trong trường targetResource của gói thuê bao, được định dạng bằng tên đầy đủ của tài nguyên. Ví dụ: đối với một gói thuê bao giám sát không gian Chat (spaces/AAAABBBBBBB), giá trị của targetResource là //chat.googleapis.com/spaces/AAAABBBBBBB.

Xác định tài nguyên mục tiêu cho Chat

Tài nguyên mục tiêu Định dạng Giới hạn
Không gian

//chat.googleapis.com/spaces/SPACE

trong đó SPACE là mã nhận dạng trong tên tài nguyên của tài nguyên space trong API Chat. Bạn có thể lấy mã nhận dạng từ URL của không gian hoặc bằng cách sử dụng phương thức spaces.list().

 Người dùng Chat hoặc ứng dụng Chat uỷ quyền cho gói thuê bao phải là thành viên của không gian thông qua Tài khoản Google hoặc tài khoản Google Workspace của họ. Hỗ trợ:
Tất cả không gian của một người dùng

//chat.googleapis.com/spaces/-

 Gói thuê bao chỉ nhận được sự kiện cho những không gian mà người dùng là thành viên thông qua tài khoản Google Workspace hoặc Tài khoản Google của họ. Chỉ hỗ trợ phương thức xác thực người dùng.
Người dùng

//cloudidentity.googleapis.com/users/USER

trong đó USER là mã nhận dạng trong tên tài nguyên của tài nguyên user trong API Chat. Để biết thông tin chi tiết, hãy xem bài viết Xác định và chỉ định người dùng 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 cho một gói thuê bao thay mặt cho người dùng khác. Chỉ hỗ trợ phương thức xác thực người dùng.
Khách hàng ( Bản dùng trước cho nhà phát triển)

//admin.googleapis.com/customers/CUSTOMER

trong đó CUSTOMER là mã khách hàng. Bạn cũng có thể sử dụng bí danh my_customer cho miền tùy chỉnh của ứng dụng Chat.

Gói thuê bao nhận được sự kiện cho tất cả không gian và người dùng do miền của khách hàng quản lý. Chỉ hỗ trợ phương thức xác thực ứng dụng có sự phê duyệt của quản trị viên.

Xác định tài nguyên mục tiêu cho Drive

Tài nguyên mục tiêu Định dạng Các hạn chế (nếu có)
Tệp //drive.googleapis.com/files/FILE

trong đó FILE là mã nhận dạng trong tên tài nguyên của tài nguyên files trong API Drive. Bạn có thể lấy mã nhận dạng từ URL của tệp hoặc bằng cách sử dụng phương thức files.list.

Người dùng uỷ quyền cho gói thuê bao phải có quyền đối với tệp trong gói thuê bao liên quan đến sự kiện đăng ký.
Bộ nhớ dùng chung //drive.googleapis.com/drives/DRIVE

trong đó DRIVE là mã nhận dạng trong tên tài nguyên của tài nguyên drives trong API Drive. Bạn có thể lấy mã nhận dạng từ URL của ổ đĩa hoặc bằng cách sử dụng phương thức drives.list.

Gói thuê bao chỉ nhận được sự kiện cho các mục trong bộ nhớ dùng chung mà người dùng là thành viên thông qua Tài khoản Google Workspace hoặc Tài khoản Google của họ.

Xác định tài nguyên mục tiêu cho Meet

Tài nguyên mục tiêu Định dạng Các hạn chế (nếu có)
Không gian của cuộc họp //meet.googleapis.com/spaces/SPACE

trong đó SPACE là mã nhận dạng trong tên tài nguyên của tài nguyên spaces của Meet API REST. Để biết thông tin chi tiết, hãy xem phần Cách Meet xác định không gian họp.
Người dùng //cloudidentity.googleapis.com/users/USER

trong đó USER là mã nhận dạng trong trường signedinUser.user của tài nguyên participants trong API REST của Meet. Để biết thông tin chi tiết, hãy xem bài viết Làm việc với người tham gia.

Gói thuê bao nhận được sự kiện về tất cả không gian họp mà người dùng là chủ sở hữu của không gian họp đó. Thông thường, chủ sở hữu không gian họp cũng là người tổ chức sự kiện trên Lịch Google liên kết với không gian họp.

Tạo gói thuê bao Google Workspace

Để tạo gói thuê bao, hãy sử dụng phương thức subscriptions.create của API Google Workspace Events để tạo tài nguyên Subscription. Chỉ định các trường sau:

  • targetResource: Một Google Workspace mà bạn đã xác định trong phần trước, được định dạng bằng tên tài nguyên đầy đủ.
  • eventTypes: Một mảng gồm một hoặc nhiều loại sự kiện mà bạn muốn nhận về tài nguyên. Ví dụ: nếu ứng dụng của bạn chỉ cần biết về tin nhắn mới được đăng lên một không gian trong Chat, thì ứng dụng chỉ cần đăng ký nhận sự kiện về tin nhắn đã tạo.
  • notificationEndpoint: Điểm cuối thông báo nơi gói thuê bao Google Workspace của bạn gửi các sự kiện. Sử dụng chủ đề Pub/Sub mà bạn đã tạo trong phần trước.
  • payloadOptions: Các lựa chọn để chỉ định lượng dữ liệu tài nguyên cần đưa vào tải trọng sự kiện. Cấu hình này ảnh hưởng đến thời gian hết hạn của gói thuê bao. Để tìm hiểu thêm, hãy xem bài viết Dữ liệu sự kiện.

Cách tạo gói thuê bao Google Workspace:

Apps Script

  1. Trong dự án Apps Script, hãy tạo một tệp tập lệnh mới có tên là createSubscription rồi thêm mã sau:

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

    Thay thế nội dung sau:

    • TARGET_RESOURCE: Tài nguyên Google Workspace mà bạn đang đăng ký, được định dạng dưới dạng tên tài nguyên đầy đủ. Ví dụ: để đăng ký một không gian Chat có mã không gian là AAAABBBB, hãy sử dụng //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Một hoặc nhiều loại sự kiện mà bạn muốn đăng ký trong tài nguyên mục tiêu. Định dạng dưới dạng một mảng chuỗi, chẳng hạn như 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Tên đầy đủ của chủ đề Pub/Sub mà bạn đã tạo trong dự án trên đám mây của mình. Có định dạng là projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA: Một giá trị boolean chỉ định liệu gói thuê bao có bao gồm dữ liệu tài nguyên trong tải trọng hay không:

      • True: Bao gồm tất cả dữ liệu tài nguyên. Để giới hạn các trường được đưa vào, hãy thêm trường fieldMask và chỉ định ít nhất một trường cho tài nguyên đã thay đổi. Chỉ các gói thuê bao tài nguyên Chat mới hỗ trợ việc đưa dữ liệu tài nguyên vào.
      • False: Loại trừ dữ liệu tài nguyên.

  2. Để tạo gói thuê bao Google Workspace, hãy chạy hàm createSubscription trong dự án Apps Script của bạn.

Python

  1. Trong thư mục đang hoạt động, hãy tạo một tệp có tên là create_subscription.py rồi thêm mã sau:

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

    Thay thế nội dung sau:

    • SCOPES: Một hoặc nhiều phạm vi OAuth hỗ trợ từng loại sự kiện cho gói thuê bao. Được định dạng dưới dạng một mảng chuỗi. Để liệt kê nhiều phạm vi, hãy phân tách bằng dấu phẩy. Ví dụ: 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • TARGET_RESOURCE: Tài nguyên Google Workspace mà bạn đang đăng ký, được định dạng dưới dạng tên tài nguyên đầy đủ. Ví dụ: để đăng ký một không gian Chat có mã không gian là AAAABBBB, hãy sử dụng //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Một hoặc nhiều loại sự kiện mà bạn muốn đăng ký trong tài nguyên mục tiêu. Định dạng dưới dạng một mảng chuỗi, chẳng hạn như 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Tên đầy đủ của chủ đề Pub/Sub mà bạn đã tạo trong dự án trên đám mây của mình. Có định dạng là projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA: Một giá trị boolean chỉ định liệu gói thuê bao có bao gồm dữ liệu tài nguyên trong tải trọng hay không:

      • True: Bao gồm tất cả dữ liệu tài nguyên. Để giới hạn các trường được đưa vào, hãy thêm trường fieldMask và chỉ định ít nhất một trường cho tài nguyên đã thay đổi. Chỉ các gói thuê bao tài nguyên Chat mới hỗ trợ việc thêm dữ liệu tài nguyên.
      • False: Loại trừ dữ liệu tài nguyên.

  2. Để tạo gói thuê bao Google Workspace, hãy chạy lệnh sau trong thiết bị đầu cuối:

    python3 create_subscription.py

API Google Workspace Events trả về một thao tác chạy trong thời gian dài đã hoàn tất, chứa thực thể của tài nguyên Subscription mà bạn đã tạo.

Kiểm tra gói thuê bao Google Workspace

Để kiểm tra xem bạn có đang nhận được sự kiện trên Google Workspace hay không, bạn có thể kích hoạt một sự kiện và lấy thông báo cho gói thuê bao Pub/Sub.

Cách kiểm tra gói thuê bao Google Workspace:

Bảng điều khiển API của Google

  1. Kích hoạt một hoặc nhiều loại sự kiện trong tài nguyên mục tiêu của gói thuê bao Google Workspace. Ví dụ: nếu bạn đã đăng ký nhận tin nhắn mới trong một phòng Chat, hãy đăng một tin nhắn lên phòng đó.

  2. Trong Google API Console, hãy chuyển đến trang Pub/Sub:

    Chuyển đến Pub/Sub

    Đảm bảo bạn đã chọn dự án trên đám mây cho ứng dụng của mình.

  3. Trong trình đơn Pub/Sub, hãy nhấp vào Subscriptions (Gói thuê bao).

  4. Trong bảng, hãy tìm gói thuê bao Pub/Sub cho chủ đề của bạn rồi nhấp vào tên gói thuê bao.

  5. Nhấp vào thẻ Tin nhắn.

  6. Nhấp vào Pull (Kéo). Có thể mất đến vài phút để một sự kiện tạo ra một thông báo Pub/Sub.

gcloud

  1. Kích hoạt một hoặc nhiều loại sự kiện trong tài nguyên mục tiêu của gói thuê bao Google Workspace. Ví dụ: nếu bạn đã đăng ký nhận tin nhắn mới trong một phòng Chat, hãy đăng một tin nhắn trong phòng đó.

  2. Chạy lệnh sau:

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

    Thay thế nội dung sau:

    • PUBSUB_SUBSCRIPTION_NAME: Tên đầy đủ của gói thuê bao Pub/Sub, được định dạng là projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
    • MESSAGE_COUNT: Số lượng thông báo Pub/Sub tối đa mà bạn muốn lấy.

    Có thể mất đến vài phút để một sự kiện tạo ra thông báo Pub/Sub.

Đối với mỗi sự kiện Google Workspace mà bạn kích hoạt, một thông báo sẽ được gửi đến gói thuê bao Pub/Sub của bạn, trong đó có chứa sự kiện đó. Để biết thông tin chi tiết, hãy xem bài viết Nhận sự kiện dưới dạng thông báo của Google Cloud Pub/Sub.

Định cấu hình cách ứng dụng nhận sự kiện

Gói thuê bao Pub/Sub mà bạn tạo là gói thuê bao dựa trên phương thức kéo. Sau khi thử nghiệm gói thuê bao Pub/Sub, bạn có thể cập nhật loại phân phối để thay đổi cách ứng dụng nhận sự kiện. Ví dụ: bạn có thể định cấu hình gói thuê bao Pub/Sub thành loại phân phối đẩy để ứng dụng của bạn có thể nhận sự kiện trực tiếp đến một điểm cuối của ứng dụng.

Để tìm hiểu về cách định cấu hình gói thuê bao Pub/Sub, hãy xem tài liệu về Pub/Sub.

Đăng ký nhận sự kiện trong không gian Chat dưới dạng ứng dụng Google Chat

Bạn có thể đăng ký nhận sự kiện trong Chat dưới dạng một ứng dụng Chat trong không gian mà ứng dụng Chat đó là thành viên. Ứng dụng Chat không thể đăng ký nhận sự kiện của người dùng.

Viết một tập lệnh gọi API Google Workspace Events

Sau đây là cách tạo gói thuê bao cho các sự kiện trong không gian Chat bằng quy trình xác thực ứng dụng và phê duyệt của quản trị viên:

  1. Nếu cần, hãy Tạo ứng dụng Chat.

  2. Đăng ký một tài nguyên Chat, nhưng:

    1. Thay vì xác thực người dùng, hãy xác thực dưới dạng ứng dụng Chat với sự phê duyệt một lần của quản trị viên.

    2. Chỉ định phạm vi uỷ quyền cho phép ứng dụng Chat đăng ký nhận sự kiện trên Chat. Các phạm vi uỷ quyền này luôn bắt đầu bằng chat.app và bao gồm:

      • https://www.googleapis.com/auth/chat.app.memberships: Đăng ký nhận thông tin về các sự kiện liên quan đến thành viên trong không gian Chat.
      • https://www.googleapis.com/auth/chat.app.memberships.readonly: Đăng ký nhận thông báo về sự kiện của thành viên trong không gian Chat.
      • https://www.googleapis.com/auth/chat.app.messages.readonly: Đăng ký nhận tin nhắn và sự kiện phản ứng trong không gian Chat.
      • https://www.googleapis.com/auth/chat.app.spaces: Đăng ký nhận sự kiện trong không gian Chat.
      • https://www.googleapis.com/auth/chat.app.spaces.readonly: Đăng ký nhận thông báo về các sự kiện trong không gian Chat.

Mã mẫu sau đây đăng ký nhận sự kiện tin nhắn trong một không gian Chat cụ thể:

Python 

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

Thay thế nội dung sau:

  • SPACE_ID: Tên không gian mà bạn có thể lấy từ phương thức spaces.list trong API Chat hoặc từ URL của không gian.
  • TOPIC_NAME: Tên đầy đủ của chủ đề Pub/Sub mà bạn đã tạo trong dự án trên đám mây của mình. Có định dạng là projects/PROJECT_ID/topics/TOPIC_ID.

  • RESOURCE_DATA: Một giá trị boolean chỉ định liệu gói thuê bao có bao gồm dữ liệu tài nguyên trong tải trọng hay không:

    • True: Bao gồm tất cả dữ liệu tài nguyên. Để giới hạn các trường được đưa vào, hãy thêm trường fieldMask và chỉ định ít nhất một trường cho tài nguyên đã thay đổi. Chỉ các gói thuê bao tài nguyên Chat mới hỗ trợ việc đưa dữ liệu tài nguyên vào.
    • False: Loại trừ dữ liệu tài nguyên.

Đăng ký nhận tất cả sự kiện trong Chat trong một tổ chức trên Google Workspace dưới dạng một ứng dụng Google Chat

Gói thuê bao của khách hàng cho phép ứng dụng Chat của bạn theo dõi các sự kiện trong không gian và sự kiện của người dùng trên toàn bộ tổ chức Google Workspace.

Để biết thông tin chi tiết về cách phân phối sự kiện cho gói thuê bao của khách hàng, bao gồm cả việc phân phối sự kiện trong không gian do các tổ chức bên ngoài quản lý, hãy xem bài viết Các hạn chế và hành vi phân phối của gói thuê bao của khách hàng.

Yêu cầu và giới hạn

  • Xác thực: Xác thực dưới dạng ứng dụng Chat với sự phê duyệt một lần của quản trị viên
  • SKU: Tổ chức Google Workspace phải có ít nhất một giấy phép SKU Enterprise. Xin lưu ý rằng yêu cầu này không được thực thi nghiêm ngặt trong giai đoạn Chương trình dùng thử cho nhà phát triển, nhưng sẽ được thực thi trong tương lai (sẽ được thông báo riêng).
  • Tính duy nhất: Một ứng dụng Chat chỉ có thể tạo một gói thuê bao của khách hàng cho một tổ chức Google Workspace nhất định. Một tổ chức Google Workspace có thể có tổng cộng tối đa 5 gói thuê bao của khách hàng (do các ứng dụng Chat khác nhau tạo).
  • Phạm vi: Cần có một hoặc nhiều phạm vi sau đây, tuỳ thuộc vào loại sự kiện bạn muốn nhận:
    • https://www.googleapis.com/auth/chat.app.all.spaces.readonly: Để nhận sự kiện về không gian.
    • https://www.googleapis.com/auth/chat.app.all.memberships.readonly: Để nhận sự kiện về gói thành viên.
    • https://www.googleapis.com/auth/chat.app.all.messages.readonly: Để nhận sự kiện về tin nhắn và phản ứng.
    • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly ( Bản dùng trước cho nhà phát triển): Để nhận sự kiện về trạng thái đọc của người dùng.

Tạo gói thuê bao cho khách hàng

Để tạo gói thuê bao cho khách hàng, hãy gọi phương thức subscriptions.create.

Mã mẫu Python sau đây tạo một gói thuê bao của khách hàng:

Python 

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)

Thay thế nội dung sau:

  • CUSTOMER_ID: Mã khách hàng. Bạn cũng có thể sử dụng bí danh my_customer cho tổ chức Google Workspace của ứng dụng Chat.
  • TOPIC_NAME: Tên đầy đủ của chủ đề Pub/Sub mà bạn đã tạo trong dự án trên đám mây. Được định dạng là projects/PROJECT_ID/topics/TOPIC_ID.
  • RESOURCE_DATA: Một giá trị boolean chỉ định liệu gói thuê bao có bao gồm dữ liệu tài nguyên trong tải trọng hay không:
    • True: Bao gồm tất cả dữ liệu tài nguyên. Để giới hạn các trường được đưa vào, hãy thêm trường fieldMask và chỉ định ít nhất một trường cho tài nguyên đã thay đổi. Chỉ những gói thuê bao tài nguyên Chat mới hỗ trợ việc thêm dữ liệu tài nguyên.
    • False: Loại trừ dữ liệu tài nguyên.