Google Drive'daki etkinliklerle çalışma

Bu sayfada, Google Cloud Pub/Sub'dan Google Drive etkinliklerinin nasıl alınacağı açıklanmaktadır.

Drive etkinliği, bir klasördeki yeni dosya gibi bir Drive kaynağındaki etkinliği veya değişikliği ifade eder. Ne olduğunu anlamak ve ardından harekete geçmek ya da kullanıcılarınıza anlamlı bir şekilde yanıt vermek için etkinlikleri kullanabilirsiniz.

Etkinlikleri nasıl kullanabileceğinize dair bazı örnekleri burada görebilirsiniz:

• Dosya, klasör veya ortak Drive'daki değişiklikleri (ör. dosya düzenlendiğinde veya yeni bir düzeltme yüklendiğinde) gözlemleyip yanıtlayabilirsiniz.

• Uygulamanızın performansını artırmak için dosyalarda yapılan değişiklikleri izleyin.

• Olası veri sızıntılarını ve yetkisiz erişimi tespit etmek için dosya paylaşımı, dosya taşıma ve silme gibi etkinlikleri denetleyin.

• Kullanıcıların dosyalarını nasıl yönettiği hakkında bilgi vererek içerik yönetiminin iyileştirilebileceği alanların belirlenmesine yardımcı olur.

• Yasal şartlara veya güvenlik politikalarına uygunluğu doğrulamak için dosya değişikliklerini izleyin.

• Eventarc, Workflows ve BigQuery gibi diğer Google Cloud ürünlerini kullanarak Drive etkinliğini analiz edin.

Etkinliklerin işleyiş şekli

Drive'da bir işlem yapıldığında Google Drive API kaynağı oluşturulur, güncellenir veya silinir. Drive, etkinlikleri kullanarak uygulamanıza gerçekleşen etkinlik türü ve etkilenen Drive API kaynağı hakkında bilgi verir.

Drive, etkinlikleri türe göre sınıflandırır. Etkinlik türleri, yalnızca ihtiyacınız olan bilgileri filtrelemenize ve almanıza yardımcı olur. Ayrıca benzer etkinlikleri aynı şekilde yönetmenizi sağlar.

Aşağıdaki tabloda, Drive'daki bir etkinliğin ilgili Drive API kaynağını nasıl etkilediği ve Drive uygulamanızın aldığı etkinlik türü gösterilmektedir:

Google Drive'dan etkinlik alma

Geleneksel olarak, Drive uygulamanız etkinlikleri Drive API veya Google Drive Activity API aracılığıyla bulabiliyordu. Google Workspace Events API'ye Drive etkinliklerinin eklenmesiyle birlikte artık etkinlikleri almak için üçüncü bir yöntem var:

• Geliştirici Önizlemesi: Etkinlikleri gerçekleşir gerçekleşmez almak için Google Workspace Events API'yi kullanarak etkinliklere abone olun.

• Drive API'yi kullanarak etkinliklere abone olma changes.watch yöntemiyle kullanıcı değişikliği etkinliklerini veya files.watch yöntemiyle dosya değişikliği etkinliklerini alın.

• Google Drive Activity API'yi çağırarak son etkinlikleri sorgulayın.

Aşağıdaki tabloda, etkinliklere abone olma ile etkinlikleri sorgulama arasındaki fark ve abone olmanın nedenleri açıklanmaktadır:

Drive etkinliklerini kullanmaya başlama

Bu kılavuzda, Drive kaynağında Google Workspace etkinlikleri aboneliğinin nasıl oluşturulacağı ve yönetileceği açıklanmaktadır. Bu, uygulamanızın Google Cloud Pub/Sub üzerinden etkinlik almasına olanak tanır.

Google Cloud projesi oluşturma

Google Cloud projesi oluşturmak için Google Cloud projesi oluşturma başlıklı makaleyi inceleyin.

Google Workspace Events API, Google Cloud Pub/Sub API ve Google Drive API'yi etkinleştirin.

İstemci kimliği ayarlama

OAuth 2.0 istemci kimliği oluşturmak için OAuth istemci kimliği kimlik bilgileri oluşturma başlıklı makaleye bakın.

Pub/Sub konusu oluşturma

Abonelik oluşturmadan önce, uygulamanızın ilgilendiği ilgili etkinlikleri alan bir Google Cloud Pub/Sub konusu oluşturmanız gerekir. Pub/Sub konusu oluşturmak için Pub/Sub konusu oluşturma ve konuya abone olma başlıklı makaleyi inceleyin.

İsteklerinizde Drive hizmet hesabına (drive-api-event-push@system.gserviceaccount.com) referans verdiğinizden emin olun.

Drive aboneliği oluşturma

Cloud etkinlikleri, abonelik konusu (veya konu hiyerarşisi altındaki diğer dosyalar) değiştiğinde gönderilir. Örneğin, bir ortak drive'da abonelik oluşturursanız ve bu ortak drive'daki birkaç alt klasörün içinde yer alan bir dosyada değişiklik yapılırsa bir etkinlik oluşturulur. Desteklenen kaynaklar ve Drive etkinlik türleri için Abonelik oluşturmaya yönelik etkinlik türleri başlıklı makaleyi inceleyin.

Aşağıdaki Node.js uygulaması, içerik değişikliği etkinliklerini dinlemek için bir dosya veya klasörde Drive etkinlikleri aboneliği oluşturur. Daha fazla bilgi için Google Workspace aboneliği oluşturma başlıklı makaleyi inceleyin.

Bu örneği çalıştırmak için Node.js ve npm'nin yüklü olduğundan emin olun. Ayrıca, bu örneği çalıştırmak için gerekli bağımlılıkların yüklendiğinden de emin olmanız gerekir.

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

Drive aboneliği oluşturmak için Google Workspace Events API'nin subscriptions.create() yöntemini kullanarak Subscription kaynağı oluşturursunuz:

// 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);

Aşağıdakini değiştirin:

• SCOPES: Abonelik için her etkinlik türünü destekleyen bir veya daha fazla OAuth kapsamı. Dize dizisi olarak biçimlendirilir. Birden fazla kapsamı listelemek için virgülle ayırın. En iyi uygulama olarak, uygulamanızın çalışmasına izin veren en kısıtlayıcı kapsamı kullanmanız gerekir. Örneğin, 'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: Abone olduğunuz Google Workspace kaynağı, tam kaynak adı olarak biçimlendirilmiş. Örneğin, bir Drive dosyasına veya klasörüne abone olmak için //drive.googleapis.com/v3/files/FileID simgesini kullanın.

• EVENT_TYPES: Hedef kaynakta abone olmak istediğiniz bir veya daha fazla etkinlik türü. 'google.workspace.drive.file.v3.contentChanged' gibi bir dizeler dizisi olarak biçimlendirin.

• RESOURCE_DATA: Aboneliğin, etkinlik yükündeki kaynak verilerini içerip içermediğini belirten bir Boole değeri. Bu özellik, aboneliğinizin süresini etkiler. Daha fazla bilgi için Etkinlik verileri başlıklı makaleyi inceleyin.

  • True: Tüm kaynak verilerini içerir. Hangi alanların dahil edileceğini sınırlamak için fieldMask ekleyin ve değiştirilen kaynak için en az bir alan belirtin. Yalnızca Chat ve Drive kaynak desteği abonelikleri kaynak verileri içerir.

  • False: Kaynak verilerini hariç tutar.

• INCLUDE_DESCENDANTS: DriveOptions'ın parçası olan bir Boole alanı. Yalnızca targetResource, Drive dosyası veya MIME türü application/vnd.google-apps.folder olarak ayarlanmış bir ortak Drive olduğunda kullanılabilir. Drive'ım veya ortak Drive'ların kök klasöründe ayarlanamaz.

  • True: Abonelik, etkinlik listesindeki tüm alt Drive dosyalarını içerir.

  • False: Abonelik, targetResource olarak belirtilen tek dosya veya ortak drive için oluşturulur.

• TOPIC_NAME: Cloud projenizde oluşturduğunuz Pub/Sub konusunun tam adı. Bu Pub/Sub konusu, abonelikle ilgili etkinlikleri alır. projects/PROJECT_ID/topics/TOPIC_ID olarak biçimlendirildi. notificationEndpoint alanı, Pub/Sub konusunu belirtmek için kullanılır ve aboneliğin etkinlikleri teslim ettiği yerdir.

Drive aboneliğinizi test etme

Drive etkinliklerini aldığınızı test etmek için bir etkinliği tetikleyebilir ve mesajları Pub/Sub aboneliğine çekebilirsiniz. Daha fazla bilgi için Google Workspace aboneliğinizi test etme başlıklı makaleyi inceleyin.

Cloud Functions kullanarak Drive etkinliklerini işleme

Drive etkinlikleri, oluşturduğunuz abonelikteki Pub/Sub konusuna gönderilir. Tetikleyiciyi oluştururken tetikleyici için Pub/Sub konusunun, etkinlik aboneliğinizdeki Pub/Sub konusuyla eşleştiğinden emin olun. Ardından, Cloud Run işlevinizi dağıtabilir ve günlüklerdeki etkinlik değişikliklerini görmek için dosyada düzenlemeler yapabilirsiniz.

İşlevi oluşturmadan önce bağımlılıklar için package.json dosyasını güncelleyin:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "cloudevents": "^8.0.0"
  }
}

Ardından, işlevin kaynak kodunu oluşturun:

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 boolean alanı DriveOptions true olduğunda, ortak Drive'lardaki ve klasörlerdeki Drive abonelikleri, etkinliği tetikleyen dosya Drive aboneliği için kullanılan klasörün çok altında iç içe yerleştirilmiş olsa bile her zaman bir etkinlik gönderir.
• Bir klasörde abonelik oluşturmuş olsanız bile, kullanıcıya veya uygulamaya erişim izni verilmemiş olabileceği için dosya hiyerarşisindeki tüm etkinlikleri almayabilirsiniz. Bu durumda abonelik etkin kalmaya devam eder ancak erişiminiz olmayan kaynaklarla ilgili etkinlik almazsınız.
• Abonelikler, tüm dosya ve klasörlerdeki etkinlikler için desteklenir ancak ortak Drive'ların kök klasöründe desteklenmez. Abonelikler yalnızca ortak drive'lar içindeki dosya ve klasörlerde desteklenir. Ortak Drive'ların kök klasöründe doğrudan yapılan değişiklikler etkinlikleri tetiklemez.
• Aboneliği yetkilendiren kullanıcının, abone olduğu etkinliklere karşılık gelen dosya üzerinde izni olmalıdır.
• Abonelik yalnızca kullanıcının Google Workspace hesabı veya Google Hesabı üzerinden erişebildiği kaynaklarla ilgili etkinlikleri alır.

İlgili konular

• Google Workspace Events API'ye genel bakış
• Google Workspace aboneliği oluşturma