進階 Google Workspace 事件服務

您可以透過進階 Google Workspace 事件服務，在 Apps Script 中使用 Google WorkspaceEvents 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 Event API 範圍」。例如：

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

參考資料

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

程式碼範例

這些範例說明如何使用進階服務執行常見的 Google WorkspaceEvents 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 Event 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 Event API 方法 (例如 subscriptions.create() 或 subscriptions.patch()) 傳回的 name 欄位值。