解決錯誤並重新啟用 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 欄位的值一律會使用暫停訂閱的原始錯誤。