Bekerja dengan acara dari Google Drive

Pratinjau Developer: Tersedia sebagai bagian dari Program Pratinjau Developer Google Workspace, yang memberikan akses awal ke fitur tertentu.

Halaman ini menjelaskan cara menerima peristiwa Google Drive dari Google Cloud Pub/Sub.

Peristiwa Drive mewakili aktivitas atau perubahan pada resource Drive, seperti file baru dalam folder. Anda dapat menggunakan peristiwa untuk memahami apa yang terjadi, lalu mengambil tindakan, atau merespons dengan cara yang bermakna bagi pengguna Anda.

Berikut beberapa contoh cara menggunakan peristiwa:

• Mengamati dan merespons perubahan pada file, folder, atau drive bersama, seperti saat file diedit atau revisi baru diupload.

• Pantau perubahan pada file untuk meningkatkan performa aplikasi Anda.

• Audit aktivitas seperti berbagi file, pemindahan file, dan penghapusan untuk membantu mendeteksi potensi kebocoran data dan akses yang tidak sah.

• Menawarkan insight tentang cara pengguna mengelola file mereka, membantu mengidentifikasi area yang pengelolaan kontennya dapat ditingkatkan.

• Melacak perubahan file untuk memverifikasi kepatuhan terhadap persyaratan peraturan atau kebijakan keamanan.

• Menganalisis aktivitas Drive menggunakan produk Google Cloud lainnya seperti Eventarc, Workflows, dan BigQuery.

Cara kerja acara

Setiap kali terjadi sesuatu di Drive, resource Google Drive API akan dibuat, diperbarui, atau dihapus. Drive menggunakan peristiwa untuk mengirimkan informasi ke aplikasi Anda tentang jenis aktivitas yang terjadi, dan resource Drive API yang terpengaruh.

Drive mengategorikan peristiwa menurut jenisnya. Jenis peristiwa membantu Anda memfilter dan menerima hanya jenis informasi yang Anda butuhkan, serta memungkinkan Anda menangani aktivitas serupa dengan cara yang sama.

Tabel berikut menunjukkan pengaruh aktivitas di Drive terhadap resource Drive API terkait, dan jenis peristiwa yang diterima aplikasi Drive Anda:

Aktivitas	Resource Drive API	Jenis peristiwa
Pengguna menambahkan file ke folder atau drive bersama.	Resource File dibuat.	File baru
Pengguna membuat proposal akses pada file.	Resource AccessProposal dibuat.	Proposal akses baru

Menerima peristiwa dari Google Drive

Biasanya, aplikasi Drive Anda dapat menemukan peristiwa melalui Drive API atau Google Drive Activity API. Dengan penambahan peristiwa Drive di Google Workspace Events API, kini ada metode ketiga untuk menerima peristiwa:

• Pratinjau Developer: Berlangganan acara menggunakan Google Workspace Events API untuk menerima acara saat terjadi. Untuk mengetahui informasi selengkapnya, lihat Berlangganan ke peristiwa Google Drive.

• Berlangganan acara menggunakan Drive API. Dapatkan peristiwa perubahan pengguna dengan metode changes.watch atau peristiwa perubahan file menggunakan metode files.watch.

• Buat kueri untuk peristiwa terbaru dengan memanggil Google Drive Activity API.

Tabel berikut menjelaskan perbedaan dan alasan untuk berlangganan peristiwa versus membuat kueri untuk peristiwa tersebut:

	Berlangganan acara Google Workspace	Berlangganan peristiwa pengamatan Drive API	Membuat kueri untuk peristiwa Drive Activity API
Kasus penggunaan	Memproses atau merespons peristiwa secara real time. Pantau perubahan pada resource untuk meningkatkan performa aplikasi Anda. Menerima data peristiwa terstruktur melalui Pub/Sub dan menggunakan produk Google Cloud seperti Cloud Run.	Mendeteksi perubahan pada metadata file dan memantau perubahan pada item tertentu secara efisien dengan notifikasi real-time. Mendukung URL callback webhook untuk menghindari polling endpoint API berulang kali.	Mengambil histori mendetail semua aktivitas, termasuk informasi terperinci tentang setiap peristiwa. Mengambil aktivitas presisi yang mencakup informasi ActionDetail, Actor, dan Target untuk tugas tertentu seperti audit.
API	Google Workspace Events API	Drive API	Drive Activity API
Sumber peristiwa	File, folder, dan drive bersama	changes.watch dan files.watch	DriveActivity
Acara yang didukung	File AccessProposal Untuk mengetahui daftar jenis peristiwa yang didukung, lihat Jenis peristiwa untuk membuat langganan dalam dokumentasi Google Workspace Events API.	Channel Untuk mengetahui daftar jenis peristiwa yang didukung, lihat Memahami peristiwa notifikasi Google Drive API dalam dokumentasi Drive API.	Action Untuk mengetahui daftar kolom yang didukung, lihat resource Action di dokumentasi referensi Drive Activity API.
Format peristiwa	Pesan Pub/Sub, diformat sesuai dengan spesifikasi CloudEvent. Untuk mengetahui detailnya, lihat Struktur peristiwa Google Workspace.	Resource Drive API (Channel)	Resource Drive Activity API (Action)
Data peristiwa	String berenkode Base64 dengan atau tanpa data resource. Untuk contoh payload, lihat Data peristiwa.	Payload JSON yang berisi data resource. Untuk contoh payload, lihat Channel resource dalam dokumentasi referensi.	Payload JSON yang berisi data resource. Untuk contoh payload, lihat isi respons activity.query dalam dokumentasi referensi.

Mulai menggunakan peristiwa Drive

Panduan ini menjelaskan cara membuat dan mengelola langganan peristiwa Google Workspace di resource Drive. Dengan demikian, aplikasi Anda dapat menerima peristiwa melalui Google Cloud Pub/Sub.

Membuat project Google Cloud

Untuk membuat project Google Cloud, lihat Membuat project Google Cloud.

Aktifkan Google Workspace Events API, Google Cloud Pub/Sub API, dan Google Drive API

Sebelum menggunakan Google API, Anda harus mengaktifkannya di project Google Cloud. Anda dapat mengaktifkan satu atau beberapa API dalam satu project Google Cloud.

Konsol Google Cloud

1. Di konsol Google Cloud, buka project Google Cloud untuk aplikasi Anda dan aktifkan Google Workspace Events API, Pub/Sub API, dan Drive API:

   Aktifkan API

2. Pastikan Anda mengaktifkan API di project Cloud yang benar, lalu klik Berikutnya.

3. Pastikan Anda mengaktifkan API yang benar, lalu klik Aktifkan.

gcloud

1. Di direktori kerja Anda, login ke Akun Google Anda:

   gcloud auth login

2. Tetapkan project Anda ke project Cloud untuk aplikasi Anda:

   gcloud config set project PROJECT_ID

   Ganti PROJECT_ID dengan project ID untuk project Cloud aplikasi Anda.

3. Aktifkan Google Workspace Events API, Pub/Sub API, dan Drive API:

   gcloud services enable workspaceevents.googleapis.com \
   pubsub.googleapis.com \
   drive.googleapis.com

Menyiapkan client ID

Untuk membuat client ID OAuth 2.0, lihat Membuat kredensial client ID OAuth.

Membuat topik Pub/Sub

Sebelum membuat langganan, Anda harus membuat topik Google Cloud Pub/Sub yang menerima peristiwa relevan yang diminati aplikasi Anda. Untuk membuat topik Pub/Sub, lihat Membuat dan berlangganan topik Pub/Sub.

Pastikan untuk mereferensikan akun layanan Drive ([e-mail]) untuk permintaan Anda.

Membuat langganan Drive

Beta: Peristiwa Drive tersedia dalam Pratinjau Developer. Anda harus menggunakan API versi v1beta. Upaya untuk menggunakan API versi v1 standar akan gagal.

Peristiwa cloud dikirim saat subjek langganan (atau file lain di bawah hierarki subjek) berubah. Misalnya, jika Anda membuat langganan di drive bersama dan file yang berada di dalam beberapa subfolder di drive bersama tersebut berubah, peristiwa akan dibuat. Untuk jenis peristiwa Drive dan resource yang didukung, lihat Jenis peristiwa untuk membuat langganan.

Aplikasi Node.js berikut membuat langganan peristiwa Drive pada file atau folder untuk memproses peristiwa perubahan konten. Untuk mengetahui informasi selengkapnya, lihat Membuat langganan Google Workspace.

Untuk menjalankan contoh ini, pastikan Anda telah menginstal Node.js & npm. Anda juga harus memastikan telah menginstal dependensi yang diperlukan untuk menjalankan contoh ini.

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

Untuk membuat langganan Drive, Anda menggunakan metode subscriptions.create() Google Workspace Events API untuk membuat resource 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/v1beta/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);

Ganti kode berikut:

• SCOPES: Satu atau beberapa cakupan OAuth yang mendukung setiap jenis peristiwa untuk langganan. Diformat sebagai array string. Untuk mencantumkan beberapa cakupan, pisahkan dengan koma. Sebagai praktik terbaik, Anda harus menggunakan cakupan paling ketat yang masih memungkinkan aplikasi Anda berfungsi. Contohnya, 'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: Resource Google Workspace yang Anda ikuti, diformat sebagai nama resource lengkapnya. Misalnya, untuk berlangganan file atau folder Drive, gunakan //drive.googleapis.com/files/FileID.

• EVENT_TYPES: Satu atau beberapa jenis peristiwa yang ingin Anda ikuti di resource target. Format sebagai array string, seperti 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: Boolean yang menentukan apakah langganan menyertakan data resource dalam payload peristiwa. Properti ini memengaruhi durasi waktu langganan Anda. Untuk mempelajari lebih lanjut, lihat Data peristiwa.

  • True: Mencakup semua data resource. Untuk membatasi kolom yang disertakan, tambahkan fieldMask dan tentukan setidaknya satu kolom untuk resource yang diubah. Hanya langganan ke resource Chat dan Drive yang mendukung penyertaan data resource.

  • False: Mengecualikan data resource.

• INCLUDE_DESCENDANTS: Kolom boolean yang merupakan bagian dari DriveOptions. Hanya tersedia jika targetResource adalah file Drive atau drive bersama yang jenis MIME-nya ditetapkan ke application/vnd.google-apps.folder. Tidak dapat ditetapkan di folder root Drive Saya atau drive bersama.

  • True: Langganan mencakup semua file Drive turunan dalam daftar peristiwa.

  • False: Langganan dibuat untuk satu file atau drive bersama yang ditentukan sebagai targetResource.

• TOPIC_NAME: Nama lengkap topik Pub/Sub yang Anda buat di project Cloud Anda. Topik Pub/Sub ini menerima peristiwa untuk langganan. Diformat sebagai projects/PROJECT_ID/topics/TOPIC_ID. Kolom notificationEndpoint digunakan untuk menentukan topik Pub/Sub dan tempat langganan mengirimkan peristiwa.

Menguji langganan Drive Anda

Untuk menguji bahwa Anda menerima peristiwa Drive, Anda dapat memicu peristiwa dan menarik pesan ke langganan Pub/Sub. Untuk mengetahui informasi selengkapnya, lihat Menguji langganan Google Workspace Anda.

Memproses peristiwa Drive menggunakan Cloud Functions

Peristiwa Drive dikirim ke topik Pub/Sub dalam langganan yang Anda buat. Saat membuat pemicu, pastikan topik Pub/Sub untuk pemicu cocok dengan topik Pub/Sub dalam langganan peristiwa Anda. Kemudian, Anda dapat men-deploy fungsi Cloud Rundan mengedit file untuk melihat perubahan peristiwa dalam log.

Sebelum membuat fungsi, perbarui package.json untuk dependensi:

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

Selanjutnya, buat kode sumber untuk fungsi:

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

Batasan

• Jika kolom boolean includeDescendants di DriveOptions adalah true, langganan Drive di folder dan drive bersama akan selalu mengirimkan peristiwa, meskipun file yang memicu peristiwa berada di banyak lapisan di bawah folder yang digunakan untuk langganan Drive.
• Meskipun Anda telah membuat langganan di folder, Anda mungkin tidak menerima semua peristiwa dalam hierarki file karena pengguna atau aplikasi mungkin tidak diberi akses ke peristiwa tersebut. Dalam kasus ini, langganan tetap aktif, tetapi Anda tidak akan menerima peristiwa apa pun untuk resource yang tidak dapat Anda akses.
• Langganan didukung untuk peristiwa pada semua file dan folder, tetapi tidak pada folder root drive bersama. Langganan hanya didukung untuk file dan folder di dalam drive bersama. Perubahan yang dilakukan langsung pada folder root drive bersama tidak akan memicu peristiwa.
• Pengguna yang mengizinkan langganan harus memiliki izin pada file yang sesuai dengan peristiwa yang mereka langgani.
• Langganan hanya menerima peristiwa untuk resource yang dapat diakses pengguna melalui akun Google Workspace atau Akun Google mereka.

Topik terkait

• Ringkasan Google Workspace Events API
• Membuat langganan Google Workspace
• Berlangganan peristiwa Google Drive