تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

العمل باستخدام الأحداث من Google Drive

توضّح هذه الصفحة كيفية تلقّي أحداث Google Drive من خلال خدمة Google Cloud Pub/Sub.

يمثّل حدث Drive نشاطًا أو تغييرًا في أحد موارد Drive، مثل ملف جديد في مجلد. يمكنك استخدام الأحداث للتعرّف على ما حدث ثم اتّخاذ إجراء أو الردّ بطريقة مفيدة للمستخدمين.

في ما يلي بعض الأمثلة على كيفية استخدام الأحداث:

مراقبة التغييرات في ملف أو مجلد أو مساحة تخزين سحابي مشتركة والردّ عليها، مثل عند تعديل ملف أو تحميل مراجعة جديدة
تتبُّع التغييرات في الملفات لتحسين أداء تطبيقك
تدقيق الأنشطة، مثل مشاركة الملفات ونقلها وحذفها، للمساعدة في رصد حالات تسرُّب البيانات المحتملة والوصول غير المصرّح به
تقديم إحصاءات حول كيفية إدارة المستخدمين لملفاتهم، ما يساعد في تحديد المجالات التي يمكن تحسين إدارة المحتوى فيها
تتبُّع تغييرات الملفات للتحقّق من الامتثال للمتطلبات التنظيمية أو سياسات الأمان
تحليل نشاط Drive باستخدام منتجات أخرى من Google Cloud، مثل Eventarc وWorkflows وBigQuery

طريقة عمل الأحداث

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

يصنّف Drive الأحداث حسب النوع. تساعدك أنواع الأحداث في فلترة المعلومات وتلقّي النوع الذي تحتاجه فقط، كما تتيح لك التعامل مع الأنشطة المشابهة بالطريقة نفسها.

يوضّح الجدول التالي كيف يؤثّر نشاط في Drive على مرجع ذي صلة في Drive API، ونوع الحدث الذي يتلقّاه تطبيق Drive:

النشاط	مرجع Drive API	نوع الحدث
يضيف مستخدم ملفًا إلى مجلد أو مساحة تخزين سحابي مشتركة.	يتم إنشاء مورد `File`.	ملف جديد
ينشئ المستخدم اقتراحًا بشأن إذن الوصول إلى ملف.	يتم إنشاء مورد `AccessProposal`.	اقتراح وصول جديد

تلقّي أحداث من Google Drive

في السابق، كان بإمكان تطبيق Drive تحديد موقع الأحداث من خلال Drive API أو Google Drive Activity API. مع إضافة أحداث Drive في Google Workspace Events API، أصبح هناك الآن طريقة ثالثة لتلقّي الأحداث:

إصدار تجريبي للمطوّرين: يمكنك الاشتراك في الأحداث باستخدام Google Workspace Events API لتلقّي الأحداث فور حدوثها. لمزيد من المعلومات، يُرجى الاطّلاع على الاشتراك في إشعارات أحداث Google Drive.
الاشتراك في الأحداث باستخدام Drive API يمكنك الحصول على أحداث تغيير المستخدمين باستخدام الطريقة changes.watch أو أحداث تغيير الملفات باستخدام الطريقة files.watch.
يمكنك طلب الأحداث الأخيرة من خلال استدعاء Google Drive Activity API.

يوضّح الجدول التالي الفرق بين الاشتراك في الأحداث والاستعلام عنها وأسباب ذلك:

	الاشتراك في فعاليات Google Workspace	الاشتراك في أحداث المراقبة في Drive API	طلب البحث عن أحداث Drive Activity API
حالات الاستخدام	معالجة الأحداث أو الردّ عليها في الوقت الفعلي تتبُّع التغييرات في الموارد لتحسين أداء تطبيقك تلقّي بيانات الأحداث المنظَّمة من خلال Pub/Sub واستخدام منتجات Google Cloud، مثل Cloud Run	رصد التغييرات في البيانات الوصفية للملفات وتتبُّع التغييرات في عناصر معيّنة بكفاءة من خلال الإشعارات في الوقت الفعلي يتيح استخدام عنوان URL لردّ ويب هوك لتجنُّب تكرار طلب نقاط نهاية واجهة برمجة التطبيقات.	استرداد سجلّ تفصيلي لجميع الأنشطة، بما في ذلك معلومات دقيقة عن كل حدث استرداد الأنشطة الدقيقة التي تتضمّن معلومات `ActionDetail` و`Actor` و`Target` لمهام معيّنة، مثل عمليات التدقيق
واجهة برمجة التطبيقات	واجهة برمجة التطبيقات لفعاليات Google Workspace	واجهة برمجة تطبيقات Drive	Drive Activity API
مصدر الأحداث	الملفات والمجلدات ومساحات التخزين السحابي المشتركة	`changes.watch` و`files.watch`	`DriveActivity`
الأحداث المتوافقة	`File` `AccessProposal` للحصول على قائمة بأنواع الأحداث المتوافقة، يُرجى الاطّلاع على أنواع الأحداث لإنشاء الاشتراكات في مستندات "واجهة برمجة تطبيقات أحداث Google Workspace".	`Channel` للاطّلاع على قائمة بأنواع الأحداث المتوافقة، يُرجى الانتقال إلى التعرّف على أحداث الإشعارات في Google Drive API في مستندات Drive API.	`Action` للاطّلاع على قائمة بالحقول المتوافقة، يُرجى الرجوع إلى المرجع `ActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionActionAction`�
تنسيق الحدث	رسالة Pub/Sub منسَّقة وفقًا لمواصفات CloudEvent لمزيد من التفاصيل، يُرجى الاطّلاع على بنية أحداث Google Workspace.	أحد موارد Drive API (`Channel`)	أحد موارد Drive Activity API (`Action`)
بيانات الأحداث	سلسلة مرمّزة باستخدام Base64 تتضمّن بيانات المورد أو لا تتضمّنها للاطّلاع على أمثلة للحِزم، راجِع بيانات الأحداث.	حِمل JSON يحتوي على بيانات الموارد للاطّلاع على مثال على الحمولة، راجِع مورد `Channel` في المستندات المرجعية.	حِمل JSON يحتوي على بيانات الموارد للاطّلاع على مثال للحِمل، راجِع نص الرد `activity.query` في المستندات المرجعية.

بدء استخدام أحداث Drive

يوضّح هذا الدليل كيفية إنشاء اشتراك في أحداث Google Workspace وإدارته على أحد موارد Drive. يتيح ذلك لتطبيقك تلقّي الأحداث عبر Google Cloud Pub/Sub.

إنشاء مشروع على Google Cloud

لإنشاء مشروع على Google Cloud، يُرجى الاطّلاع على إنشاء مشروع على Google Cloud.

تفعيل واجهة Google Workspace Events API وواجهة Google Cloud Pub/Sub API وواجهة Google Drive API

قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

Google Cloud Console

في "وحدة تحكّم Google Cloud"، افتح مشروع Google Cloud لتطبيقك وفعِّل واجهة برمجة التطبيقات Google Workspace Events API وواجهة برمجة التطبيقات Pub/Sub API وواجهة برمجة التطبيقات Drive API:

تفعيل واجهات برمجة التطبيقات
تأكَّد من أنّك بصدد تفعيل واجهات برمجة التطبيقات في مشروع Cloud الصحيح، ثم انقر على التالي.
تأكَّد من تفعيل واجهات برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

gcloud

في دليل العمل، سجِّل الدخول إلى حسابك على Google:
```
gcloud auth login
```
اضبط مشروعك على مشروع Cloud لتطبيقك:
```
gcloud config set project PROJECT_ID
```
استبدِل PROJECT_ID بمعرّف المشروع لمشروع Cloud الخاص بتطبيقك.
فعِّل واجهة برمجة التطبيقات لفعاليات Google Workspace وواجهة برمجة التطبيقات Pub/Sub وواجهة برمجة التطبيقات Drive:
```
gcloud services enable workspaceevents.googleapis.com \
pubsub.googleapis.com \
drive.googleapis.com
```

إعداد معرّف عميل

لإنشاء معرّف عميل OAuth 2.0، يُرجى الاطّلاع على إنشاء بيانات اعتماد معرّف عميل OAuth.

إنشاء موضوع Pub/Sub

قبل إنشاء اشتراك، يجب إنشاء موضوع Google Cloud Pub/Sub يتلقّى الأحداث ذات الصلة التي يهتم بها تطبيقك. لإنشاء موضوع Pub/Sub، يُرجى الاطّلاع على مقالة إنشاء موضوع Pub/Sub والاشتراك فيه.

احرص على الإشارة إلى حساب خدمة Drive (drive-api-event-push@system.gserviceaccount.com) في طلباتك.

إنشاء اشتراك في Drive

يتم إرسال أحداث السحابة الإلكترونية عند تغيُّر موضوع الاشتراك (أو أي ملف آخر ضمن التسلسل الهرمي للموضوع). على سبيل المثال، إذا أنشأت اشتراكًا في مساحة تخزين سحابي مشتركة وتم تغيير ملف مضمّن في عدّة مجلدات فرعية في مساحة التخزين السحابي المشتركة هذه، سيؤدي ذلك إلى إنشاء حدث. للاطّلاع على الموارد وأنواع أحداث Drive المتوافقة، يُرجى الرجوع إلى أنواع الأحداث لإنشاء الاشتراكات.

ينشئ تطبيق Node.js التالي اشتراكًا في أحداث Drive على ملف أو مجلد للاستماع إلى أحداث تغيير المحتوى. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء اشتراك في Google Workspace.

لتنفيذ هذا المثال، تأكَّد من تثبيت Node.js وnpm. عليك أيضًا التأكّد من تثبيت التبعيات المطلوبة لتشغيل هذا المثال.

# Install needed dependencies
$ npm install googleapis @google-cloud/local-auth axios

لإنشاء اشتراك في Drive، يمكنك استخدام طريقة subscriptions.create() في Google Workspace Events API لإنشاء مورد Subscription:

// app.js

const fs = require('fs').promises;
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const axios = require('axios');

// Scopes for Google Drive API access.
const SCOPES = ['SCOPES'];

/**
 * Authenticates the user running the script.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  const client = await authenticate({
    scopes: SCOPES,
    keyfilePath: 'credentials.json',
  });
  if (client.credentials) {
    const content = await fs.readFile('credentials.json');
    const keys = JSON.parse(content);
    const {client_id, client_secret} = keys.installed || keys.web;
    const payload = JSON.stringify({
      type: 'authorized_user',
      client_id,
      client_secret,
      refresh_token: client.credentials.refresh_token,
    });
    await fs.writeFile('token.json', payload);
    return client;
  } else {
    throw new Exception(
        'credentials.json did not have the Oauth client secret or it was not properly formatted');
  }
  }

/**
 * Creates a subscription to Google Drive events.
 * @param {OAuth2Client} authClient An authorized OAuth2 client.
 */
async function createSubscription(authClient) {
  const url = 'https://workspaceevents.googleapis.com/v1beta/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          '<var>RESOURCE_DATA</var>'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          '<var>INCLUDE_DESCENDANTS</var>'
        }
      }
    },
    notification_endpoint: {pubsub_topic: 'TOPIC_NAME'}
  };
  try {
    const {token} = await authClient.getAccessToken();
    const response = await axios.post(
        url, data, {headers: {'Authorization': `Bearer ${token}`}});
    console.log('Subscription created:', response.data);
  } catch (error) {
    const message = error.response ? error.response.data : error.message;
    console.error('Error creating subscription:', message);
  }
}

authorize().then(createSubscription).catch(console.error);

غيِّر القيم في السلسلة على الشكل التالي:

SCOPES: نطاق واحد أو أكثر من نطاقات OAuth التي تتوافق مع كل نوع من أنواع الأحداث في الاشتراك. يتم تنسيقه كصفيف من السلاسل. لإدراج نطاقات متعددة، افصل بينها بفواصل. من أفضل الممارسات استخدام النطاق الأكثر تقييدًا الذي يتيح لتطبيقك مواصلة العمل. على سبيل المثال، 'https://www.googleapis.com/auth/drive.file'.
‫TARGET_RESOURCE: مرجع Google Workspace الذي تشترك فيه، بتنسيق اسم المرجع الكامل. على سبيل المثال، للاشتراك في ملف أو مجلد في Drive، استخدِم //drive.googleapis.com/files/FileID.
EVENT_TYPES: تمثّل هذه السمة نوعًا واحدًا أو أكثر من أنواع الأحداث التي تريد الاشتراك فيها في المرجع المستهدف. يجب أن يكون التنسيق عبارة عن مصفوفة من السلاسل، مثل 'google.workspace.drive.file.v3.contentChanged'.
‫RESOURCE_DATA: قيمة منطقية تحدّد ما إذا كان الاشتراك يتضمّن بيانات الموارد في حمولة الحدث. تؤثّر هذه السمة في مدة اشتراكك. لمزيد من المعلومات، اطّلِع على بيانات الأحداث.
- ‫True: تتضمّن جميع بيانات الموارد. للحدّ من الحقول التي يتم تضمينها، أضِف fieldMask وحدِّد حقلًا واحدًا على الأقل للمورد الذي تم تغييره. تتوفّر الاشتراكات في موارد Chat وDrive فقط، بما في ذلك بيانات الموارد.
- False: يستبعد بيانات الموارد.
INCLUDE_DESCENDANTS: حقل منطقي يشكّل جزءًا من DriveOptions لا تتوفّر هذه السمة إلا عندما يكون targetResource ملفًا على Drive أو مساحة تخزين سحابي مشتركة تم ضبط نوع MIME فيها على application/vnd.google-apps.folder. لا يمكن ضبطها على المجلد الجذر في "ملفاتي" أو مساحات التخزين السحابي المشتركة.
- True: يتضمّن الاشتراك جميع ملفات Drive الفرعية في قائمة الأحداث.
- ‫False: يتم إنشاء الاشتراك للملف الفردي أو مساحة التخزين السحابي المشتركة المحدّدة كـ targetResource.
TOPIC_NAME: الاسم الكامل لموضوع Pub/Sub الذي أنشأته في مشروعك على السحابة الإلكترونية يتلقّى موضوع النشر/الاشتراك هذا الأحداث الخاصة بالاشتراك. تم تنسيقه على النحو التالي: projects/PROJECT_ID/topics/TOPIC_ID. يُستخدَم الحقل notificationEndpoint لتحديد موضوع Pub/Sub، وهو المكان الذي يقدّم فيه الاشتراك الأحداث.

اختبار اشتراكك في Drive

لاختبار تلقّي أحداث Drive، يمكنك تشغيل حدث واسترداد الرسائل إلى اشتراك Pub/Sub. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختبار اشتراكك في Google Workspace.

معالجة أحداث Drive باستخدام Cloud Functions

يتم إرسال أحداث Drive إلى موضوع Pub/Sub في الاشتراك الذي تنشئه. عند إنشاء المشغّل، تأكَّد من أنّ موضوع Pub/Sub الخاص بالمشغّل يتطابق مع موضوع Pub/Sub في اشتراكك في الأحداث. يمكنك بعد ذلك نشر دالة Cloud Run وإجراء تعديلات على الملف للاطّلاع على تغييرات الأحداث في السجلات.

قبل إنشاء الدالة، عدِّل package.json للتبعيات:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "cloudevents": "^8.0.0"
  }
}

بعد ذلك، أنشئ رمز المصدر للدالة:

const functions = require('@google-cloud/functions-framework');
const { HTTP } = require("cloudevents");

/**
 * A Cloud Function triggered by Pub/Sub messages containing Google Drive activity events.
 * This function processes different types of Drive events.
 *
 * @param {object} cloudEvent The CloudEvent object.
 * @param {object} cloudEvent.data The data payload from the event source.
 */
functions.cloudEvent('helloFromDrive', async (cloudEvent) => {
  try {
    // Verify the Pub/Sub message exists
    if (!cloudEvent.data || !cloudEvent.data.message) {
      console.warn("Event is missing the Pub/Sub message payload.");
      return;
    }

    // Extract the Pub/Sub message details
    const { message } = cloudEvent.data;
    const { attributes, data } = message;

    // The original Drive CloudEvent is reconstructed from the Pub/Sub message attributes
    const driveEvent = HTTP.toEvent({ headers: attributes });
    const { type } = driveEvent;

    // The Drive event's payload is a base64 encoded JSON string
    const payload = JSON.parse(Buffer.from(data, "base64").toString());

    console.log(`Processing Drive event type: ${type}`);

    // Use a switch statement to handle different event types
    switch (type) {
      case 'google.workspace.drive.file.v3.contentChanged':
        console.log('File Content Changed:', payload);
        break;
      case 'google.workspace.drive.accessproposal.v3.created':
        console.log('Access Proposal Created:', payload);
        break;
      default:
        console.log(`Received unhandled event type: ${type}`);
        break;
    }
  } catch (error) {
    console.error("An error occurred while processing the Drive event:", error);
  }
});

القيود

عندما تكون قيمة الحقل المنطقي includeDescendants في DriveOptions هي true، ترسل اشتراكات Drive في مساحات التخزين السحابي المشتركة والمجلدات حدثًا دائمًا، حتى إذا كان الملف الذي أدى إلى تشغيل الحدث مضمّنًا في عدة طبقات أسفل المجلد المستخدَم للاشتراك في Drive.
على الرغم من أنّك قد تكون أنشأت اشتراكًا في مجلد، قد لا تتلقّى جميع الأحداث ضمن التسلسل الهرمي للملفات لأنّه قد لا يتم منح المستخدم أو التطبيق إذن الوصول إليها. في هذه الحالة، يظل الاشتراك نشطًا ولكن لن تتلقّى أي أحداث للموارد التي لا يمكنك الوصول إليها.
تتوفّر الاشتراكات للأحداث على جميع الملفات والمجلدات، ولكن ليس على المجلد الجذر لمساحات التخزين السحابي المشتركة. لا تتوفّر الاشتراكات إلا للملفات والمجلدات داخل مساحات التخزين السحابي المشتركة. لن تؤدي التغييرات التي يتم إجراؤها مباشرةً على المجلد الجذر في مساحات التخزين السحابي المشتركة إلى تشغيل الأحداث.
يجب أن يكون لدى المستخدم الذي يمنح الإذن بالاشتراك إذن بالملف الذي يتضمّن الأحداث التي يريد الاشتراك فيها.
لا يتلقّى الاشتراك سوى أحداث الموارد التي يمكن للمستخدم الوصول إليها من خلال حسابه على Google Workspace أو حسابه على Google.