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 Google Drive từ Google Cloud Pub/Sub.

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

Dưới đâ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ẻ tệp, di chuyển tệp và xoá tệp để giúp phát hiện các trường hợp rò rỉ dữ liệu tiềm ẩn và truy cập trái phép.
Cung cấp thông tin chi tiết về cách người dùng đang quản lý tệp của họ, giúp xác định những lĩnh vực có thể cải thiện 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 , chẳng hạn như Eventarc, Workflows, và BigQuery.

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

Bất cứ khi nào có điều gì đó 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. Các 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 biết cách một hoạt động ví dụ trong Drive ảnh hưởng đến tài nguyên API Drive liên quan và loại sự kiện mà ứng dụng Drive của bạn nhận được:

Hoạt động	Tài nguyên API Drive	Loại sự kiện
Người dùng tạo đề xuất quyền truy cập trên một tệp.	Tài nguyên `AccessProposal` được tạo.	Đề xuất quyền truy cập mới
Người dùng tạo yêu cầu phê duyệt trên một tệp.	Tài nguyên `Approval` được tạo.	Yêu cầu phê duyệt mới
Người dùng đăng nhận xét trong tệp Google Tài liệu, Trang tính hoặc Trang trình bày.	Tài nguyên `Comment` được tạo.	Nhận xét mới
Người dùng thêm tệp vào thư mục hoặc bộ nhớ dùng chung.	Tài nguyên `File` được tạo.	Tệp mới
Người dùng tạo quyền trên một tệp.	Tài nguyên `Permission` được tạo.	Quyền mới
Người dùng trả lời nhận xét.	Tài nguyên `Reply` được tạo.	Câu trả lời mới

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

Theo truyền thống, ứng dụng Drive của bạn có thể xác định vị trí các sự kiện thông qua API Drive hoặc Google Drive Activity API. Với việc bổ sung các sự kiện Drive trong Google Workspace Events API, hiện có một phương thức thứ ba để nhận sự kiện:

Đăng ký nhận sự kiện bằng Google Workspace Events API để nhận sự kiện khi chúng xảy ra. Để biết thêm thông tin, hãy xem bài viết Đăng ký nhận sự kiệ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 của 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 đăng ký nhận sự kiện so với truy vấn sự kiện:

	Đăng ký nhận sự kiện Google Workspace	Đăng ký nhận sự kiện theo dõi API Drive	Truy vấn sự kiện Drive Activity API
Trường hợp sử dụng	Xử lý hoặc phản hồi các sự kiện theo thời gian thực. Theo dõi các thay đổi trong tài nguyên để cải thiện hiệu suất của ứng dụng. Nhận dữ liệu sự kiện có cấu trúc thông qua Pub/Sub và sử dụng các sản phẩm của Google Cloud như Cloud Run.	Phát hiện các thay đổi đối với siêu dữ liệu tệp và theo dõi hiệu quả các thay đổi đối với các mục cụ thể bằng thông báo theo thời gian thực. Hỗ trợ URL gọi lại webhook để tránh việc liên tục thăm dò các điểm cuối API.	Tìm nạp nhật ký chi tiết về tất cả hoạt động, bao gồm cả thông tin thật chi tiết về từng sự kiện. Truy xuất các hoạt động chính xác bao gồm thông tin `ActionDetail`, `Actor` và `Target` cho các tác vụ cụ thể như kiểm tra.
API	Google Workspace Events API	API Google Drive	API Hoạt động trong Google Drive
Nguồn sự kiện	Tệp, thư mục và bộ nhớ dùng chung	`changes.watch` và `files.watch`	`DriveActivity`
Sự kiện được hỗ trợ	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem Loại sự kiện để tạo gói thuê bao trong tài liệu Google Workspace Events API.	`Channel` Để biết danh sách các loại sự kiện được hỗ trợ, hãy xem phần Tìm hiểu các sự kiện thông báo của API Google Drive trong tài liệu API Drive.	`Action` Để biết danh sách các trường được hỗ trợ, hãy xem tài nguyên `Action` resource trong tài liệu tham khảo về Drive Activity API reference documentation.
Định dạng sự kiện	Thông báo Pub/Sub, được định dạng theo CloudEvent specification. Để biết thông tin chi tiết, hãy xem phần Cấu trúc của sự kiện Google Workspace.	Tài nguyên API Drive (`Channel`)	Tài nguyên Drive Activity API (`Action`)
Dữ liệu sự kiện	Chuỗi được mã hoá Base64 có hoặc không có dữ liệu tài nguyên. Để biết các tải trọng ví dụ, hãy xem phần Dữ liệu sự kiện.	Tải trọng JSON chứa dữ liệu tài nguyên. Để biết tải trọng ví dụ, hãy xem tài nguyên `Channel` trong tài liệu tham khảo.	Tải trọng JSON chứa dữ liệu tài nguyên. Để biết tải trọng ví dụ, hãy xem phần nội dung phản hồi `activity.query` trong tài liệu tham khảo.

Bắt đầu sử dụng sự kiệ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 Google Workspace trên tài nguyên Drive. Điều này cho phép ứng dụng của bạn nhận sự kiện qua Google Cloud Pub/Sub.

Tạo dự án Google Cloud

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

Bật Google Workspace Events API, Google Cloud Pub/Sub API và API Google Drive

Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.

Bảng điều khiển Google Cloud

Trong bảng điều khiển Google Cloud, hãy mở dự án Google Cloud cho ứng dụng của bạn và bật Google Workspace Events API, Pub/Sub API và API Drive:

Bật các API
Xác nhận rằng bạn đang bật các API trong dự án trên đám mây chính xác, sau đó nhấp vào Tiếp theo.
Xác nhận rằng bạn đang bật các API chính xác, sau đó nhấp vào Bật.

gcloud

Trong thư mục làm việc, hãy đăng nhập vào Tài khoản Google của bạn:
```
gcloud auth login
```
Đặt dự án của bạn thành dự án trên đám mây cho ứng dụng của bạn:
```
gcloud config set project PROJECT_ID
```
Thay thế PROJECT_ID bằng mã dự án cho dự án trên đám mây của ứng dụng.

Bật Google Workspace Events API, Pub/Sub API và API Drive:

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

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

Để tạo mã ứng dụng OAuth 2.0, hãy xem bài viết Tạo thông tin xác thực mã ứng dụng 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 có liên quan mà ứng dụng của bạn quan tâm. Để tạo chủ đề Pub/Sub, hãy xem bài viết Tạo và đăng ký nhận chủ đề Pub/Sub topic.

Hãy nhớ tham chiếu 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

Các sự kiện trên Cloud được gửi đi khi đối tượng thuê bao (hoặc bất kỳ tệp nào khác trong hệ thống phân cấp của đối tượng) thay đổi. Ví dụ: nếu bạn tạo gói thuê bao trên 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ì hệ thống sẽ tạo một sự kiện. Để biết các tài nguyên và loại sự kiện Drive được hỗ trợ, hãy xem phần Loại sự kiện để tạo gói thuê bao.

Ứng dụng Node.js sau đây tạo gói thuê bao sự kiện Drive trên 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 & npm installed. Bạn cũng cần đảm bảo đã cài đặt các phần phụ thuộc bắt buộc để 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.createcủa Google Workspace Events API để 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ả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 nhưng 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ý nhận, được định dạng dưới dạng tên tài nguyên đầy đủ. Ví dụ: để đăng ký nhận tệp hoặc thư mục 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ý nhận trong tài nguyên đích. Định dạng dưới dạng mảng chuỗi, chẳng hạn như 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: Một giá trị boolean chỉ định xem 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 gian của gói thuê bao. Để tìm hiểu thêm, hãy xem phần 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ỉ các gói thuê bao cho tài nguyên Chat và Drive mới hỗ trợ việc đưa dữ liệu tài nguyên vào.
- False: Loại trừ dữ liệu tài nguyên.
INCLUDE_DESCENDANTS: Một trường boolean là một phần của DriveOptions. Chỉ có khi targetResource là tệp 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 Drive cấp dưới 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. Chủ đề Pub/Sub này nhận các sự kiện cho gói thuê bao. Được đị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 gửi sự kiện.

Kiểm thử gói thuê bao Drive

Để kiểm thử rằng bạn đang nhận sự kiện Drive, 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 thử gói thuê bao Google Workspace.

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

Sự kiện Drive được gửi đến chủ đề Pub/Sub trong gói thuê bao mà bạn tạo. Hãy đảm bảo rằng khi tạo điều kiện kích hoạt, chủ đề Pub/Sub cho điều kiện kích hoạt sẽ 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);
  }
});

Các điểm hạn chế

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ù bạn có thể đã tạo gói thuê bao trên một thư mục, nhưng bạn có thể không nhận được tất cả sự kiện trong hệ thống 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 các tài nguyên mà bạn không có quyền truy cập.
Các 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. Các gói thuê bao 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 trên tệp tương ứng với các sự kiện mà họ đăng ký nhận.
Gói thuê bao chỉ nhận sự kiện cho các 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ọ.

Làm việc với các sự kiện trên Google Drive Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.