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 Drive kaynağındaki etkinliği veya değişikliği (ör. klasördeki yeni bir dosya) temsil eder. Etkinlikleri kullanarak neler olduğunu anlayabilir ve ardından harekete geçebilir ya da kullanıcılarınız için anlamlı bir şekilde yanıt verebilirsiniz.

Etkinlikleri nasıl kullanabileceğinize dair bazı örnekler:

• Bir dosya, klasör veya ortak Drive'daki değişiklikleri (ör. bir dosyanın düzenlenmesi veya yeni bir düzeltmenin yüklenmesi) gözlemleyip yanıtlayın.

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

• Olası veri sızıntılarını ve yetkisiz erişimleri 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ğiyle ilgili analizler sunarak içerik yönetiminin iyileştirilebileceği alanları belirlemeye yardımcı olur.

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

• 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 bir Google Drive API kaynağı oluşturulur, güncellenir veya silinir. Drive, gerçekleşen etkinliğin türü ve etkilenen Drive API kaynağı hakkında uygulamanıza bilgi göndermek için etkinlikleri kullanır.

Drive, etkinlikleri türlerine göre kategorilere ayırır. Etkinlik türleri, yalnızca ihtiyacınız olan bilgi türünü filtreleyip almanıza yardımcı olur ve benzer etkinlikleri aynı şekilde işlemenize olanak tanır.

Aşağıdaki tabloda, Drive'daki örnek 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, etkinlikleri almak için üçüncü bir yöntem daha kullanılabilir:

• Etkinlikleri gerçekleştikleri anda almak için Google Workspace Events API'yi kullanarak etkinliklere abone olun. Daha fazla bilgi için Google Drive etkinliklerine abone olma başlıklı makaleyi inceleyin.

• 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 sorgulama.

Aşağıdaki tabloda, etkinliklere abone olmak ile etkinlikleri sorgulamak arasındaki fark ve nedenler 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 sayede uygulamanız Google Cloud Pub/Sub üzerinden etkinlik alabilir.

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ştirme

İstemci kimliği oluşturma

OAuth 2.0 istemci kimliği oluşturmak için OAuth istemci kimliği kimlik bilgileri oluşturma başlıklı makaleyi inceleyin.

Pub/Sub konusu oluşturma

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

İstekleriniz için Drive hizmet hesabına (drive-api-event-push@system.gserviceaccount.com) başvurduğunuzdan emin olun.

Drive aboneliği oluşturma

Abonelik konusu (veya konunun hiyerarşisindeki diğer dosyalar) değiştiğinde bulut etkinlikleri gönderilir. Örneğin, bir ortak Drive'da abonelik oluşturursanız ve bu ortak Drive'daki birkaç alt klasörde iç içe yerleştirilmiş bir dosya değişirse bir etkinlik oluşturulur. Desteklenen kaynaklar ve Drive etkinlik türleri için Abonelik oluşturmak için 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üklü olduğundan 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'];

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

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çimlendirilir. Örneğin, bir Drive dosyasına veya klasörüne abone olmak için //drive.googleapis.com/files/FileID 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 dize dizisi olarak biçimlendirin.

• RESOURCE_DATA: Aboneliğin, etkinlik yükünde kaynak verileri 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. Dahil edilen alanları sınırlamak için fieldMask parametresini ekleyin ve değiştirilen kaynak için en az bir alan belirtin. Yalnızca Chat ve Drive kaynaklarına yapılan abonelikler, kaynak verileri de dahil olmak üzere kaynak desteği sunar.

  • False: Kaynak verilerini hariç tutar.

• INCLUDE_DESCENDANTS: DriveOptions'nin parçası olan bir boole alanı. Yalnızca targetResource bir Drive dosyasıysa veya MIME türü application/vnd.google-apps.folder olarak ayarlanmış bir ortak Drive ise 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 yayınladığı yerdir.

Drive aboneliğinizi test etme

Drive etkinliklerini aldığınızı test etmek için bir etkinlik 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 tetikleyicinin 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);
  }
});

• DriveOptions içindeki includeDescendants boole alanı true olduğunda, ortak Drive'lar ve klasörlerdeki Drive abonelikleri, etkinliği tetikleyen dosya Drive aboneliği için kullanılan klasörün birçok katman altında yer alsa bile her zaman bir etkinlik gönderir.
• Bir klasörde abonelik oluşturmuş olsanız bile, kullanıcıya veya uygulamaya erişim izni verilmediği için dosya hiyerarşisindeki tüm etkinlikleri alamayabilirsiniz. Bu durumda abonelik etkin kalır ancak erişiminiz olmayan kaynaklar için 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ın içindeki dosya ve klasörler için desteklenir. Doğrudan ortak Drive'ın kök klasöründe 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.

Abonelik kotaları ve sıklık sınırları hakkında bilgi edinmek için Google Workspace Events API kullanım sınırları başlıklı makaleyi inceleyin.

İlgili konular

• Google Workspace Events API'ye genel bakış
• Google Workspace aboneliği oluşturma
• Google Drive etkinliklerine abone olma
• Google Workspace Events API kullanım sınırları