العمل باستخدام الأحداث من 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:

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

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

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

• الاشتراك في الأحداث باستخدام Drive API يمكنك الحصول على أحداث تغيير المستخدمين باستخدام طريقة changes.watch أو أحداث تغيير الملفات باستخدام طريقة files.watch.

• يمكنك الاستعلام عن الأحداث الأخيرة من خلال طلب Google Drive Activity API.

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

بدء استخدام أحداث 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

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

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

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

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

تأكَّد من الإشارة إلى حساب خدمة Drive (drive-api-event-push@system.gserviceaccount.com) لطلباتك.

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

يتم إرسال أحداث Cloud عند تغيير موضوع الاشتراك (أو أي ملف آخر ضمن التسلسل الهرمي للموضوع). على سبيل المثال، إذا أنشأت اشتراكًا في مساحة تخزين سحابي مشتركة وتم تغيير ملف متداخل ضمن عدة مجلدات فرعية في مساحة التخزين السحابي المشتركة هذه، يتم إنشاء حدث. للاطّلاع على الموارد وأنواع أحداث 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/v1/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          'RESOURCE_DATA'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          'INCLUDE_DESCENDANTS'
        }
      }
    },
    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 الذي أنشأته في مشروعك على السحابة الإلكترونية. يتلقّى موضوع 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.

للحصول على معلومات حول حصص الاشتراك وحدود المعدّل، يُرجى الاطّلاع على حدود استخدام Google Workspace Events API.

المواضيع ذات الصلة

• نظرة عامة على Google Workspace Events API
• إنشاء اشتراك في Google Workspace
• الاشتراك في أحداث Google Drive
• حدود استخدام Google Workspace Events API