این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

تغییرات یک فایل، پوشه، یا درایو مشترک را مشاهده کرده و به آنها پاسخ دهید، مانند زمانی که یک فایل ویرایش می شود یا یک نسخه جدید آپلود می شود.
برای بهبود عملکرد برنامه خود، تغییرات فایل ها را نظارت کنید.
فعالیت‌های حسابرسی مانند اشتراک‌گذاری فایل، جابجایی فایل، و حذف برای کمک به شناسایی نشت داده‌های احتمالی و دسترسی غیرمجاز.
بینش هایی در مورد نحوه مدیریت فایل های کاربران توسط کاربران ارائه دهید و به شناسایی مناطقی که مدیریت محتوا می تواند بهبود یابد کمک می کند.
ردیابی تغییرات فایل برای تأیید انطباق با الزامات قانونی یا سیاست های امنیتی.
فعالیت Drive را با استفاده از سایر محصولات Google Cloud مانند Eventarc ، Workflows ، و BigQuery تجزیه و تحلیل کنید.

رویدادها چگونه کار می کنند

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

Drive رویدادها را بر اساس نوع دسته بندی می کند. انواع رویداد به شما کمک می کند تا تنها نوع اطلاعاتی را که نیاز دارید فیلتر کرده و دریافت کنید و به شما امکان می دهد فعالیت های مشابه را به همان روش انجام دهید.

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

فعالیت	منبع API Drive	نوع رویداد
کاربر یک فایل را به یک پوشه یا درایو مشترک اضافه می کند.	یک منبع `File` ایجاد می شود.	فایل جدید
کاربر یک پیشنهاد دسترسی روی یک فایل ایجاد می کند.	یک منبع `AccessProposal` ایجاد می شود.	پیشنهاد دسترسی جدید

رویدادها را از Google Drive دریافت کنید

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

پیش‌نمایش توسعه‌دهنده : با استفاده از Google Workspace Events API در رویدادها مشترک شوید تا رویدادها را هنگام وقوع دریافت کنید.
با استفاده از Drive API در رویدادها مشترک شوید. رویدادهای تغییر کاربر را با روش changes.watch یا رویدادهای تغییر فایل با استفاده از روش files.watch دریافت کنید.
برای رویدادهای اخیر با تماس با Google Drive Activity API پرس و جو کنید.

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

	در رویدادهای Google Workspace مشترک شوید	در رویدادهای تماشای Drive API مشترک شوید	پرس و جو برای رویدادهای API Activity Drive
موارد استفاده کنید	رویدادها را در زمان واقعی پردازش یا پاسخ دهید. تغییرات در منابع را برای بهبود عملکرد برنامه خود نظارت کنید. داده‌های رویداد ساختاریافته را از طریق Pub/Sub دریافت کنید و از محصولات Google Cloud مانند Cloud Run استفاده کنید.	تشخیص تغییرات در فراداده فایل و نظارت موثر بر تغییرات در موارد خاص با اعلان های زمان واقعی. برای جلوگیری از نظرسنجی مکرر نقاط پایانی API از یک URL بازگشت به تماس وب هوک پشتیبانی می کند.	تاریخچه مفصلی از همه فعالیت‌ها، از جمله اطلاعات کامل درباره هر رویداد را واکشی کنید. بازیابی فعالیت‌های دقیقی که شامل اطلاعات `ActionDetail` ، `Actor` و `Target` برای کارهای خاص مانند ممیزی است.
API	Google Workspace Events API	Drive API	Drive Activity API
منبع حوادث	فایل ها، پوشه ها و درایوهای مشترک	`changes.watch` و `files.watch`	`DriveActivity`
رویدادهای پشتیبانی شده	`File` `AccessProposal` برای فهرستی از انواع رویدادهای پشتیبانی شده، انواع رویداد برای ایجاد اشتراک در اسناد Google Workspace Events API را ببینید.	`Channel` برای لیستی از انواع رویدادهای پشتیبانی شده، به درک رویدادهای اعلان Google Drive API در اسناد Drive API مراجعه کنید.	`Action` برای فهرستی از فیلدهای پشتیبانی شده، به منبع `Action` در مستندات مرجع Drive Activity API مراجعه کنید.
قالب رویداد	یک پیام Pub/Sub که بر اساس مشخصات CloudEvent قالب‌بندی شده است. برای جزئیات، به ساختار رویدادهای Google Workspace مراجعه کنید.	یک منبع Drive API ( `Channel` )	منبع API Activity Drive ( `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 روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.

کنسول Google Cloud

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

gcloud

در فهرست کاری خود، وارد حساب Google خود شوید:
```
gcloud auth login
```
پروژه خود را روی پروژه Cloud برای برنامه خود تنظیم کنید:
```
gcloud config set project PROJECT_ID
```
شناسه پروژه پروژه Cloud را برای برنامه خود جایگزین PROJECT_ID کنید.

فعال کردن 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 ایجاد کنید

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

برنامه 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'];

/**
 * Loads saved credentials from token.json, or authenticates the user.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  try {
    const content = await fs.readFile('token.json');
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    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;
  }
}

/**
 * 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: 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/v3/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 : اشتراک شامل همه فایل‌های Decendent 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 را با استفاده از توابع ابری پردازش کنید

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