更新或續訂 Google Workspace 訂閱方案

本頁說明如何使用 subscriptions.update() 方法續訂 Google Workspace 方案。您可以使用這個方法更新訂閱項目的到期時間，包括將訂閱項目續訂至最長到期時間，或是更新要接收目標資源相關事件的事件類型清單。

Apps Script

  • Google Workspace 訂閱方案。如要建立訂閱項目，請參閱「建立訂閱項目」一文。

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

Python

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

續訂 Google Workspace 方案

在本節中，您將使用 Google Workspace Events API 的 subscriptions.update() 方法，將訂閱項目續訂至最長到期時間。如要指定最長到期時間，請將 Subscription 資源的 ttl 欄位更新為 0。

最長到期時間取決於事件酬載中包含的資源資料。如要進一步瞭解到期時間，請參閱「Google Workspace 事件的事件資料」。

如要續訂 Google Workspace 方案，請按照下列步驟操作：

Apps Script

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

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

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.patch({
    ttl: '0s',
  }, name);
  console.log(response);
}

    更改下列內容：

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

  2. 如要更新 Google Workspace 訂閱方案，請在 Apps Script 專案中執行函式 updateSubscription。

Python

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

    """Update 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,
)

BODY = {
    'ttl': {'seconds': 0},
}
NAME = 'subscriptions/SUBSCRIPTION_ID'
response = (
    service.subscriptions()
    .patch(name=NAME, updateMask='ttl', body=BODY)
    .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 憑證，且檔案名為 credentials.json。程式碼範例會使用這個 JSON 檔案向 Google Workspace 進行驗證，並取得使用者憑證。如需操作說明，請參閱「建立 OAuth 用戶端 ID 憑證」。

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

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

如要取得更新後 Subscription 資源的詳細資料，請使用 operations.get() 方法，並指定從 subscriptions.update() 要求傳回的 Operation 資源。否則，如果您指定先前訂閱方案版本的 Operation 資源，回應會是空白。

透過 Google Chat 擴充應用程式更新或續訂方案

您可以更新或續訂 Chat 事件的訂閱項目，方法是使用 Chat 應用程式，而非使用者。程序類似，但有以下例外情況：

  1. 請以 Chat 應用程式身分進行驗證，並取得管理員一次性核准，而不是進行使用者驗證。

  2. 指定授權範圍，允許 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 專案，然後執行下列操作：

  1. 在 Google Cloud 控制台中，依序前往「選單」圖示 >「API 和服務」 >「憑證」。

    前往「憑證」

  2. 依序按一下「建立憑證」>「API 金鑰」。
  3. 系統會顯示新的 API 金鑰。
    • 按一下「複製」圖示 ，即可複製 API 金鑰，在應用程式的程式碼中使用。您也可以在專案憑證的「API 金鑰」專區中找到 API 金鑰。
    • 為避免未經授權的使用行為，建議您為可使用該 API 金鑰的 API 及使用位置新增限制。詳情請參閱「新增 API 限制」一文。

編寫呼叫 Google Workspace Events API 的指令碼

下列程式碼範例會更新 Chat 應用程式的 Google Workspace 訂閱項目：

Python

  """Update 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',
  )

  BODY = {
      'ttl': {'seconds': 0},
  }
  NAME = 'subscriptions/SUBSCRIPTION_ID'
  response = (
      service.subscriptions()
      .patch(name=NAME, updateMask='ttl', body=BODY)
      .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，請使用下列任一方法：

    • uid 欄位的值。
    • name 欄位中代表的資源名稱 ID。舉例來說，如果資源名稱是 subscriptions/subscription-123，請使用 subscription-123。