کار کردن با رویدادها از 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 نوع رویداد
کاربری پیشنهاد دسترسی برای فایلی ایجاد می‌کند. منبع AccessProposal ایجاد شده است. پیشنهاد دسترسی جدید

کاربری تأییدیه‌ای برای فایلی ایجاد می‌کند.

منبع Approval ایجاد شده است. تأییدیه جدید
کاربری در فایل «سندنگار»، «کاربرگ‌نگار»، یا «اسلایدنگار Google» نظری پست می‌کند. منبع Comment ایجاد شده است. نظر جدید
کاربری فایلی را به پوشه یا درایو مشترک اضافه می‌کند. منبع File ایجاد شده است. فایل جدید
کاربری اجازه‌هایی برای فایلی ایجاد می‌کند. منبع Permission ایجاد شده است. اجازه جدید
کاربری به نظری پاسخ دهد. منبع Reply ایجاد شده است. پاسخ جدید

دریافت رویدادها از 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.
  • تغییرات فراداده فایل را شناسایی کنید و با اعلان‌های هم‌زمان، تغییرات موارد خاص را به‌طور مؤثر پایش کنید.
  • از نشانی وب فراخوانی وب‌قلاب پشتیبانی می‌کند تا از نظرسنجی مکرر نقاط پایانی میانای برنامه‌سازی کاربردی جلوگیری شود.
  • سابقه دقیقی از همه فعالیت‌ها، ازجمله اطلاعات جزئی درباره هر رویداد، واکشی کنید.
  • فعالیت‌های دقیقی را که شامل اطلاعات ActionDetail، Actor، و Target است برای کارهای خاصی مثل ممیزی بازیابی کنید.
میانای برنامه‌سازی کاربردی Google Workspace Events API Google Drive API Google Drive Activity API
منبع رویدادها فایل‌ها، پوشه‌ها، و درایوهای مشترک ‫changes.watch و files.watch DriveActivity
رویدادهای پشتیبانی‌شده
  • AccessProposal
  • Approval
  • Comment
  • File
  • Permission
  • Reply
برای مشاهده فهرست انواع رویدادهای پشتیبانی‌شده، به انواع رویداد برای ایجاد اشتراک در سند Google Workspace Events API مراجعه کنید.
Channel

برای مشاهده فهرست انواع رویدادهای پشتیبانی‌شده، به آشنایی با رویدادهای اعلان Google Drive API در اسناد Drive API مراجعه کنید.
Action

برای مشاهده فهرست فیلدهای پشتیبانی‌شده، به منبع Action در اسناد مرجع Drive Activity API مراجعه کنید.
قالب رویداد پیام 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 API، باید آن‌ها را در پروژه Google Cloud فعال کنید. می‌توانید یک یا چند میانای برنامه‌سازی کاربردی را در یک پروژه Google Cloud روشن کنید.

;کنسول Google Cloud

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

    فعال کردن میاناهای برنامه‌سازی کاربردی

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

  3. مطمئن شوید که میاناهای برنامه‌سازی کاربردی درست را فعال می‌کنید، سپس روی فعال کردن کلیک کنید.

gcloud

  1. در فهرست راهنمای کاری‌تان، به سیستم «حساب Google» خود وارد شوید:

    gcloud auth login
  2. پروژه‌تان را روی پروژه Cloud برای برنامه‌تان تنظیم کنید:

    gcloud config set project PROJECT_ID

    PROJECT_ID را با شناسه پروژه برای پروژه Cloud برنامه‌تان جایگزین کنید.

  3. Google Workspace Events API،‏ Pub/Sub API، و Drive 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، به ایجاد کردن و مشترک شدن در موضوع 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 تنظیم شده باشد. نمی‌تواند روی پوشه ریشه 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 بااستفاده از 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 مراجعه کنید.