Trang này được dịch bởi Cloud Translation API.

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 các sự kiện trên Google Drive từ Google Cloud Pub/Sub.

Sự kiện trên Drive biểu thị một hoạt động hoặc thay đổi đối với một 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 để tìm hiểu những gì đã xảy ra, sau đó thực hiện hành động hoặc phản hồi theo cách có ý nghĩa đối với 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:

Theo dõi 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 điểm cần 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, 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ó sự kiện xảy ra trong Drive, một tài nguyên Google Drive API sẽ được tạo, cập nhật hoặc xoá. Drive sử dụng các sự kiện để gửi thông tin đến ứng dụng của bạn về loại hoạt động đã xảy ra và tài nguyên Drive API bị ảnh hưởng.

Drive phân loại các sự kiện theo loại. Các loại sự kiện giúp bạn lọc và chỉ nhận được 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 trong Drive ảnh hưởng đến tài nguyên Drive API có 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 Drive API	Loại sự kiện
Người dùng thêm một 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 một đề xuất cấp quyền truy cập cho một tệp.	Tài nguyên `AccessProposal` sẽ được tạo.	Đề xuất cấp quyền truy cập 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 API Google Drive Activity. Khi thêm các sự kiện trên Drive vào Google Workspace Events API, giờ đây, bạn có thể nhận sự kiện bằng phương thức thứ ba:

Bản dùng thử dành cho nhà phát triể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 thông báo về các sự kiện trên Google Drive.
Đăng ký nhận sự kiện bằng Drive API. Nhận các sự kiện thay đổi của người dùng bằng phương thức changes.watch hoặc cá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:

	Đăng ký nhận thông tin về các sự kiện của Google Workspace	Đăng ký nhận thông báo về các sự kiện theo dõi của Drive API	Truy vấn các 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 về 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 liên tục thăm dò các điểm cuối API.	Lấy nhật ký chi tiết về tất cả hoạt động, bao gồm cả thông tin 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 Drive	Drive Activity API
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ợ	`File` `AccessProposal` Để xem danh sách các loại sự kiện được hỗ trợ, hãy xem phần Các loại sự kiện để tạo gói thuê bao trong tài liệu về Google Workspace Events API.	`Channel` Để xem danh sách các loại sự kiện được hỗ trợ, hãy xem phần Tìm hiểu về các sự kiện thông báo của API Google Drive trong tài liệu về Drive API.	`Action` Để biết danh sách các trường được hỗ trợ, hãy xem tài nguyên `Action` trong tài liệu tham khảo Drive Activity API.
Định dạng sự kiện	Một thông báo Pub/Sub, được định dạng theo quy cách CloudEvent. Để biết thông tin chi tiết, hãy xem phần Cấu trúc của các sự kiện trên Google Workspace.	Tài nguyên Drive API (`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 ví dụ về tải trọng, 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 ví dụ về tải trọng, 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. Để xem ví dụ về tải trọng, hãy xem nội dung phản hồi `activity.query` trong tài liệu tham khảo.

Làm quen với sự kiện trên Drive

Hướng dẫn này giải thích cách tạo và quản lý chế độ đăng ký sự kiện của Google Workspace trên một tài nguyên Drive. Điều này cho phép ứng dụng của bạn nhận các 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 phần Tạo một dự án trên Google Cloud.

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

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

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

Trong Google Cloud Console, hãy mở dự án Google Cloud cho ứng dụng của bạn rồi bật Google Workspace Events API, Pub/Sub API và Drive API:

Bật API
Xác nhận rằng bạn đang bật các API trong dự án Cloud chính xác, sau đó nhấp vào Tiếp theo.
Xác nhận rằng bạn đang bật đúng API, 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 Cloud cho ứng dụng:
```
gcloud config set project PROJECT_ID
```
Thay PROJECT_ID bằng mã dự án cho dự án trên Cloud của ứng dụng.

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

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

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 đăng nhập mã ứng dụng khách OAuth.

Tạo một chủ đề Pub/Sub

Trước khi tạo một 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 phần Tạo và đăng ký chủ đề Pub/Sub.

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 đám mây sẽ được gửi đi khi chủ đề đăng ký (hoặc bất kỳ tệp nào khác trong hệ thống phân cấp của chủ đề) thay đổi. Ví dụ: nếu bạn tạo một lượt đăng ký trên bộ nhớ dùng chung và một tệp thay đổi nằm trong nhiều 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 loại tài nguyên và sự kiện được hỗ trợ trên Drive, hãy xem phần Các loại sự kiện để tạo lượt đăng ký.

Ứng dụng Node.js sau đây tạo một chế độ đăng ký 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 và npm. 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 một gói thuê bao Drive, bạn sử dụng phương thức subscriptions.create() của Google Workspace Events API để tạo một 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/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);

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ý nhận thông báo, được định dạng dưới dạng tên tài nguyên đầy đủ. Ví dụ: để đăng ký nhận thông báo về một tệp hoặc thư mục trên Drive, hãy 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 đích. Định dạng dưới dạng một mảng gồm các chuỗi, chẳng hạn như 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: 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 sử dụng gói thuê bao của bạn. Để 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 những 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ỉ hỗ trợ việc đăng ký nhận thông báo về tài nguyên Chat và Drive, bao gồm cả 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ó khi targetResource là một tệp Drive hoặc một 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: Sự kiện đăng ký bao gồm tất cả các tệp trên Drive trong danh sách sự kiện.
- False: Lệnh đăng ký được tạo cho một tệp hoặc ổ đĩa 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 Cloud. Chủ đề Pub/Sub này nhận các sự kiện cho gói thuê bao. Được định dạng dưới dạng projects/PROJECT_ID/topics/TOPIC_ID. Trường notificationEndpoint dùng để chỉ định chủ đề Pub/Sub và là nơi gói thuê bao gửi các sự kiện.

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

Để kiểm tra xem bạn có 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 thử gói thuê bao Google Workspace.

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

Các sự kiện trên Drive sẽ đượ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 rằng 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);
  }
});

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

Khi trường boolean includeDescendants trong DriveOptions là true, các sự kiện đăng ký trên Drive đối với 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 đó nằm sâu nhiều lớp bên dưới thư mục được dùng cho sự kiện đăng ký trên Drive.
Mặc dù đã tạo một chế độ đăng ký trên một thư mục, nhưng bạn có thể không nhận được tất cả cá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 những tài nguyên mà bạn không có quyền truy cập.
Bạn có thể đăng ký nhận thông báo về các sự kiện trên mọi tệp và thư mục, nhưng không thể đăng ký nhận thông báo về các sự kiện 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 đăng ký phải có quyền đối với tệp tương ứng với các sự kiện mà họ đăng ký.
Dịch vụ đăng ký chỉ nhận cá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ọ.