ทำงานกับกิจกรรมจาก Google ไดรฟ์

<0x

หน้านี้จะอธิบายวิธีรับเหตุการณ์ใน Google ไดรฟ์จาก Google Cloud Pub/Sub

เหตุการณ์ในไดรฟ์แสดงถึงกิจกรรมหรือการเปลี่ยนแปลงใน ทรัพยากรของไดรฟ์ เช่น ไฟล์ใหม่ในโฟลเดอร์ คุณใช้เหตุการณ์เพื่อทําความเข้าใจสิ่งที่เกิดขึ้น แล้วดําเนินการ หรือตอบสนองในลักษณะที่ มีความหมายต่อผู้ใช้ได้

ตัวอย่างวิธีใช้เหตุการณ์มีดังนี้

• สังเกตและตอบสนองต่อการเปลี่ยนแปลงในไฟล์ โฟลเดอร์ หรือไดรฟ์ที่แชร์ เช่น เมื่อมีการแก้ไขไฟล์หรืออัปโหลดฉบับร่างใหม่

• ตรวจสอบการเปลี่ยนแปลงไฟล์เพื่อปรับปรุงประสิทธิภาพของแอป

• ตรวจสอบกิจกรรมต่างๆ เช่น การแชร์ไฟล์ การย้ายไฟล์ และการลบ เพื่อช่วยตรวจหา การรั่วไหลของข้อมูลที่อาจเกิดขึ้นและการเข้าถึงที่ไม่ได้รับอนุญาต

• ให้ข้อมูลเชิงลึกเกี่ยวกับวิธีที่ผู้ใช้จัดการไฟล์ ซึ่งจะช่วยระบุ ส่วนที่ควรปรับปรุงการจัดการเนื้อหา

• ติดตามการเปลี่ยนแปลงไฟล์เพื่อยืนยันการปฏิบัติตามข้อกำหนดด้านกฎระเบียบหรือ นโยบายความปลอดภัย

• วิเคราะห์กิจกรรมในไดรฟ์โดยใช้ผลิตภัณฑ์อื่นๆ ของ Google Cloud เช่น Eventarc, Workflows และ BigQuery

วิธีการทำงานของกิจกรรม

เมื่อใดก็ตามที่มีการดำเนินการในไดรฟ์ ระบบจะสร้าง อัปเดต หรือลบทรัพยากร Google ไดรฟ์ API ไดรฟ์ใช้เหตุการณ์เพื่อส่งข้อมูลไปยังแอปเกี่ยวกับประเภทกิจกรรมที่เกิดขึ้น และทรัพยากร Drive API ที่ได้รับผลกระทบ

ไดรฟ์จัดหมวดหมู่เหตุการณ์ตามประเภท ประเภทเหตุการณ์ช่วยให้คุณกรองและ รับเฉพาะข้อมูลประเภทที่ต้องการได้ และช่วยให้คุณจัดการกิจกรรมที่คล้ายกัน ในลักษณะเดียวกันได้

ตารางต่อไปนี้แสดงให้เห็นว่ากิจกรรมในไดรฟ์ส่งผลต่อทรัพยากรที่เกี่ยวข้องของ Drive API อย่างไร และประเภทเหตุการณ์ที่แอปไดรฟ์ได้รับ

กิจกรรม	ทรัพยากรของ Drive API	ประเภทของกิจกรรม
ผู้ใช้เพิ่มไฟล์ลงในโฟลเดอร์หรือไดรฟ์ที่แชร์	สร้างทรัพยากร File	ไฟล์ใหม่
ผู้ใช้สร้างข้อเสนอการเข้าถึงในไฟล์	สร้างทรัพยากร AccessProposal	ข้อเสนอการเข้าถึงใหม่

รับเหตุการณ์จาก Google ไดรฟ์

โดยปกติแล้ว แอปไดรฟ์จะค้นหาเหตุการณ์ผ่าน Drive API หรือ Google Drive Activity API การเพิ่มเหตุการณ์ในไดรฟ์ใน Google Workspace Events API ทำให้ตอนนี้มีวิธีที่ 3 ในการรับเหตุการณ์ ดังนี้

• รุ่นตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์: สมัครรับข้อมูลกิจกรรมโดยใช้ Google Workspace Events API เพื่อรับกิจกรรมเมื่อเกิดขึ้น

• สมัครรับข้อมูลกิจกรรมโดยใช้ Drive API รับเหตุการณ์การเปลี่ยนแปลงของผู้ใช้ ด้วยเมธอด changes.watch หรือเหตุการณ์การเปลี่ยนแปลงไฟล์โดยใช้เมธอด files.watch

• ค้นหาเหตุการณ์ล่าสุดโดยเรียกใช้ Google Drive Activity API

ตารางต่อไปนี้อธิบายความแตกต่างและเหตุผลในการสมัครรับข้อมูล เหตุการณ์เทียบกับการค้นหาเหตุการณ์

	สมัครรับข้อมูลกิจกรรมของ Google Workspace	ติดตามเหตุการณ์การดูของ Drive API	ค้นหาเหตุการณ์ Drive Activity API
กรณีการใช้งาน	ประมวลผลหรือตอบกลับเหตุการณ์แบบเรียลไทม์ ตรวจสอบการเปลี่ยนแปลงในทรัพยากรเพื่อปรับปรุงประสิทธิภาพของแอป รับข้อมูลเหตุการณ์ที่มีโครงสร้างผ่าน Pub/Sub และใช้ผลิตภัณฑ์ Google Cloud เช่น Cloud Run	ตรวจหาการเปลี่ยนแปลงข้อมูลเมตาของไฟล์และตรวจสอบการเปลี่ยนแปลงรายการที่เฉพาะเจาะจงได้อย่างมีประสิทธิภาพด้วยการแจ้งเตือนแบบเรียลไทม์ รองรับ URL การเรียกกลับของเว็บฮุคเพื่อหลีกเลี่ยงการสำรวจปลายทาง API ซ้ำๆ	ดึงประวัติโดยละเอียดของกิจกรรมทั้งหมด รวมถึงข้อมูลแบบละเอียดเกี่ยวกับแต่ละเหตุการณ์ ดึงกิจกรรมที่แม่นยำซึ่งมีข้อมูล ActionDetail, Actor และ Target สำหรับงานที่เฉพาะเจาะจง เช่น การตรวจสอบ
API	Google Workspace Events API	API ไดรฟ์	Drive Activity API
แหล่งที่มาของเหตุการณ์	ไฟล์ โฟลเดอร์ และไดรฟ์ที่แชร์	changes.watch และ files.watch	DriveActivity
เหตุการณ์ที่รองรับ	File AccessProposal ดูรายการประเภทกิจกรรมที่รองรับได้ที่ ประเภทกิจกรรมสำหรับการสร้างการสมัครใช้บริการใน เอกสารประกอบของ Google Workspace Events API	Channel ดูรายการประเภทเหตุการณ์ที่รองรับได้ที่ ทำความเข้าใจเหตุการณ์การแจ้งเตือนของ Google Drive API ในเอกสารประกอบของ Drive API	Action ดูรายการฟิลด์ที่รองรับได้ใน Action ในเอกสารอ้างอิง Drive Activity API
รูปแบบกิจกรรม	ข้อความ Pub/Sub ที่จัดรูปแบบตาม ข้อกำหนด CloudEvent โปรดดูรายละเอียดที่หัวข้อ โครงสร้างของกิจกรรมใน Google Workspace	ทรัพยากร Drive API (Channel)	ทรัพยากร Drive Activity API (Action)
ข้อมูลเหตุการณ์	สตริงที่เข้ารหัส Base64 ที่มีหรือไม่มีข้อมูลทรัพยากร ดูเพย์โหลดตัวอย่างได้ที่ข้อมูลเหตุการณ์	เพย์โหลด JSON ที่มีข้อมูลทรัพยากร ดูตัวอย่างเพย์โหลดได้ที่แหล่งข้อมูลChannel ในเอกสารอ้างอิง	เพย์โหลด JSON ที่มีข้อมูลทรัพยากร ดูตัวอย่างเพย์โหลดได้ที่activity.queryเนื้อหาการตอบกลับ ในเอกสารอ้างอิง

เริ่มต้นใช้งานเหตุการณ์ในไดรฟ์

คู่มือนี้อธิบายวิธีสร้างและจัดการการสมัครรับข้อมูลเหตุการณ์ใน Google Workspace ในทรัพยากรของไดรฟ์ ซึ่งจะช่วยให้แอปของคุณได้รับ เหตุการณ์ผ่าน Google Cloud Pub/Sub

สร้างโปรเจ็กต์ Google Cloud

หากต้องการสร้างโปรเจ็กต์ Google Cloud โปรดดูสร้างโปรเจ็กต์ Google Cloud

เปิดใช้ Google Workspace Events API, Google Cloud Pub/Sub API และ Google Drive API

ก่อนใช้ Google API คุณต้องเปิดใช้ API ในโปรเจ็กต์ Google Cloud คุณเปิด API อย่างน้อย 1 รายการในโปรเจ็กต์ Google Cloud เดียวได้

คอนโซล Google Cloud

1. ใน Google Cloud Console ให้เปิดโปรเจ็กต์ Google Cloud สำหรับแอป แล้ว เปิดใช้ Google Workspace Events API, Pub/Sub API และ Drive API โดยทำดังนี้

   เปิดใช้ API

2. ยืนยันว่าคุณกำลังเปิดใช้ API ในโปรเจ็กต์ Cloud ที่ถูกต้อง จากนั้นคลิกถัดไป

3. ยืนยันว่าคุณเปิดใช้ API ที่ถูกต้อง แล้วคลิกเปิดใช้

gcloud

1. ลงชื่อเข้าใช้บัญชี Google ในไดเรกทอรีการทำงานโดยทำดังนี้

   gcloud auth login

2. ตั้งค่าโปรเจ็กต์เป็นโปรเจ็กต์ Cloud สำหรับแอปของคุณ

   gcloud config set project PROJECT_ID

   แทนที่ PROJECT_ID ด้วยรหัสโปรเจ็กต์ สำหรับโปรเจ็กต์ระบบคลาวด์ของแอป

3. เปิดใช้ Google Workspace Events API, Pub/Sub API และ Drive API โดยทำดังนี้

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

ตั้งค่ารหัสไคลเอ็นต์

หากต้องการสร้างรหัสไคลเอ็นต์ OAuth 2.0 โปรดดูสร้างข้อมูลเข้าสู่ระบบรหัสไคลเอ็นต์ OAuth

สร้างหัวข้อ Pub/Sub

ก่อนสร้างการสมัครใช้บริการ คุณต้องสร้างหัวข้อ Google Cloud Pub/Sub ที่รับเหตุการณ์ที่เกี่ยวข้องซึ่งแอปพลิเคชันของคุณสนใจ หากต้องการสร้างหัวข้อ Pub/Sub ให้ดูสร้างและสมัครรับข้อมูลหัวข้อ Pub/Sub

โปรดอ้างอิงบัญชีบริการของไดรฟ์ ([e-mail]) สำหรับคำขอของคุณ

สร้างการสมัครใช้บริการไดรฟ์

ระบบจะส่งเหตุการณ์ในระบบคลาวด์เมื่อมีการเปลี่ยนแปลงหัวข้อการสมัครใช้บริการ (หรือไฟล์อื่นๆ ภายใต้ลำดับชั้นของหัวข้อ) เช่น หากคุณสร้างการติดตามในไดรฟ์ที่แชร์และมีการเปลี่ยนแปลงไฟล์ที่ซ้อนอยู่ใน โฟลเดอร์ย่อยหลายรายการในไดรฟ์ที่แชร์นั้น ระบบจะสร้างเหตุการณ์ ดูทรัพยากรที่รองรับ และประเภทเหตุการณ์ในไดรฟ์ได้ที่ประเภทเหตุการณ์สำหรับการสร้าง การติดตาม

แอปพลิเคชัน Node.js ต่อไปนี้จะสร้างการสมัครรับข้อมูลเหตุการณ์ในไดรฟ์ ในไฟล์หรือโฟลเดอร์เพื่อฟังเหตุการณ์การเปลี่ยนแปลงเนื้อหา โปรดดูข้อมูลเพิ่มเติมที่หัวข้อสร้างการสมัครใช้บริการ Google Workspace

หากต้องการเรียกใช้ตัวอย่างนี้ โปรดตรวจสอบว่าคุณได้ติดตั้ง Node.js และ npm แล้ว นอกจากนี้ คุณยังต้องตรวจสอบว่าได้ติดตั้งการอ้างอิงที่จำเป็นเพื่อเรียกใช้ ตัวอย่างนี้แล้ว

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

หากต้องการสร้างการสมัครใช้บริการไดรฟ์ คุณต้องใช้เมธอด subscriptions.create() ของ Google Workspace Events API เพื่อสร้างทรัพยากร 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'];

/**
 * Loads saved credentials from token.json, or authenticates the user.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  try {
    const content = await fs.readFile('token.json');
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    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;
  }
}

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

แทนที่ค่าต่อไปนี้

• SCOPES: ขอบเขต OAuth อย่างน้อย 1 รายการที่รองรับกิจกรรมแต่ละประเภทสำหรับการ สมัครใช้บริการ จัดรูปแบบเป็นอาร์เรย์ของสตริง หากต้องการแสดงขอบเขตหลายรายการ ให้คั่นด้วยคอมมา แนวทางปฏิบัติแนะนำคือคุณควรใช้ขอบเขตที่จำกัดมากที่สุด ซึ่งยังคงอนุญาตให้แอปทำงานได้ เช่น 'https://www.googleapis.com/auth/drive.file'

• TARGET_RESOURCE: ทรัพยากร Google Workspace ที่คุณสมัครใช้บริการ ซึ่งจัดรูปแบบเป็นชื่อทรัพยากรแบบเต็ม เช่น หากต้องการติดตามไฟล์หรือโฟลเดอร์ในไดรฟ์ ให้ใช้ //drive.googleapis.com/files/FileID

• EVENT_TYPES: ประเภทกิจกรรมอย่างน้อย 1 รายการ ที่คุณต้องการติดตามในแหล่งข้อมูลเป้าหมาย จัดรูปแบบเป็นอาร์เรย์ของ สตริง เช่น 'google.workspace.drive.file.v3.contentChanged'

• RESOURCE_DATA: บูลีนที่ระบุว่าการสมัครใช้บริการรวมข้อมูลทรัพยากรในเพย์โหลดของเหตุการณ์หรือไม่ พร็อพเพอร์ตี้นี้ จะส่งผลต่อระยะเวลาของการสมัครใช้บริการ ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลเหตุการณ์

  • True: รวมข้อมูลทรัพยากรทั้งหมด หากต้องการจำกัดช่องที่จะรวม ให้เพิ่ม fieldMask และระบุช่องอย่างน้อย 1 ช่องสำหรับทรัพยากรที่เปลี่ยนแปลง เฉพาะการสมัครใช้บริการ การสนับสนุนทรัพยากรของ Chat และไดรฟ์ รวมถึง ข้อมูลทรัพยากร

  • False: ไม่รวมข้อมูลทรัพยากร

• INCLUDE_DESCENDANTS: ฟิลด์บูลีนที่เป็นส่วนหนึ่งของ DriveOptions ใช้ได้เฉพาะเมื่อ targetResource เป็นไฟล์ในไดรฟ์หรือไดรฟ์ที่แชร์ซึ่งตั้งค่าประเภท MIME เป็น application/vnd.google-apps.folder ตั้งค่าในโฟลเดอร์รูทของไดรฟ์ของฉันหรือไดรฟ์ที่แชร์ไม่ได้

  • True: การสมัครใช้บริการรวมไฟล์ทั้งหมดในไดรฟ์ ที่สืบทอดมาในรายการกิจกรรม

  • False: ระบบจะสร้างการติดตามสำหรับไฟล์เดียวหรือไดรฟ์ที่แชร์ ซึ่งระบุเป็นtargetResource

• TOPIC_NAME: ชื่อเต็มของหัวข้อ Pub/Sub ที่คุณสร้างในโปรเจ็กต์ Cloud หัวข้อ Pub/Sub นี้จะได้รับเหตุการณ์ สำหรับการสมัครใช้บริการ โดยมีรูปแบบเป็น projects/PROJECT_ID/topics/TOPIC_ID ฟิลด์ notificationEndpoint ใช้เพื่อระบุหัวข้อ Pub/Sub และเป็นที่ที่การสมัครใช้บริการ ส่งเหตุการณ์

ทดสอบการสมัครใช้บริการไดรฟ์

หากต้องการทดสอบว่าคุณได้รับเหตุการณ์ในไดรฟ์หรือไม่ คุณสามารถทริกเกอร์ เหตุการณ์และดึงข้อความไปยังการสมัครใช้บริการ Pub/Sub ดูข้อมูลเพิ่มเติมได้ที่หัวข้อทดสอบการสมัครใช้บริการ Google Workspace

ประมวลผลเหตุการณ์ในไดรฟ์โดยใช้ Cloud Functions

ระบบจะส่งเหตุการณ์ในไดรฟ์ไปยังหัวข้อ Pub/Sub ในการสมัครใช้บริการ ที่คุณสร้าง ตรวจสอบว่าเมื่อสร้างทริกเกอร์ หัวข้อ Pub/Sub สำหรับ ทริกเกอร์จะตรงกับหัวข้อ Pub/Sub ในการสมัครใช้บริการเหตุการณ์ จากนั้นคุณจะติดตั้งใช้งานฟังก์ชัน Cloud Run และแก้ไขไฟล์เพื่อดูการเปลี่ยนแปลงเหตุการณ์ในบันทึกได้

ก่อนสร้างฟังก์ชัน ให้อัปเดต package.json สำหรับการอ้างอิงดังนี้

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

จากนั้นสร้างซอร์สโค้ดสำหรับฟังก์ชัน

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

ข้อจำกัด

• เมื่อฟิลด์บูลีน includeDescendants ใน DriveOptions เป็น true การติดตามไดรฟ์ในไดรฟ์ที่แชร์และโฟลเดอร์ จะส่งเหตุการณ์เสมอ แม้ว่าไฟล์ที่ทริกเกอร์เหตุการณ์จะซ้อนอยู่หลายชั้นใต้ โฟลเดอร์ที่ใช้สำหรับการติดตามไดรฟ์ก็ตาม
• แม้ว่าคุณจะสร้างการติดตามในโฟลเดอร์ แต่คุณอาจไม่ได้รับเหตุการณ์ทั้งหมด ภายในลำดับชั้นของไฟล์ เนื่องจากผู้ใช้หรือแอปพลิเคชันอาจไม่ได้รับสิทธิ์เข้าถึง ในกรณีนี้ การสมัครใช้บริการจะยังคงใช้งานได้ แต่คุณจะไม่ได้รับเหตุการณ์ใดๆ สำหรับทรัพยากรที่คุณไม่มีสิทธิ์เข้าถึง
• ระบบรองรับการติดตามกิจกรรมในไฟล์และโฟลเดอร์ทั้งหมด แต่ไม่รองรับในโฟลเดอร์รูทของ ไดรฟ์ที่แชร์ ระบบรองรับการติดตามเฉพาะไฟล์และโฟลเดอร์ภายในไดรฟ์ที่แชร์เท่านั้น การเปลี่ยนแปลงที่ทำกับโฟลเดอร์รูทของไดรฟ์ที่แชร์โดยตรงจะไม่ทริกเกอร์เหตุการณ์
• ผู้ใช้ที่ให้สิทธิ์การสมัครใช้บริการต้องมีสิทธิ์ในไฟล์ที่สอดคล้องกับ เหตุการณ์ที่สมัครใช้บริการ
• การสมัครใช้บริการจะรับเฉพาะเหตุการณ์สำหรับทรัพยากรที่ผู้ใช้มีสิทธิ์เข้าถึงผ่าน บัญชี Google Workspace หรือบัญชี Google

หัวข้อที่เกี่ยวข้อง

• ภาพรวมของ Google Workspace Events API
• สร้างการสมัครใช้บริการ Google Workspace