خدمة أحداث Google Workspace المتقدّمة

تتيح لك خدمة "أحداث Google Workspace" المتقدّمة استخدام Google Workspace Events API في Apps Script. تتيح لك واجهة برمجة التطبيقات هذه الاشتراك في موارد Google Workspace لتلقّي الأحداث ذات الصلة التي تهمّك. تمثّل الأحداث التغييرات التي تطرأ على الموارد، مثل الحالات التي يتم فيها إنشاء الموارد أو تعديلها أو حذفها.

المتطلبات الأساسية

  • مشروع "برمجة تطبيقات Google" يستخدم مشروعًا عاديًا على Google Cloud بدلاً من المشروع التلقائي الذي أنشأته "برمجة تطبيقات Google" تلقائيًا
  • موضوع Pub/Sub تم إنشاؤه في مشروع Google Cloud نفسه لتلقّي أحداث الاشتراك لإنشاء موضوع على Pub/Sub، اطّلِع على مقالة إنشاء موضوع على Pub/Sub والاشتراك فيه.
  • للاشتراك في أحداث Chat، يجب أن يكون لديك تطبيق Google Chat تم ضبطه في صفحة إعدادات Chat API في وحدة تحكّم Google Cloud. لإنشاء تطبيق Google Chat، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat باستخدام لغة برمجة تطبيقات Google.

  • نطاقات التفويض اللازمة التي تمت إضافتها إلى ملف appsscript.json لمشروع Apps Script تعتمد النطاقات اللازمة على أنواع موارد الاشتراكات المستهدَفة والأحداث. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة اختيار نطاقات Google Workspace Events API. على سبيل المثال:

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

مراجع

لمزيد من المعلومات عن هذه الخدمة، يُرجى الاطّلاع على مستندات مرجعية لواجهة برمجة التطبيقات Google Workspace Events API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة "أحداث Google Workspace" العناصر والطُرق والمقاييس نفسها المستخدَمة في واجهة برمجة التطبيقات المتاحة للجميع.

نموذج التعليمات البرمجية

توضِّح لك هذه العيّنات كيفية تنفيذ الإجراءات الشائعة في 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);
  }
}

إدراج الاشتراكات

لعرض الاشتراكات التي تمّت فلترتها حسب أنواع الأحداث والمرجع المستهدَف، أضِف الدالة التالية إلى رمز مشروع "النصوص البرمجية للتطبيقات":

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);
  }
}

تعديل الاشتراك

لتعديل اشتراك أو تجديده، أضِف الدالة التالية إلى رمز مشروع "برمجة تطبيقات Google":

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);
  }
}

إعادة تفعيل الاشتراك

لإعادة تفعيل اشتراك، أضِف الدالة التالية إلى رمز مشروع "برمجة تطبيقات Google":

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().

للحصول على معلومات عن عملية معيّنة، أضِف الدالة التالية إلى رمز مشروع "برمجة التطبيقات":

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 Events API، مثل subscriptions.create() أو subscriptions.patch().