進階 Google Workspace 事件服務

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

必要條件

  • 使用標準 Google Cloud 專案的 Apps Script 專案，而非由 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 指令碼專案的程式碼：

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 欄位值。