解決錯誤並重新啟用 Google Workspace 訂閱方案

本頁說明如何透過解決或疑難排解錯誤以及呼叫 subscriptions.reactivate() 方法，重新啟用已停權的 Google Workspace 訂閱方案。

當錯誤導致訂閱項目無法接收事件時，Google Workspace 訂閱會暫停。例如，找不到目標資源或通知端點時，訂閱項目就會遭到停權。解決該訂閱項目的所有錯誤後，您就可以重新啟用訂閱項目，再次開始接收事件。

你可以透過下列方式瞭解遭停權的訂閱項目：

  • 您的應用程式會收到有關停權的生命週期事件。如果訂閱項目因端點發生錯誤而遭到停權，您可能會收不到生命週期事件。
  • 您可以用 subscriptions.get() 或 subscriptions.list() 方法查看訂閱項目的 state 欄位是否設為 SUSPENDED。
  • 系統會發送通知到通知端點失敗，如要瞭解如何監控傳送至 Google Cloud Pub/Sub 主題的傳送失敗，請參閱處理訊息失敗問題。

重新啟用的訂閱項目將沿用原先的到期日。如要延長訂閱項目的到期時間，請參閱更新或續訂訂閱項目。

Apps Script

  • Apps Script 專案：
    • 請使用 Google Cloud 專案，而非 Apps Script 自動建立的預設專案。
    • 針對新增用來設定 OAuth 同意畫面的所有範圍，您也必須將範圍新增至 Apps Script 專案的 appsscript.json 檔案中。 例如： 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.readonly"
]
    • 啟用 Google Workspace Events 進階服務。

Python

  • Python 3.6 或更高版本
  • pip 套件管理工具
  • 最新的 Python 專用 Google 用戶端程式庫。如要安裝或更新，請在指令列介面中執行下列指令： 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib

找出並修正錯誤

如要找出訂閱項目的錯誤，請查看訂閱項目的 suspensionReason 欄位。收到有關停權的生命週期事件，或使用 subscriptions.get() 方法查看訂閱項目的所有欄位時，即可找到這個欄位。

下表顯示訂閱項目的可能錯誤，以及在可能的情況下如何解決這些錯誤。如果您無法解決錯誤，您可以刪除訂閱項目，或等待訂閱項目到期。Google Workspace Event API 會自動刪除過期的訂閱項目。

錯誤 說明 解決方式

USER_SCOPE_REVOKED

授權使用者已撤銷訂閱項目所需的一或多個 OAuth 範圍。 取得其他存取權杖。詳情請參閱「 從 Google 授權伺服器取得存取權杖」。

RESOURCE_DELETED

訂閱項目的目標資源已刪除。 如果資源已還原，請呼叫 reactivate() 方法。如果確實如此，則無須採取任何行動，因為訂閱項目在沒有原始目標資源的情況下，您無法重新啟用該訂閱項目。

USER_AUTHORIZATION_FAILURE

授權使用者已無法再存取訂閱項目的資源。 您無須採取行動，授權該訂閱項目的使用者無法存取目標資源，因此您無法重新啟用該訂閱項目。

ENDPOINT_PERMISSION_DENIED

Google Workspace 應用程式無法存取傳送事件至通知端點的權限。 將存取權授予傳遞事件的 Google Workspace 應用程式的服務帳戶。

如果是 Google Chat 事件，服務帳戶為 chat-api-push@system.gserviceaccount.com。如果是 Google Meet 活動，服務帳戶為 meet-api-event-push@system.gserviceaccount.com。

如果是 Pub/Sub 主題，請將 Pub/Sub 發布者 (roles/pubsub.publisher) ) 角色授予服務帳戶。

ENDPOINT_NOT_FOUND

通知端點不存在或找不到。 請檢查端點是否仍然有效且正在運作。如要排解 Pub/Sub 主題的問題，請參閱疑難排解說明文件。

ENDPOINT_RESOURCE_EXHAUSTED

由於配額不足或達到頻率限制，通知端點無法接收事件。 請申請提高配額，

重新啟用訂閱項目

解決暫停訂閱項目的錯誤後，您可以使用 reactivate() 方法讓訂閱項目再次接收事件。這個方法會檢查所有錯誤是否已解決，並將訂閱項目的 state 欄位從 SUSPENDED 變更為 ACTIVE。

如何重新啟用 Google Workspace 訂閱方案：

Apps Script

  1. 在 Apps Script 專案中，建立名為 reactivateSubscription 的新指令碼檔案，並新增下列程式碼：

    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);
}

    更改下列內容：

    • SUBSCRIPTION_ID：訂閱項目的 ID。如要取得 ID，您可以使用下列任一工具：
      • uid 欄位的值。
      • name 欄位中代表的資源名稱 ID。舉例來說，如果資源名稱是 subscriptions/subscription-123，請使用 subscription-123。

  2. 如要重新啟用 Google Workspace 訂閱，請在 Apps Script 專案中執行 reactivateSubscription 函式。

Python

  1. 在工作目錄中，建立名為 reactivate_subscription.py 的檔案，並新增下列程式碼：

    """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('client_secrets.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)

    更改下列內容：

    • SCOPES：支援訂閱每個事件類型的一或多個 OAuth 範圍。採用字串陣列的格式。如要列出多個範圍，請以半形逗號分隔。 例如：'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'。
    • SUBSCRIPTION_ID：訂閱項目的 ID。如要取得 ID，您可以使用下列任一工具：
      • uid 欄位的值。
      • name 欄位中代表的資源名稱 ID。舉例來說，如果資源名稱是 subscriptions/subscription-123，請使用 subscription-123。

  2. 在工作目錄中，確認您已儲存 OAuth 用戶端 ID 憑證並命名為 client_secrets.json。程式碼範例會使用這個 JSON 檔案向 Google Workspace 進行驗證，並取得使用者憑證。如需操作說明，請參閱「建立 OAuth 用戶端 ID 憑證」。

  3. 如要重新啟用 Google Workspace 訂閱方案，請在終端機中執行下列指令：

    python3 reactivate_subscription.py
Google Workspace Event API 會傳回長時間執行的作業，其中包含 Subscription 資源的執行個體。

如果要求失敗，請參閱以下章節，瞭解如何排解其他錯誤。

排解多個錯誤

如果您已解決暫停訂閱的錯誤，且 reactivate() 方法失敗，表示訂閱項目暫停後可能發生了其他錯誤。

如要找出其他錯誤，請查看失敗要求的輸出內容。輸出結果包含仍顯示的任何錯誤。

如果訂閱項目有多個錯誤，suspensionReason 欄位的值一律會使用暫停訂閱的原始錯誤。