שירות מתקדם של Google Workspace Event

שירות האירועים המתקדמים של Google Workspace מאפשר להשתמש ב-Google Workspace Event API ב-Apps Script. ה-API הזה מאפשר להירשם למשאבים של Google Workspace כדי לקבל אירועים רלוונטיים שמעניינים אתכם. אירועים מייצגים שינויים במשאבים, למשל כשיוצרים, מעדכנים או מוחקים משאבים.

דרישות מוקדמות

  • פרויקט ב-Apps Script באמצעות פרויקט רגיל של Google Cloud, במקום פרויקט ברירת המחדל שנוצר באופן אוטומטי על ידי Apps Script.
  • נושא Pub/Sub שנוצר באותו פרויקט ב-Google Cloud כדי לקבל אירועים של מינויים. במאמר יצירת נושא Pub/Sub והרשמה אליו תוכלו לקרוא איך יוצרים נושא Pub/Sub.
  • כדי להירשם לאירועים ב-Chat, צריך להגדיר אפליקציה ל-Google Chat בדף ההגדרות של Chat API במסוף Google Cloud. רוצים לדעת איך יוצרים אפליקציה ל-Google Chat באמצעות Apps Script?

  • היקפי ההרשאות הנחוצים שנוספו לקובץ appsscript.json של פרויקט Apps Script. היקפים הנדרשים תלויים בסוגים של משאבי היעד ואירועי היעד של המינויים. לפרטים נוספים תוכלו לקרוא את המאמר בחירת היקפים של Google Workspace Event API. למשל:

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

חומרי עזר

למידע נוסף על השירות הזה, תוכלו לעיין במסמכי הפניית API ל-Google Workspace Event API. כמו כל השירותים המתקדמים ב-Apps Script, גם שירות Google Workspace אירועים משתמש באותם אובייקטים, שיטות ופרמטרים כמו ה-API הציבורי.

קוד לדוגמה

הדוגמאות האלה ממחישות איך לבצע פעולות נפוצות ב-Google Workspace Event 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 מחזירות פעולה ממושכת. אפשר להשתמש ב-method 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);
  }
}

על מנת לקבל את השם של פעולה, יש להשתמש בערך מהשדה name שהוחזר מאחת מהשיטות של Google Workspace Event API, כמו subscriptions.create() או subscriptions.patch().