Làm việc với các sự kiện trên Google Drive

Trang này giải thích cách nhận sự kiện trên Google Drive từ Google Cloud Pub/Sub.

Sự kiện trên Drive đại diện cho một hoạt động hoặc thay đổi đối với tài nguyên trên Drive, chẳng hạn như một tệp mới trong thư mục. Bạn có thể sử dụng các sự kiện để hiểu những gì đã xảy ra, sau đó hành động hoặc phản hồi theo cách có ý nghĩa cho người dùng.

Sau đây là một số ví dụ về cách bạn có thể sử dụng sự kiện:

• Quan sát và phản hồi các thay đổi trong tệp, thư mục hoặc bộ nhớ dùng chung, chẳng hạn như khi một tệp được chỉnh sửa hoặc một bản sửa đổi mới được tải lên.

• Theo dõi các thay đổi đối với tệp để cải thiện hiệu suất của ứng dụng.

• Kiểm tra các hoạt động như chia sẻ, di chuyển và xoá tệp để phát hiện các trường hợp rò rỉ dữ liệu và truy cập trái phép có thể xảy ra.

• Cung cấp thông tin chi tiết về cách người dùng quản lý tệp, giúp xác định những khía cạnh có thể cải thiện trong việc quản lý nội dung.

• Theo dõi các thay đổi đối với tệp để xác minh việc tuân thủ các yêu cầu theo quy định hoặc chính sách bảo mật.

• Phân tích hoạt động trên Drive bằng các sản phẩm khác của Google Cloud như Eventarc, Workflows và BigQuery.

Cách hoạt động của sự kiện

Bất cứ khi nào có sự kiện xảy ra trong Drive, một tài nguyên API Google Drive sẽ được tạo, cập nhật hoặc xoá. Drive sử dụng các sự kiện để cung cấp thông tin cho ứng dụng của bạn về loại hoạt động đã xảy ra và tài nguyên API Drive bị ảnh hưởng.

Drive phân loại sự kiện theo loại. Loại sự kiện giúp bạn lọc và chỉ nhận loại thông tin bạn cần, đồng thời cho phép bạn xử lý các hoạt động tương tự theo cùng một cách.

Bảng sau đây cho thấy cách một hoạt động mẫu trong Drive ảnh hưởng đến tài nguyên API Drive có liên quan và loại sự kiện mà ứng dụng Drive của bạn nhận được:

Nhận sự kiện từ Google Drive

Thông thường, ứng dụng Drive của bạn có thể tìm thấy các sự kiện thông qua API Drive hoặc API Hoạt động trên Google Drive. Với việc bổ sung sự kiện trên Drive trong API Google Workspace Events, giờ đây có một phương thức thứ ba để nhận sự kiện:

• Đăng ký nhận sự kiện bằng API Google Workspace Events để nhận sự kiện khi sự kiện xảy ra. Để biết thêm thông tin, hãy xem bài viết Đăng ký nhận thông báo về sự kiện trên Google Drive.

• Đăng ký nhận sự kiện bằng API Drive. Nhận sự kiện thay đổi của người dùng bằng phương thức changes.watch hoặc sự kiện thay đổi tệp bằng phương thức files.watch.

• Truy vấn các sự kiện gần đây bằng cách gọi Google Drive Activity API.

Bảng sau đây giải thích sự khác biệt và lý do nên đăng ký nhận sự kiện thay vì truy vấn sự kiện:

Bắt đầu sử dụng sự kiện trên Drive

Hướng dẫn này giải thích cách tạo và quản lý gói thuê bao sự kiện của Google Workspace trên tài nguyên Drive. Việc này cho phép ứng dụng của bạn nhận sự kiện qua Google Cloud Pub/Sub.

Tạo một dự án trên Google Cloud

Để tạo một dự án trên Google Cloud, hãy xem bài viết Tạo dự án trên Google Cloud.

Bật API Sự kiện Google Workspace, API Google Cloud Pub/Sub và API Google Drive

Thiết lập mã ứng dụng khách

Để tạo mã ứng dụng khách OAuth 2.0, hãy xem phần Tạo thông tin xác thực mã ứng dụng khách OAuth.

Tạo chủ đề Pub/Sub

Trước khi tạo gói thuê bao, bạn phải tạo một chủ đề Google Cloud Pub/Sub để nhận các sự kiện liên quan mà ứng dụng của bạn quan tâm. Để tạo chủ đề Pub/Sub, hãy xem phần Tạo và đăng ký chủ đề Pub/Sub.

Hãy nhớ tham chiếu đến tài khoản dịch vụ Drive (drive-api-event-push@system.gserviceaccount.com) cho các yêu cầu của bạn.

Tạo gói thuê bao Drive

Sự kiện trên đám mây được gửi đi khi đối tượng của gói thuê bao (hoặc bất kỳ tệp nào khác trong hệ phân cấp của đối tượng) thay đổi. Ví dụ: nếu bạn tạo một gói thuê bao trên một bộ nhớ dùng chung và một tệp thay đổi được lồng trong một số thư mục con trong bộ nhớ dùng chung đó, thì gói thuê bao đó sẽ tạo ra một sự kiện. Để biết các tài nguyên và loại sự kiện được hỗ trợ trên Drive, hãy xem phần Các loại sự kiện để tạo gói thuê bao.

Ứng dụng Node.js sau đây tạo một gói thuê bao sự kiện trên Drive cho một tệp hoặc thư mục để theo dõi các sự kiện thay đổi nội dung. Để biết thêm thông tin, hãy xem bài viết Tạo gói thuê bao Google Workspace.

Để chạy ví dụ này, hãy đảm bảo bạn đã cài đặt cả Node.js và npm. Bạn cũng cần đảm bảo rằng bạn đã cài đặt các phần phụ thuộc cần thiết để chạy ví dụ này.

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

Để tạo gói thuê bao Drive, bạn sử dụng phương thức subscriptions.create của API Sự kiện Google Workspace để tạo tài nguyên 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: {
        {
          '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);

Thay thế nội dung sau:

• SCOPES: Một hoặc nhiều phạm vi OAuth hỗ trợ từng loại sự kiện cho gói thuê bao. Được định dạng dưới dạng một mảng chuỗi. Để liệt kê nhiều phạm vi, hãy phân tách bằng dấu phẩy. Tốt nhất là bạn nên sử dụng phạm vi hạn chế nhất mà vẫn cho phép ứng dụng của bạn hoạt động. Ví dụ: 'https://www.googleapis.com/auth/drive.file'

• TARGET_RESOURCE: Tài nguyên Google Workspace mà bạn đang đăng ký, được định dạng dưới dạng tên tài nguyên đầy đủ. Ví dụ: để đăng ký một tệp hoặc thư mục trên Drive, hãy sử dụng //drive.googleapis.com/files/FileID.

• EVENT_TYPES: Một hoặc nhiều loại sự kiện mà bạn muốn đăng ký trong tài nguyên mục tiêu. Định dạng dưới dạng một mảng chuỗi, chẳng hạn như 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: Một giá trị boolean cho biết liệu gói thuê bao có bao gồm dữ liệu tài nguyên trong tải trọng sự kiện hay không. Thuộc tính này ảnh hưởng đến thời hạn của gói thuê bao. Để tìm hiểu thêm, hãy xem bài viết Dữ liệu sự kiện.

  • True: Bao gồm tất cả dữ liệu tài nguyên. Để giới hạn các trường được đưa vào, hãy thêm fieldMask và chỉ định ít nhất một trường cho tài nguyên đã thay đổi. Chỉ những gói thuê bao hỗ trợ tài nguyên Chat và Drive mới bao gồm dữ liệu tài nguyên.

  • False: Loại trừ dữ liệu tài nguyên.

• INCLUDE_DESCENDANTS: Một trường boolean thuộc DriveOptions. Chỉ có thể sử dụng khi targetResource là tệp trên Drive hoặc bộ nhớ dùng chung có loại MIME được đặt thành application/vnd.google-apps.folder. Không thể đặt trên thư mục gốc của Drive của tôi hoặc bộ nhớ dùng chung.

  • True: Gói thuê bao bao gồm tất cả các tệp con trên Drive trong danh sách sự kiện.

  • False: Gói thuê bao được tạo cho một tệp hoặc bộ nhớ dùng chung được chỉ định là targetResource.

• TOPIC_NAME: Tên đầy đủ của chủ đề Pub/Sub mà bạn đã tạo trong dự án trên đám mây của bạn. Chủ đề Pub/Sub này nhận các sự kiện cho gói thuê bao. Định dạng là projects/PROJECT_ID/topics/TOPIC_ID. Trường notificationEndpoint được dùng để chỉ định chủ đề Pub/Sub và đây là nơi gói thuê bao phân phối sự kiện.

Kiểm tra gói thuê bao Drive

Để kiểm tra xem bạn có đang nhận được sự kiện trên Drive hay không, bạn có thể kích hoạt một sự kiện và kéo thông báo đến gói thuê bao Pub/Sub. Để biết thêm thông tin, hãy xem bài viết Kiểm tra gói thuê bao Google Workspace.

Xử lý sự kiện trên Drive bằng Cloud Functions

Các sự kiện trên Drive được gửi đến chủ đề Pub/Sub trong gói thuê bao mà bạn tạo. Khi tạo điều kiện kích hoạt, hãy đảm bảo chủ đề Pub/Sub cho điều kiện kích hoạt khớp với chủ đề Pub/Sub trong gói thuê bao sự kiện của bạn. Sau đó, bạn có thể triển khai hàm Cloud Run và chỉnh sửa tệp để xem các thay đổi về sự kiện trong nhật ký.

Trước khi tạo hàm, hãy cập nhật package.json cho các phần phụ thuộc:

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

Tiếp theo, hãy tạo mã nguồn cho hàm:

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

• Khi trường boolean includeDescendants trong DriveOptions là true, các gói thuê bao Drive trên bộ nhớ dùng chung và thư mục luôn gửi một sự kiện, ngay cả khi tệp kích hoạt sự kiện đó được lồng nhiều lớp bên dưới thư mục dùng cho gói thuê bao Drive.
• Mặc dù có thể đã tạo gói thuê bao cho một thư mục, nhưng bạn có thể không nhận được tất cả sự kiện trong hệ phân cấp tệp vì người dùng hoặc ứng dụng có thể không được cấp quyền truy cập vào các sự kiện đó. Trong trường hợp này, gói thuê bao vẫn hoạt động nhưng bạn sẽ không nhận được bất kỳ sự kiện nào cho những tài nguyên mà bạn không có quyền truy cập.
• Gói thuê bao được hỗ trợ cho các sự kiện trên tất cả tệp và thư mục, nhưng không được hỗ trợ trên thư mục gốc của bộ nhớ dùng chung. Tính năng đăng ký chỉ được hỗ trợ cho các tệp và thư mục bên trong bộ nhớ dùng chung. Những thay đổi được thực hiện trực tiếp đối với thư mục gốc của bộ nhớ dùng chung sẽ không kích hoạt sự kiện.
• Người dùng uỷ quyền cho gói thuê bao phải có quyền đối với tệp tương ứng với các sự kiện mà họ đăng ký.
• Gói thuê bao chỉ nhận được sự kiện cho những tài nguyên mà người dùng có quyền truy cập thông qua tài khoản Google Workspace hoặc Tài khoản Google của họ.

Để biết thông tin về hạn mức gói thuê bao và giới hạn tốc độ, hãy xem bài viết Giới hạn sử dụng của Google Workspace Events API.

Chủ đề có liên quan

• Tổng quan về Google Workspace Events API
• Tạo gói thuê bao Google Workspace
• Đăng ký nhận thông báo về các sự kiện trên Google Drive
• Hạn mức sử dụng Google Workspace Events API