Google Drive में मौजूद इवेंट पर काम करना

इस पेज पर, Google Cloud Pub/Sub से Google Drive के इवेंट पाने का तरीका बताया गया है.

Drive इवेंट , Drive के किसी संसाधन में होने वाली गतिविधि या बदलाव को दिखाता है. जैसे, किसी फ़ोल्डर में नई फ़ाइल. इवेंट की मदद से, यह समझा जा सकता है कि क्या हुआ. इसके बाद, कार्रवाई की जा सकती है या अपने उपयोगकर्ताओं के लिए काम का जवाब दिया जा सकता है.

यहां कुछ उदाहरण दिए गए हैं कि इवेंट का इस्तेमाल कैसे किया जा सकता है:

किसी फ़ाइल, फ़ोल्डर या शेयर की गई ड्राइव में होने वाले बदलावों को देखना और उनका जवाब देना. जैसे, किसी फ़ाइल में बदलाव करना या नया वर्शन अपलोड करना.
अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाने के लिए, फ़ाइलों में होने वाले बदलावों पर नज़र रखना.
डेटा लीक होने और अनधिकृत ऐक्सेस का पता लगाने के लिए, फ़ाइल शेयर करने, फ़ाइलें मूव करने, और फ़ाइलें मिटाने जैसी गतिविधियों की ऑडिट करना.
उपयोगकर्ता अपनी फ़ाइलें कैसे मैनेज कर रहे हैं, इस बारे में अहम जानकारी देना. इससे यह पता लगाने में मदद मिलती है कि कॉन्टेंट मैनेजमेंट को किन मामलों में बेहतर बनाया जा सकता है.
कानूनी शर्तों या सुरक्षा नीतियों के मुताबिक काम किया जा रहा है या नहीं, यह देखने के लिए फ़ाइल में होने वाले बदलावों को ट्रैक करना.
Eventarc, Workflows, और BigQuery जैसे अन्य Google Cloud प्रॉडक्ट का इस्तेमाल करके, Drive में होने वाली गतिविधि का विश्लेषण करना.

इवेंट कैसे काम करते हैं

Drive में कुछ भी होने पर, Google Drive API का कोई संसाधन बनाया, अपडेट किया या मिटाया जाता है. Drive, इवेंट का इस्तेमाल करके आपके ऐप्लिकेशन को यह जानकारी देता है कि किस तरह की गतिविधि हुई है और Drive API के किस संसाधन पर इसका असर पड़ा है.

Drive, इवेंट को टाइप के हिसाब से कैटगरी में बांटता है. इवेंट टाइप की मदद से, सिर्फ़ ज़रूरी जानकारी को फ़िल्टर किया जा सकता है और पाया जा सकता है. साथ ही, एक जैसी गतिविधियों को एक ही तरीके से मैनेज किया जा सकता है.

यहां दी गई टेबल में बताया गया है कि Drive में किसी गतिविधि का असर, उससे जुड़े Drive API के संसाधन पर कैसे पड़ता है. साथ ही, यह भी बताया गया है कि आपके Drive ऐप्लिकेशन को किस तरह का इवेंट मिलता है:

गतिविधि	Drive API का संसाधन	इवेंट किस तरह का है
कोई उपयोगकर्ता, किसी फ़ाइल को ऐक्सेस करने का अनुरोध करता है.	एक `AccessProposal` संसाधन बनाया जाता है.	ऐक्सेस करने का नया अनुरोध
कोई उपयोगकर्ता, किसी फ़ाइल के लिए अनुमति का अनुरोध करता है.	एक `Approval` संसाधन बनाया जाता है.	अनुमति का नया अनुरोध
कोई उपयोगकर्ता, Google Docs, Sheets या Slides की किसी फ़ाइल में टिप्पणी पोस्ट करता है.	एक `Comment` संसाधन बनाया जाता है.	नई टिप्पणी
कोई उपयोगकर्ता, किसी फ़ाइल को किसी फ़ोल्डर या शेयर की गई ड्राइव में जोड़ता है.	A `File` संसाधन बनाया जाता है.	नई फ़ाइल
कोई उपयोगकर्ता, किसी फ़ाइल के लिए अनुमतियां बनाता है.	एक `Permission` संसाधन बनाया जाता है.	नई अनुमति
कोई उपयोगकर्ता, किसी टिप्पणी का जवाब देता है.	A `Reply` संसाधन बनाया जाता है.	नया जवाब

Google Drive से इवेंट पाना

आम तौर पर, आपका Drive ऐप्लिकेशन, Drive API या Google Drive पर गतिविधि के बारे में बताने वाले एपीआई की मदद से इवेंट ढूंढ सकता है. Google Workspace Events API में Drive के इवेंट जोड़ने के बाद, अब इवेंट पाने का तीसरा तरीका भी उपलब्ध है:

Google Workspace Events API का इस्तेमाल करके, इवेंट की सदस्यता लें, ताकि इवेंट होने पर उन्हें पाया जा सके. ज़्यादा जानकारी के लिए, Google Drive के इवेंट की सदस्यता लेना लेख पढ़ें.
Drive API का इस्तेमाल करके, इवेंट की सदस्यता लें. `changes.watch` तरीके से, उपयोगकर्ता के बदलाव वाले इवेंट पाएं या `files.watch` तरीके से, फ़ाइल में होने वाले बदलाव वाले इवेंट पाएं.changes.watchfiles.watch
Google Drive पर गतिविधि के बारे में बताने वाले एपीआई को कॉल करके, हाल ही में हुए इवेंट के बारे में क्वेरी करें.

यहां दी गई टेबल में, इवेंट की सदस्यता लेने और उनके बारे में क्वेरी करने के बीच का अंतर और वजहें बताई गई हैं:

	Google Workspace के इवेंट की सदस्यता लेना	Drive API के वॉच इवेंट की सदस्यता लेना	Drive पर गतिविधि के बारे में बताने वाले एपीआई के इवेंट के बारे में क्वेरी करना
इस्तेमाल के उदाहरण	रीयल टाइम में इवेंट को प्रोसेस करना या उनका जवाब देना. अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाने के लिए, संसाधनों में होने वाले बदलावों पर नज़र रखना. Pub/Sub के ज़रिए, स्ट्रक्चर्ड इवेंट डेटा पाना और Cloud Run जैसे Google Cloud प्रॉडक्ट का इस्तेमाल करना.	फ़ाइल के मेटाडेटा में होने वाले बदलावों का पता लगाना और रीयल-टाइम सूचनाओं की मदद से, खास आइटम में होने वाले बदलावों पर नज़र रखना. एपीआई एंडपॉइंट को बार-बार पोल करने से बचने के लिए, वेबहुक कॉलबैक यूआरएल की सुविधा उपलब्ध है.	सभी गतिविधियों का इतिहास देखना. इसमें हर इवेंट के बारे में ज़्यादा जानकारी शामिल होती है. ऑडिट जैसे खास टास्क के लिए, सटीक गतिविधियां पाना. इनमें `ActionDetail`, `Actor`, और `Target` की जानकारी शामिल होती है.
एपीआई	Google Workspace Events API	Google Drive API	Google Drive पर गतिविधि के बारे में बताने वाला एपीआई
इवेंट का सोर्स	फ़ाइलें, फ़ोल्डर, और शेयर की गई ड्राइव	`changes.watch` और `files.watch`	`DriveActivity`
इस्तेमाल किए जा सकने वाले इवेंट	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` इस्तेमाल किए जा सकने वाले इवेंट टाइप की सूची देखने के लिए, सदस्यताएं बनाने के लिए इवेंट टाइप लेख पढ़ें. यह लेख Google Workspace Events API के दस्तावेज़ में है.	`Channel` इस्तेमाल किए जा सकने वाले इवेंट टाइप की सूची देखने के लिए, Drive API के दस्तावेज़ में, Google Drive API की सूचना वाले इवेंट समझना लेख पढ़ें.	`Action` इस्तेमाल किए जा सकने वाले फ़ील्ड की सूची देखने के लिए, Drive पर गतिविधि के बारे में बताने वाले एपीआई के रेफ़रंस दस्तावेज़ में, `Action` संसाधन लेख पढ़ें.
इवेंट का फ़ॉर्मैट	CloudEvent की खास जानकारी के मुताबिक फ़ॉर्मैट किया गया Pub/Sub मैसेज. ज़्यादा जानकारी के लिए, Google Workspace के इवेंट का स्ट्रक्चर लेख पढ़ें.	Drive API का संसाधन (`Channel`)	Drive पर गतिविधि के बारे में बताने वाले एपीआई का संसाधन (`Action`)
इवेंट का डेटा	Base64 में कोड में बदली गई स्ट्रिंग. इसमें संसाधन का डेटा शामिल हो भी सकता है और नहीं भी. पेलोड के उदाहरण देखने के लिए, इवेंट का डेटा लेख पढ़ें.	JSON पेलोड, जिसमें संसाधन का डेटा शामिल होता है. पेलोड का उदाहरण देखने के लिए, रेफ़रंस दस्तावेज़ में, `Channel` संसाधन लेख पढ़ें.	JSON पेलोड, जिसमें संसाधन का डेटा शामिल होता है. पेलोड का उदाहरण देखने के लिए, रेफ़रंस दस्तावेज़ में, `activity.query` जवाब का मुख्य हिस्सा लेख पढ़ें.

Drive के इवेंट का इस्तेमाल शुरू करना

इस गाइड में, Drive के किसी संसाधन पर Google Workspace के इवेंट की सदस्यता बनाने और उसे मैनेज करने का तरीका बताया गया है. इससे आपका ऐप्लिकेशन, 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 कंसोल

Google Cloud कंसोल में, अपने ऐप्लिकेशन के लिए Google Cloud प्रोजेक्ट खोलें और Google Workspace Events API, Pub/Sub API, और Drive API को चालू करें:

एपीआई चालू करें
पुष्टि करें कि आपने सही Cloud प्रोजेक्ट में एपीआई चालू किए हैं. इसके बाद, अगला पर क्लिक करें.
पुष्टि करें कि आपने सही एपीआई चालू किए हैं. इसके बाद, चालू करें पर क्लिक करें.

gcloud

अपनी वर्किंग डायरेक्ट्री में, अपने Google खाते में साइन इन करें:
```
gcloud auth login
```
अपने प्रोजेक्ट को, अपने ऐप्लिकेशन के लिए Cloud प्रोजेक्ट पर सेट करें:
```
gcloud config set project PROJECT_ID
```
PROJECT_ID की जगह, अपने ऐप्लिकेशन के लिए Cloud प्रोजेक्ट का प्रोजेक्ट आईडी डालें.

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 की सदस्यता लेने के लिए, Google Workspace Events API के subscriptions.create तरीके का इस्तेमाल करके, 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: {
        {
          '<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: आपके Cloud प्रोजेक्ट में बनाए गए Pub/Sub विषय का पूरा नाम. इस Pub/Sub विषय पर, सदस्यता के लिए इवेंट मिलते हैं. इसे projects/PROJECT_ID/topics/TOPIC_ID के तौर पर फ़ॉर्मैट किया जाता है. The notificationEndpoint फ़ील्ड का इस्तेमाल, Pub/Sub विषय को तय करने के लिए किया जाता है. सदस्यता के इवेंट इसी पर डिलीवर किए जाते हैं.

Drive की सदस्यता की जांच करना

यह जांचने के लिए कि आपको Drive के इवेंट मिल रहे हैं या नहीं, कोई इवेंट ट्रिगर करें और Pub/Sub की सदस्यता के लिए मैसेज पुल करें. ज़्यादा जानकारी के लिए, Google Workspace की सदस्यता की जांच करना लेख पढ़ें.

Cloud Functions का इस्तेमाल करके, 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 खाते से होता है.