Khắc phục lỗi và kích hoạt lại gói thuê bao Google Workspace

Trang này giải thích cách kích hoạt lại gói thuê bao Google Workspace bị tạm ngưng bằng cách giải quyết hoặc khắc phục lỗi và gọi phương thức subscriptions.reactivate.

Các gói thuê bao Google Workspace sẽ bị tạm ngưng bất cứ khi nào có lỗi khiến gói thuê bao không nhận được sự kiện. Ví dụ: một thuê bao sẽ bị tạm ngưng khi không tìm thấy tài nguyên mục tiêu hoặc điểm cuối thông báo của thuê bao đó. Sau khi giải quyết mọi lỗi liên quan đến gói thuê bao, bạn có thể kích hoạt lại gói thuê bao để bắt đầu nhận lại các sự kiện.

Bạn có thể tìm hiểu về gói thuê bao bị tạm ngưng theo những cách sau:

  • Ứng dụng của bạn nhận được một sự kiện trong vòng đời về việc tạm ngưng. Nếu gói thuê bao của bạn bị tạm ngưng do lỗi với điểm cuối, thì có thể bạn sẽ không nhận được sự kiện vòng đời.
  • Bạn sử dụng phương thức subscriptions.get hoặc subscriptions.list để xem trường state của gói thuê bao có được đặt thành SUSPENDED hay không.
  • Bạn sẽ nhận được thông báo về việc không gửi được đến điểm cuối thông báo. Để tìm hiểu về việc giám sát các lỗi gửi đến chủ đề Google Cloud Pub/Sub, hãy xem phần Xử lý lỗi thông báo.

Các gói thuê bao được kích hoạt lại vẫn giữ nguyên ngày hết hạn ban đầu. Để gia hạn thời gian hết hạn của gói thuê bao, hãy xem bài viết Cập nhật hoặc gia hạn gói thuê bao Google Workspace.

Apps Script

  • Gói thuê bao Google Workspace. Để tạo một gói thuê bao, hãy xem phần Tạo gói thuê bao.

  • Một dự án Apps Script:
    • Sử dụng dự án Google Cloud của bạn thay vì dự án mặc định do Apps Script tự động tạo.
    • Đối với tất cả các phạm vi mà bạn đã thêm để định cấu hình màn hình đồ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 nội dung 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

Xác định và giải quyết lỗi

Để xác định lỗi của một gói thuê bao, hãy xem xét trường suspensionReason của gói thuê bao đó. Bạn có thể tìm thấy trường này khi nhận được một sự kiện vòng đời về trạng thái tạm ngưng hoặc bằng cách sử dụng phương thức subscriptions.get để xem xét tất cả các trường của gói thuê bao.

Bảng sau đây cho thấy các lỗi có thể xảy ra đối với một gói thuê bao và cách khắc phục các lỗi đó (nếu có thể). Nếu không khắc phục được lỗi, bạn có thể xoá gói thuê bao hoặc đợi gói thuê bao hết hạn. Google Workspace Events API sẽ tự động xoá các gói thuê bao đã hết hạn.

Lỗi Nội dung mô tả Cách giải quyết

USER_SCOPE_REVOKED

Người dùng uỷ quyền đã thu hồi quyền cấp một hoặc nhiều phạm vi OAuth cần thiết cho gói thuê bao. Lấy một mã truy cập khác. Để biết thông tin chi tiết, hãy xem phần Lấy mã truy cập từ Máy chủ uỷ quyền của Google.

RESOURCE_DELETED

Tài nguyên mục tiêu của gói thuê bao bị xoá. Nếu tài nguyên được khôi phục, hãy gọi phương thức reactivate. Nếu không, bạn không cần làm gì cả vì không thể kích hoạt lại một thuê bao mà không có tài nguyên đích ban đầu.

USER_AUTHORIZATION_FAILURE

Người dùng uỷ quyền không còn quyền truy cập vào tài nguyên cho gói thuê bao nữa. Bạn không cần làm gì cả. Bạn không thể kích hoạt lại gói thuê bao vì người dùng đã uỷ quyền không thể truy cập vào tài nguyên đích.

ENDPOINT_PERMISSION_DENIED

Ứng dụng Google Workspace không có quyền truy cập để gửi các sự kiện đến điểm cuối thông báo của bạn. Cấp quyền truy cập cho tài khoản dịch vụ đối với ứng dụng Google Workspace cung cấp sự kiện.

Tài khoản dịch vụ:
  • Sự kiện trên Google Chat: chat-api-push@system.gserviceaccount.com
  • Sự kiện trên Google Drive: drive-api-event-push@system.gserviceaccount.com
  • Sự kiện trên Google Meet: meet-api-event-push@system.gserviceaccount.com

Đối với chủ đề Pub/Sub, hãy cấp vai trò Nhà xuất bản Pub/Sub (roles/pubsub.publisher) cho tài khoản dịch vụ.

ENDPOINT_NOT_FOUND

Điểm cuối thông báo không tồn tại hoặc không tìm thấy. Kiểm tra để đảm bảo rằng điểm cuối vẫn đang hoạt động. Để khắc phục sự cố về các chủ đề Pub/Sub, hãy xem Tài liệu khắc phục sự cố.

ENDPOINT_RESOURCE_EXHAUSTED

Điểm cuối thông báo không nhận được sự kiện do không đủ hạn mức hoặc đạt đến tốc độ giới hạn. Yêu cầu tăng hạn mức.

APP_SCOPE_REVOKED

Quản trị viên miền đã thu hồi quyền cấp một hoặc nhiều phạm vi OAuth cho ứng dụng Chat. Nhận được sự phê duyệt của quản trị viên.

APP_AUTHORIZATION_FAILURE

Ứng dụng Chat đã uỷ quyền tạo gói thuê bao không còn quyền truy cập vào tài nguyên đích của gói thuê bao nữa. Lấy lại quyền truy cập vào tài nguyên đích. Ví dụ: nếu tài nguyên đích là một không gian trong Chat, thì ứng dụng Chat có thể cần có quyền thành viên trong không gian đó.

Kích hoạt lại gói thuê bao

Sau khi giải quyết lỗi khiến gói thuê bao của bạn bị tạm ngưng, bạn có thể dùng phương thức reactivate để cho phép gói thuê bao nhận lại các sự kiện. Phương thức này kiểm tra để đảm bảo tất cả lỗi đều được giải quyết và thay đổi trường state của gói thuê bao từ SUSPENDED thành ACTIVE.

Cách kích hoạt lại gói thuê bao Google Workspace:

Apps Script

  1. Trong dự án Apps Script, hãy tạo một tệp kịch bản mới có tên là reactivateSubscription rồi thêm mã sau:

    function reactivateSubscription() {
  // The name of the subscription to reactivate.
  const name = 'subscriptions/SUBSCRIPTION_ID';

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.reactivate({}, name);
  console.log(response);
}

    Thay thế nội dung sau:

    • SUBSCRIPTION_ID: Mã nhận dạng của gói thuê bao. Để lấy mã nhận dạng, bạn có thể sử dụng bất kỳ phương thức nào sau đây:
      • Giá trị của trường uid.
      • Mã nhận dạng của tên tài nguyên được biểu thị trong trường name. Ví dụ: nếu tên tài nguyên là subscriptions/subscription-123, hãy dùng subscription-123.

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

Python

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

    """Reactivate 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()

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

NAME = 'subscriptions/SUBSCRIPTION_ID'
response = service.subscriptions().reactivate(name=NAME).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'.
    • SUBSCRIPTION_ID: Mã nhận dạng của gói thuê bao. Để lấy mã nhận dạng, bạn có thể sử dụng bất kỳ phương thức nào sau đây:
      • Giá trị của trường uid.
      • Mã nhận dạng của tên tài nguyên được biểu thị trong trường name. Ví dụ: nếu tên tài nguyên là subscriptions/subscription-123, hãy dùng subscription-123.

  2. Trong thư mục làm việc, hãy đảm bảo bạn đã lưu trữ thông tin đăng nhập mã ứng dụng OAuth và đặt tên cho tệp là credentials.json. Mã mẫu sử dụng tệp JSON này để xác thực với Google Workspace và lấy thông tin đăng nhập của người dùng. Để biết hướng dẫn, hãy xem phần Tạo thông tin đăng nhập mã ứng dụng khách OAuth.

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

    python3 reactivate_subscription.py
Google Workspace Events API trả về một thao tác diễn ra trong thời gian dài chứa phiên bản của tài nguyên Subscription.

Nếu yêu cầu không thành công, hãy xem phần sau để khắc phục các lỗi khác.

Kích hoạt lại gói thuê bao dưới dạng ứng dụng Google Chat

Bạn có thể kích hoạt lại một gói đăng ký nhận sự kiện Chat dưới dạng một ứng dụng Chat thay vì dưới dạng người dùng. Quy trình này tương tự, ngoại trừ:

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

  2. Chỉ định các phạm vi uỷ quyền cho phép ứng dụng Chat đăng ký nhận các 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 những phạm vi sau:

    • https://www.googleapis.com/auth/chat.app.memberships: Đăng ký nhận thông báo về sự kiện của thành viên trong phòng Chat.
    • https://www.googleapis.com/auth/chat.app.messages.readonly: Đăng ký nhận sự kiện về tin nhắn và lượt thể hiện cảm xúc trong không gian Chat.
    • https://www.googleapis.com/auth/chat.app.spaces: Đăng ký nhận thông báo về các sự kiện trong không gian trên Chat.

Tạo một khoá API

Để gọi một phương thức API trong bản dùng thử cho nhà phát triển, bạn phải sử dụng một phiên bản không công khai của tài liệu khám phá API trong bản dùng thử cho nhà phát triển. Để xác thực yêu cầu, bạn phải truyền một khoá API.

Để tạo Khoá API, hãy mở dự án Google Cloud của ứng dụng rồi làm như sau:

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > API và Dịch vụ > Thông tin xác thực.

    Chuyển đến phần Thông tin đăng nhập

  2. Nhấp vào Tạo thông tin xác thực > Khoá API.
  3. Khoá API mới của bạn sẽ xuất hiện.
    • Nhấp vào biểu tượng Sao chép để sao chép khoá API nhằm sử dụng trong mã của ứng dụng. Bạn cũng có thể tìm thấy khoá API trong phần "Khoá API" của thông tin đăng nhập dự án.
    • Để ngăn chặn việc sử dụng trái phép, bạn nên hạn chế nơi và API mà khoá API có thể được dùng. Để biết thêm thông tin chi tiết, hãy xem phần Thêm các quy tắc hạn chế đối với API.

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

Mã mẫu sau đây kích hoạt lại gói thuê bao Google Workspace của một ứng dụng Chat:

Python 

  """Reactivate subscription."""

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

  # Specify required scopes.
  SCOPES = [SCOPES]

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

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1beta',
      credentials=CREDENTIALS,
      discoveryServiceUrl='https://workspaceevents.googleapis.com/$discovery/rest?version=v1beta&labels=DEVELOPER_PREVIEW&key=API_KEY',
  )

  NAME = 'subscriptions/SUBSCRIPTION_ID'
  response = service.subscriptions().reactivate(name=NAME).execute()
  print(response)

Thay thế nội dung sau:

  • SCOPES: Chỉ định các phạm vi uỷ quyền cho phép ứng dụng Chat đăng ký nhận các 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 những phạm vi sau:

    • https://www.googleapis.com/auth/chat.app.memberships: Đăng ký nhận thông báo về sự kiện của thành viên trong phòng Chat.
    • https://www.googleapis.com/auth/chat.app.messages.readonly: Đăng ký nhận sự kiện về tin nhắn và lượt thể hiện cảm xúc trong không gian Chat.
    • https://www.googleapis.com/auth/chat.app.spaces: Đăng ký nhận thông báo về các sự kiện trong không gian trên Chat.

  • API_KEY: Khoá API mà bạn đã tạo để xây dựng điểm cuối dịch vụ cho Google Workspace Events API.

  • SUBSCRIPTION_ID: Mã nhận dạng của gói thuê bao. Để lấy mã nhận dạng, bạn có thể dùng một trong những cách sau:

    • Giá trị của trường uid.
    • Mã nhận dạng của tên tài nguyên được biểu thị trong trường name. Ví dụ: nếu tên tài nguyên là subscriptions/subscription-123, hãy dùng subscription-123.

Khắc phục nhiều lỗi

Nếu bạn đã giải quyết lỗi khiến gói thuê bao bị tạm ngưng và phương thức reactivate không thành công, thì có thể đã xảy ra một lỗi khác sau khi gói thuê bao của bạn bị tạm ngưng.

Để xác định các lỗi khác, hãy xem xét đầu ra của yêu cầu không thực hiện được. Đầu ra chứa mọi lỗi vẫn còn.

Khi gói thuê bao của bạn gặp nhiều lỗi, giá trị cho trường suspensionReason luôn sử dụng lỗi ban đầu khiến gói thuê bao của bạn bị tạm ngưng.