العمل باستخدام الأحداث من Google Drive (original) (raw)

توضّح هذه الصفحة كيفية تلقّي أحداث 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 Events API لتلقّي الأحداث فور حدوثها. لمزيد من المعلومات، يُرجى الاطّلاع على الاشتراك في إشعارات أحداث 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 وGoogle Cloud Pub/Sub API وGoogle Drive API

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

Google Cloud Console

1. في "وحدة تحكّم Google Cloud"، افتح مشروع Google Cloud لتطبيقك وفعِّل واجهة Google Workspace Events API وواجهة Pub/Sub API وواجهة Drive API:
   تفعيل واجهات برمجة التطبيقات
2. تأكَّد من أنّك بصدد تفعيل واجهات برمجة التطبيقات في مشروع Cloud الصحيح، ثم انقر على التالي.
3. تأكَّد من تفعيل واجهات برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

gcloud

1. في دليل العمل، سجِّل الدخول إلى حسابك على Google:

gcloud auth login  

1. اضبط مشروعك على مشروع Cloud لتطبيقك:

gcloud config set project PROJECT_ID  

استبدِل PROJECT_ID بمعرّف المشروع لمشروع Cloud الخاص بتطبيقك. 3. فعِّل واجهة برمجة التطبيقات لفعاليات 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 باستخدام "وظائف السحابة الإلكترونية"

يتم إرسال أحداث 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
• الاشتراك في أحداث Google Drive