進階 Google Workspace 事件服務

Advanced Google Workspace Events 服務可讓您在 Apps Script 中使用 Google Workspace Events API。有了這個 API，您就能訂閱 Google Workspace 資源，掌握您感興趣的相關事件資訊。事件是指對資源進行的變更，例如建立、更新或刪除。

必要條件

  • Apps Script 專案使用標準 Google Cloud 專案，而非 Apps Script 自動建立的預設專案。
  • 在同一個 Google Cloud 專案中建立的 Pub/Sub 主題，用於接收訂閱事件。如要建立 Pub/Sub 主題，請參閱「建立及訂閱 Pub/Sub 主題」。
  • 如要訂閱 Chat 事件，您必須在 Google Cloud 控制台的 Chat API 設定頁面上，設定 Google Chat 應用程式。如要建立 Google Chat 擴充應用程式，請參閱「使用 Apps Script 建構 Google Chat 擴充應用程式」。

  • 已在 Apps Script 專案的 appsscript.json 檔案中新增必要授權範圍。必要範圍取決於訂閱項目目標資源和事件的類型。詳情請參閱「選擇 Google Workspace Events API 範圍」。例如：

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.readonly"
]

參考資料

如要進一步瞭解這項服務，請參閱 Google Workspace Events API 參考說明文件。與 Apps Script 中的所有進階服務一樣，Google Workspace Events 服務使用的物件、方法和參數，都與公開 API 相同。

程式碼範例

這些範例說明如何使用進階服務，執行常見的 Google Workspace Events API 動作。

建立訂閱項目

如要建立 Google Workspace 資源的訂閱項目，請將下列函式新增至 Apps Script 專案的程式碼：

advanced/events.gs
/**
 * Creates a subscription to receive events about a Google Workspace resource.
 * For a list of supported resources and event types, see the
 * [Google Workspace Events API Overview](https://developers.google.com/workspace/events#supported-events).
 * For additional information, see the
 * [subscriptions.create](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/create)
 * method reference.
 * @param {!string} targetResource The full resource name of the Google Workspace resource to subscribe to.
 * @param {!string|!Array<string>} eventTypes The types of events to receive about the resource.
 * @param {!string} pubsubTopic The resource name of the Pub/Sub topic that receives events from the subscription.
 */
function createSubscription(targetResource, eventTypes, pubsubTopic) {
  try {
    const operation = WorkspaceEvents.Subscriptions.create({
      targetResource: targetResource,
      eventTypes: eventTypes,
      notificationEndpoint: {
        pubsubTopic: pubsubTopic,
      },
    });
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to create subscription with error %s', err.message);
  }
}

可列出訂閱項目

如要列出依事件類型和目標資源篩選的訂閱項目，請將下列函式新增至 Apps Script 專案的程式碼：

advanced/events.gs
/**
 * Lists subscriptions created by the calling app filtered by one or more event types and optionally by a target resource.
 * For additional information, see the
 * [subscriptions.list](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/list)
 * method reference.
 * @param {!string} filter The query filter.
 */
function listSubscriptions(filter) {
  try {
    const response = WorkspaceEvents.Subscriptions.list({ filter });
    console.log(response);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to list subscriptions with error %s', err.message);
  }
}

可取得訂閱項目

如要取得訂閱資訊，請在 Apps Script 專案的程式碼中加入下列函式：

advanced/events.gs
/**
 * Gets details about a subscription.
 * For additional information, see the
 * [subscriptions.get](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/get)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function getSubscription(name) {
  try {
    const subscription = WorkspaceEvents.Subscriptions.get(name);
    console.log(subscription);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to get subscription with error %s', err.message);
  }
}

更新訂閱項目

如要更新或續訂訂閱項目，請在 Apps Script 專案的程式碼中新增下列函式：

advanced/events.gs
/**
 * Updates an existing subscription.
 * This can be used to renew a subscription that is about to expire.
 * For additional information, see the
 * [subscriptions.patch](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/patch)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function patchSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.patch({
      // Setting the TTL to 0 seconds extends the subscription to its maximum expiration time.
      ttl: '0s',
    }, name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to update subscription with error %s', err.message);
  }
}

重新啟用訂閱方案

如要重新啟用訂閱項目，請在 Apps Script 專案的程式碼中加入下列函式：

advanced/events.gs
/**
 * Reactivates a suspended subscription.
 * Before reactivating, you must resolve any errors with the subscription.
 * For additional information, see the
 * [subscriptions.reactivate](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/reactivate)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function reactivateSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.reactivate({}, name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to reactivate subscription with error %s', err.message);
  }
}

刪除訂閱項目

如要刪除訂閱項目，請將下列函式新增至 Apps Script 專案的程式碼：

advanced/events.gs
/**
 * Deletes a subscription.
 * For additional information, see the
 * [subscriptions.delete](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/delete)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function deleteSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.remove(name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to delete subscription with error %s', err.message);
  }
}

取得作業

大多數 Google Workspace Events API 方法都會傳回長時間執行的作業。如要判斷作業狀態，可以使用 operations.get() 方法。

如要取得作業相關資訊，請將下列函式新增至 Apps Script 專案的程式碼：

advanced/events.gs
/**
 * Gets details about an operation returned by one of the methods on the subscription
 * resource of the Google Workspace Events API.
 * For additional information, see the
 * [operations.get](https://developers.google.com/workspace/events/reference/rest/v1/operations/get)
 * method reference.
 * @param {!string} name The resource name of the operation.
 */
function getOperation(name) {
  try {
    const operation = WorkspaceEvents.Operations.get(name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to get operation with error %s', err.message);
  }
}

如要取得作業名稱，請使用 Google Workspace Events API 方法 (例如 subscriptions.create() 或 subscriptions.patch()) 傳回的 name 欄位值。