解決錯誤並重新啟用 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 Events 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 指令碼專案中,建立名為 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 Events API 會傳回長時間執行作業,其中包含 Subscription 資源的例項。

如果要求失敗,請參閱下一個部分,瞭解如何排除其他錯誤。

排解多個錯誤

如果您已解決導致訂閱項目遭到停用的錯誤,但 reactivate() 方法仍失敗,表示訂閱項目遭到停用後可能發生其他錯誤。

如要找出其他錯誤,請查看失敗要求的輸出內容。輸出內容會包含仍存在的任何錯誤。

如果訂閱項目有多個錯誤,suspensionReason 欄位的值一律會使用導致訂閱項目遭到停用的原始錯誤。