با رویدادهای Google Drive کار کنید

پیش‌نمایش توسعه‌دهندگان: به عنوان بخشی از برنامه پیش‌نمایش توسعه‌دهندگان Google Workspace موجود است که دسترسی زودهنگام به برخی ویژگی‌ها را فراهم می‌کند.

این صفحه نحوه دریافت رویدادهای گوگل درایو از Google Cloud Pub/Sub را توضیح می‌دهد.

یک رویداد Drive نشان دهنده یک فعالیت یا تغییر در یک منبع Drive است، مانند یک فایل جدید در یک پوشه. شما می‌توانید از رویدادها برای درک آنچه اتفاق افتاده و سپس انجام اقدام یا برای پاسخ دادن به کاربران خود به روشی معنادار استفاده کنید.

در اینجا چند مثال از نحوه استفاده از رویدادها آورده شده است:

• مشاهده و پاسخ به تغییرات در یک فایل، پوشه یا درایو مشترک، مانند زمانی که یک فایل ویرایش می‌شود یا یک نسخه جدید آپلود می‌شود.

• تغییرات فایل‌ها را برای بهبود عملکرد برنامه خود زیر نظر بگیرید.

• فعالیت‌های حسابرسی مانند اشتراک‌گذاری فایل، انتقال فایل و حذف فایل‌ها را برای کمک به شناسایی نشت‌های احتمالی داده‌ها و دسترسی غیرمجاز انجام دهید.

• ارائه بینش‌هایی در مورد نحوه مدیریت فایل‌های کاربران، به شناسایی حوزه‌هایی که مدیریت محتوا می‌تواند بهبود یابد.

• پیگیری تغییرات فایل‌ها برای تأیید انطباق با الزامات نظارتی یا سیاست‌های امنیتی.

• فعالیت Drive را با استفاده از سایر محصولات Google Cloud مانند Eventarc ، Workflows و BigQuery تجزیه و تحلیل کنید.

نحوه عملکرد رویدادها

هر زمان که اتفاقی در درایو رخ می‌دهد، یک منبع API گوگل درایو ایجاد، به‌روزرسانی یا حذف می‌شود. درایو از رویدادها برای ارائه اطلاعات به برنامه شما در مورد نوع فعالیت رخ داده و منبع API درایو که تحت تأثیر قرار گرفته است، استفاده می‌کند.

درایو رویدادها را بر اساس نوع دسته‌بندی می‌کند. انواع رویدادها به شما کمک می‌کنند تا فقط نوع اطلاعات مورد نیاز خود را فیلتر و دریافت کنید و به شما امکان می‌دهد فعالیت‌های مشابه را به یک روش مدیریت کنید.

جدول زیر نشان می‌دهد که چگونه یک فعالیت نمونه در Drive بر یک منبع Drive API مرتبط تأثیر می‌گذارد و نوع رویدادی که برنامه Drive شما دریافت می‌کند را نشان می‌دهد:

فعالیت	منبع API درایو	نوع رویداد
کاربر یک پیشنهاد دسترسی روی یک فایل ایجاد می‌کند.	یک منبع AccessProposal ایجاد می‌شود.	پیشنهاد دسترسی جدید
یک کاربر در یک فایل Google Docs، Sheets یا Slides نظر خود را ارسال می‌کند.	یک منبع Comment ایجاد می‌شود.	نظر جدید
کاربر فایلی را به یک پوشه یا درایو مشترک اضافه می‌کند.	یک منبع File ایجاد می‌شود.	فایل جدید
یک کاربر به یک نظر پاسخ می‌دهد.	یک منبع Reply ایجاد می‌شود.	پاسخ جدید

دریافت رویدادها از گوگل درایو

به طور سنتی، برنامه Drive شما می‌توانست رویدادها را از طریق Drive API یا Google Drive Activity API پیدا کند. با اضافه شدن رویدادهای Drive در Google Workspace Events API، اکنون روش سومی برای دریافت رویدادها وجود دارد:

• پیش‌نمایش توسعه‌دهندگان : با استفاده از رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API) در رویدادها مشترک شوید تا رویدادها را به محض وقوع دریافت کنید. برای اطلاعات بیشتر، به «مشترک شدن در رویدادهای گوگل درایو» مراجعه کنید.

• با استفاده از Drive API در رویدادها مشترک شوید. رویدادهای تغییر کاربر را با متد changes.watch یا رویدادهای تغییر فایل را با استفاده از متد files.watch دریافت کنید.

• با فراخوانی API فعالیت گوگل درایو، رویدادهای اخیر را جستجو کنید.

جدول زیر تفاوت و دلایل اشتراک در رویدادها در مقابل پرس و جو برای آنها را توضیح می‌دهد:

	در رویدادهای Google Workspace مشترک شوید	برای مشاهده رویدادهای Drive API مشترک شوید	جستجوی رویدادهای API فعالیت درایو
موارد استفاده	رویدادها را در زمان واقعی پردازش یا پاسخ دهید. برای بهبود عملکرد برنامه خود، تغییرات در منابع را زیر نظر بگیرید. داده‌های رویداد ساختاریافته را از طریق Pub/Sub دریافت کنید و از محصولات Google Cloud مانند Cloud Run استفاده کنید.	تغییرات در متادیتای فایل را تشخیص داده و با اعلان‌های بلادرنگ، تغییرات موارد خاص را به طور مؤثر رصد کنید. از یک URL فراخوانی وب‌هوک پشتیبانی می‌کند تا از نمونه‌برداری مکرر نقاط انتهایی API جلوگیری شود.	تاریخچه دقیقی از تمام فعالیت‌ها، شامل اطلاعات جزئی در مورد هر رویداد، را دریافت کنید. فعالیت‌های دقیقی را که شامل اطلاعات ActionDetail ، Actor و Target برای وظایف خاص مانند حسابرسی‌ها می‌شود، بازیابی کنید.
رابط برنامه‌نویسی کاربردی (API)	رابط برنامه‌نویسی کاربردی رویدادهای فضای کاری گوگل (Google Workspace Events API)	رابط برنامه‌نویسی کاربردی گوگل درایو	رابط برنامه‌نویسی کاربردی فعالیت گوگل درایو
منبع رویدادها	فایل‌ها، پوشه‌ها و درایوهای اشتراکی	changes.watch و files.watch	DriveActivity
رویدادهای پشتیبانی شده	AccessProposal Comment File Reply برای مشاهده فهرستی از انواع رویدادهای پشتیبانی‌شده، به بخش انواع رویدادها برای ایجاد اشتراک‌ها در مستندات Google Workspace Events API مراجعه کنید.	Channel برای مشاهده فهرستی از انواع رویدادهای پشتیبانی‌شده، به بخش «درک رویدادهای اعلان API گوگل درایو» در مستندات Drive API مراجعه کنید.	Action برای مشاهده فهرست فیلدهای پشتیبانی‌شده، به منبع Action در مستندات مرجع Drive Activity API مراجعه کنید.
قالب رویداد	یک پیام Pub/Sub، که مطابق با مشخصات CloudEvent قالب‌بندی شده است. برای جزئیات بیشتر، به ساختار رویدادهای Google Workspace مراجعه کنید.	یک منبع API درایو ( Channel )	یک منبع API مربوط به فعالیت درایو ( Action )
داده‌های رویداد	رشته کدگذاری شده با Base64 با یا بدون داده‌های منبع. برای مثال، payloadها، به Event data مراجعه کنید.	بار داده JSON که حاوی داده‌های منبع است. برای مثال، به منبع Channel در مستندات مرجع مراجعه کنید.	بار داده JSON که شامل داده‌های منبع است. برای مثال، به بدنه پاسخ activity.query در مستندات مرجع مراجعه کنید.

شروع به کار با رویدادهای Drive

این راهنما نحوه ایجاد و مدیریت اشتراک رویدادهای Google Workspace را در یک منبع Drive توضیح می‌دهد. این به برنامه شما اجازه می‌دهد رویدادها را از طریق Google Cloud Pub/Sub دریافت کند.

ایجاد یک پروژه گوگل کلود

برای ایجاد یک پروژه Google Cloud، به ایجاد یک پروژه Google Cloud مراجعه کنید.

فعال کردن API رویدادهای Google Workspace، API Google Cloud Pub/Sub و API Google Drive

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.

کنسول گوگل کلود

1. در کنسول Google Cloud، پروژه Google Cloud مربوط به برنامه خود را باز کنید و API رویدادهای Google Workspace، API Pub/Sub و API Drive را فعال کنید:

   فعال کردن APIها

2. تأیید کنید که APIها را در پروژه Cloud صحیح فعال می‌کنید، سپس روی Next کلیک کنید.

3. تأیید کنید که API های صحیح را فعال می‌کنید، سپس روی فعال کردن کلیک کنید.

جی‌کلاود

1. در دایرکتوری کاری خود، به حساب گوگل خود وارد شوید:

   gcloud auth login

2. پروژه خود را برای برنامه خود روی پروژه Cloud تنظیم کنید:

   gcloud config set project PROJECT_ID

   به جای PROJECT_ID شناسه پروژه مربوط به پروژه ابری برنامه خود را وارد کنید.

3. فعال کردن API رویدادهای Google Workspace، API Pub/Sub و API درایو:

   gcloud services enable workspaceevents.googleapis.com \
   pubsub.googleapis.com \
   drive.googleapis.com

تنظیم شناسه مشتری

برای ایجاد شناسه کلاینت OAuth 2.0، به بخش «ایجاد اعتبارنامه‌های شناسه کلاینت OAuth» مراجعه کنید.

ایجاد یک موضوع عمومی/زیرموضوعی

قبل از ایجاد اشتراک، باید یک موضوع Pub/Sub در Google Cloud ایجاد کنید که رویدادهای مرتبط مورد علاقه برنامه شما را دریافت کند. برای ایجاد موضوع Pub/Sub، به بخش «ایجاد و اشتراک در یک موضوع Pub/Sub» مراجعه کنید.

حتماً برای درخواست‌های خود به حساب سرویس Drive ( [e-mail] ) ارجاع دهید.

ایجاد اشتراک درایو

بتا: رویدادهای درایو در پیش‌نمایش توسعه‌دهندگان هستند. شما باید از نسخه v1beta این API استفاده کنید. تلاش برای استفاده از نسخه استاندارد v1 API با شکست مواجه خواهد شد.

رویدادهای ابری زمانی ارسال می‌شوند که موضوع اشتراک (یا هر فایل دیگری که در سلسله مراتب موضوع قرار دارد) تغییر کند. برای مثال، اگر در یک درایو مشترک، اشتراکی ایجاد کنید و فایلی که در چندین زیرپوشه در آن درایو مشترک قرار دارد تغییر کند، یک رویداد ایجاد می‌شود. برای منابع پشتیبانی شده و انواع رویدادهای درایو، به انواع رویداد برای ایجاد اشتراک‌ها مراجعه کنید.

برنامه Node.js زیر یک اشتراک رویدادهای Drive روی یک فایل یا پوشه ایجاد می‌کند تا به رویدادهای تغییر محتوا گوش دهد. برای اطلاعات بیشتر، به ایجاد اشتراک Google Workspace مراجعه کنید.

برای اجرای این مثال، مطمئن شوید که Node.js و npm را نصب کرده‌اید . همچنین باید مطمئن شوید که وابستگی‌های مورد نیاز برای اجرای این مثال را نصب کرده‌اید.

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

برای ایجاد اشتراک Drive، از متد subscriptions.create() از API رویدادهای Google Workspace برای ایجاد یک منبع 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 : یک مقدار بولی که مشخص می‌کند آیا اشتراک شامل داده‌های منبع در payload رویداد می‌شود یا خیر. این ویژگی بر مدت زمان اشتراک شما تأثیر می‌گذارد. برای کسب اطلاعات بیشتر، به Event data مراجعه کنید.

  • True : شامل تمام داده‌های منبع می‌شود. برای محدود کردن اینکه کدام فیلدها شامل شوند، fieldMask اضافه کنید و حداقل یک فیلد برای منبع تغییر یافته مشخص کنید. فقط اشتراک‌های پشتیبانی از منابع Chat و Drive شامل داده‌های منبع می‌شوند.

  • False : داده‌های منابع را شامل نمی‌شود.

• INCLUDE_DESCENDANTS : یک فیلد بولی که بخشی از DriveOptions است. فقط زمانی در دسترس است که targetResource یا یک فایل Drive یا یک درایو مشترک باشد که نوع MIME آن روی application/vnd.google-apps.folder تنظیم شده باشد. نمی‌توان آن را روی پوشه ریشه My Drive یا درایوهای مشترک تنظیم کرد.

  • True : این اشتراک شامل تمام فایل‌های Drive نسل بعدی در لیست رویدادها می‌شود.

  • False : اشتراک برای فایل یا درایو اشتراکی که به عنوان targetResource مشخص شده است، ایجاد می‌شود.

• TOPIC_NAME : نام کامل موضوع Pub/Sub که در پروژه Cloud خود ایجاد کرده‌اید. این موضوع Pub/Sub رویدادهای مربوط به اشتراک را دریافت می‌کند. به صورت projects/ PROJECT_ID /topics/ TOPIC_ID قالب‌بندی شده است. فیلد notificationEndpoint برای مشخص کردن موضوع Pub/Sub استفاده می‌شود و جایی است که اشتراک، رویدادها را ارائه می‌دهد.

اشتراک Drive خود را آزمایش کنید

برای بررسی اینکه آیا رویدادهای Drive را دریافت می‌کنید، می‌توانید یک رویداد را فعال کنید و پیام‌ها را به اشتراک Pub/Sub منتقل کنید. برای اطلاعات بیشتر، به بخش «تست اشتراک Google Workspace» مراجعه کنید.

پردازش رویدادهای 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 خود به آنها دسترسی دارد.

مباحث مرتبط

• مرور کلی API رویدادهای Google Workspace
• ایجاد اشتراک Google Workspace
• در رویدادهای گوگل درایو مشترک شوید