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

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

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

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

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

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

مَراجع

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

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

توضّح لك هذه النماذج كيفية تنفيذ الإجراءات الشائعة في Google Workspace Events API باستخدام الخدمة المتقدّمة.

إنشاء اشتراك

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

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

الاشتراك

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

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

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

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

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

حذف الاشتراك

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

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