本頁說明如何解決或排解錯誤,並呼叫 subscriptions.reactivate
方法,重新啟用已暫停的 Google Workspace 訂閱方案。
如果發生錯誤,導致訂閱方案無法接收事件,Google Workspace 訂閱方案就會停用。舉例來說,如果找不到目標資源或通知端點,訂閱項目就會遭到暫停。解決訂閱項目相關錯誤後,即可重新啟用訂閱項目,再次接收事件。
如要瞭解遭停權的訂閱方案,請採取下列任一做法:
- 應用程式會收到有關停權的生命週期事件。如果訂閱項目因端點發生錯誤而遭到停權,您可能不會收到生命週期事件。
- 您可以使用
subscriptions.get
或subscriptions.list
方法,查看訂閱項目的state
欄位是否設為SUSPENDED
。 - 系統會通知您通知端點的傳送失敗情形。如要瞭解如何監控傳送至 Google Cloud Pub/Sub 主題的訊息是否失敗,請參閱「處理訊息傳送失敗」。
重新啟用的訂閱項目會維持原到期日。如要延長訂閱方案的效期,請參閱「更新或續訂 Google Workspace 訂閱方案」。
Apps Script
- Google Workspace 訂閱方案。如要建立訂閱項目,請參閱「建立訂閱項目」一文。
- Apps Script 專案:
- 使用 Google Cloud 專案,而非 Apps Script 自動建立的預設專案。
- 針對您新增的所有範圍,以設定 OAuth 同意畫面,您也必須在 Apps Script 專案的
appsscript.json
檔案中新增範圍。舉例來說,如果您指定chat.messages
範圍,請新增下列項目: - 啟用
Google Workspace Events
進階服務。
"oauthScopes": [ "https://www.googleapis.com/auth/chat.messages" ]
訂閱中的各事件類型都需要驗證和適當的授權範圍:
- 如要進行使用者驗證,必須有一或多個範圍支援訂閱項目的至少一種事件類型。如要找出範圍,請參閱「依事件類型劃分的範圍」。
- 如要以 Chat 擴充應用程式身分訂閱 Chat 事件,必須透過一次性管理員核准進行應用程式驗證。以 Chat 應用程式身分訂閱 Chat 事件的功能,目前僅在開發人員預覽版中提供。
Python
- Python 3.6 以上版本
- pip 套件管理工具
- 最新版 Python 適用的 Google 用戶端程式庫。如要安裝或更新這些工具,請在指令列介面中執行下列指令:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- Google Workspace 訂閱方案。如要建立訂閱項目,請參閱「建立訂閱項目」一文。
訂閱中的各事件類型都需要驗證和適當的授權範圍:
- 如要進行使用者驗證,必須有一或多個範圍支援訂閱項目的至少一種事件類型。如要找出範圍,請參閱「依事件類型劃分的範圍」。
- 如要以 Chat 擴充應用程式身分訂閱 Chat 事件,必須透過一次性管理員核准進行應用程式驗證。以 Chat 應用程式身分訂閱 Chat 事件的功能,目前僅在開發人員預覽版中提供。
找出並解決錯誤
如要找出訂閱項目的錯誤,請查看訂閱項目的 suspensionReason
欄位。當您收到有關暫停的生命週期事件時,或使用 subscriptions.get
方法查看訂閱項目的所有欄位時,即可找到這個欄位。
下表列出訂閱項目可能發生的錯誤,以及解決方法 (如適用)。如果無法解決錯誤,可以刪除訂閱項目,或等待訂閱項目到期。Google Workspace Events API 會自動刪除過期的訂閱項目。
錯誤 | 說明 | 解決方法 |
---|---|---|
|
授權使用者已撤銷訂閱項目所需的一或多個 OAuth 範圍授權。 | 取得其他存取權杖。詳情請參閱「 從 Google 授權伺服器取得存取權杖」。 |
|
訂閱項目的目標資源已刪除。 | 如果資源已還原,請呼叫 reactivate 方法。否則無須採取任何行動,因為如果沒有原始目標資源,就無法重新啟用訂閱項目。 |
|
授權使用者已無法存取訂閱項目的資源。 | 您無須採取行動,由於授權訂閱的使用者無法存取目標資源,因此您無法重新啟用訂閱。 |
|
Google Workspace 應用程式無法將事件傳送至通知端點。 | 將存取權授予 Google Workspace 應用程式的服務帳戶,以便傳送事件。 服務帳戶:
如果是 Pub/Sub 主題,請將「Pub/Sub 發布者」角色 ( roles/pubsub.publisher)
) 授予服務帳戶。 |
|
通知端點不存在或找不到。 | 確認端點仍處於有效狀態且正常運作。如要排解 Pub/Sub 主題問題,請參閱疑難排解文件。 |
|
通知端點因配額不足或達到速率限制,無法接收事件。 | 申請提高配額。 |
|
網域管理員已撤銷 Chat 應用程式的一或多個 OAuth 範圍授權。 | 取得管理員核准。 |
|
授權建立訂閱項目的 Chat 應用程式已無法存取訂閱項目的目標資源。 | 重新取得目標資源的存取權。舉例來說,如果目標資源是 Chat 聊天室,Chat 應用程式可能需要加入該聊天室。 |
重新啟用訂閱方案
解決導致訂閱項目暫停的問題後,即可使用 reactivate
方法,讓訂閱項目再次接收事件。這個方法會檢查所有錯誤是否都已解決,並將訂閱項目的 state
欄位從 SUSPENDED
變更為 ACTIVE
。
如要重新啟用 Google Workspace 訂閱方案,請按照下列步驟操作:
Apps Script
在 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); }
更改下列內容:
如要重新啟用 Google Workspace 訂閱方案,請在 Apps Script 專案中執行
reactivateSubscription
函式。
Python
在工作目錄中,建立名為
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('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)
更改下列內容:
SCOPES
:支援訂閱項目中各事件類型的 OAuth 範圍。格式為字串陣列。如要列出多個範圍,請以半形逗號分隔。 例如:'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'
。SUBSCRIPTION_ID
:訂閱 ID。如要取得 ID,可以使用下列任一方法:
請確認工作目錄中已儲存 OAuth 用戶端 ID 憑證,且檔案名為
credentials.json
。程式碼範例會使用這個 JSON 檔案向 Google Workspace 進行驗證,並取得使用者憑證。如需操作說明,請參閱「建立 OAuth 用戶端 ID 憑證」。如要重新啟用 Google Workspace 訂閱方案,請在終端機中執行下列指令:
python3 reactivate_subscription.py
Subscription
資源的執行個體。如果要求失敗,請參閱下一節,排解其他錯誤。
使用 Google Chat 擴充應用程式重新啟用訂閱方案
您可以重新啟用 Chat 事件的訂閱項目,但要以 Chat 應用程式而非使用者身分進行。程序類似,但有以下例外情況:
請以 Chat 應用程式身分進行驗證,並取得管理員一次性核准,而不是進行使用者驗證。
指定授權範圍,允許 Chat 應用程式訂閱 Chat 事件。這些授權範圍一律以
chat.app
開頭,並包含下列項目:https://www.googleapis.com/auth/chat.app.memberships
: 訂閱 Chat 聊天室成員事件。https://www.googleapis.com/auth/chat.app.messages.readonly
: 訂閱 Chat 聊天室訊息和回應事件。https://www.googleapis.com/auth/chat.app.spaces
: 訂閱 Chat 聊天室事件。
建立 API 金鑰
如要呼叫開發人員預先發布版 API 方法,您必須使用非公開的開發人員預先發布版 API 探索文件。如要驗證要求,您必須傳遞 API 金鑰。
如要建立 API 金鑰,請開啟應用程式的 Google Cloud 專案,然後執行下列操作:
- 在 Google Cloud 控制台中,依序前往「選單」圖示 >「API 和服務」 >「憑證」。
- 依序按一下「建立憑證」>「API 金鑰」。
- 系統會顯示新的 API 金鑰。
- 按一下「複製」圖示 ,即可複製 API 金鑰,在應用程式的程式碼中使用。您也可以在專案憑證的「API 金鑰」專區中找到 API 金鑰。
- 為避免未經授權的使用行為,建議您為可使用該 API 金鑰的 API 及使用位置新增限制。詳情請參閱「新增 API 限制」一文。
編寫呼叫 Google Workspace Events API 的指令碼
下列程式碼範例會重新啟用 Chat 應用程式的 Google Workspace 訂閱方案:
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)
更改下列內容:
SCOPES
:指定授權範圍,允許 Chat 應用程式訂閱 Chat 事件。這些授權範圍一律以chat.app
開頭,並包含下列項目:https://www.googleapis.com/auth/chat.app.memberships
: 訂閱 Chat 聊天室成員事件。https://www.googleapis.com/auth/chat.app.messages.readonly
: 訂閱 Chat 聊天室訊息和回應事件。https://www.googleapis.com/auth/chat.app.spaces
: 訂閱 Chat 聊天室事件。
API_KEY
:您建立的 API 金鑰,用於建構 Google Workspace Events API 的服務端點。SUBSCRIPTION_ID
:訂閱 ID。如要取得 ID,請使用下列任一方法:
排解多個錯誤
如果已解決導致訂閱方案遭停用的錯誤,但 reactivate
方法仍失敗,可能是訂閱方案遭停用後發生其他錯誤。
如要找出其他錯誤,請查看失敗要求的輸出內容。輸出內容會顯示仍存在的任何錯誤。
如果訂閱項目發生多項錯誤,suspensionReason
欄位的值一律會使用導致訂閱項目暫停的原始錯誤。