בדף הזה מוסבר איך לקבל אירועים של Google Drive מ-Google Cloud Pub/Sub.
אירוע ב-Drive מייצג פעילות או שינוי במשאב ב-Drive, כמו קובץ חדש בתיקייה. אתם יכולים להשתמש באירועים כדי להבין מה קרה ואז לפעול, או להגיב בצורה משמעותית למשתמשים.
הנה כמה דוגמאות לשימוש באירועים:
לצפות בשינויים בקובץ, בתיקייה או באחסון שיתופי ולהגיב להם, למשל כשקובץ נערך או כשגרסה חדשה מועלית.
כדי לשפר את ביצועי האפליקציה, אתם יכולים לעקוב אחרי שינויים בקבצים.
כדי לזהות דליפות נתונים פוטנציאליות וגישה לא מורשית, אפשר לבדוק פעילויות כמו שיתוף קבצים, העברת קבצים ומחיקות.
התובנות האלה עוזרות להבין איך המשתמשים מנהלים את הקבצים שלהם, ולזהות תחומים שבהם אפשר לשפר את ניהול התוכן.
לעקוב אחרי שינויים בקבצים כדי לוודא שהם עומדים בדרישות הרגולטוריות או במדיניות האבטחה.
לנתח את הפעילות ב-Drive באמצעות מוצרים אחרים של Google Cloud, כמו Eventarc, Workflows ו-BigQuery.
איך אירועים פועלים
בכל פעם שקורה משהו ב-Drive, משאב של Google Drive API נוצר, מתעדכן או נמחק. ב-Drive נעשה שימוש באירועים כדי להעביר לאפליקציה מידע על סוג הפעילות שהתרחשה ועל המשאב של Drive API שהושפע.
ב-Drive, האירועים מסווגים לפי סוג. סוגי האירועים עוזרים לכם לסנן ולקבל רק את סוג המידע שאתם צריכים, ומאפשרים לכם לטפל בפעילויות דומות באותו אופן.
בטבלה הבאה מוצג איך פעילות לדוגמה ב-Drive משפיעה על משאב קשור של Drive API, וסוג האירוע שאפליקציית Drive מקבלת:
| פעילות | משאב של Drive API | סוג אירוע |
|---|---|---|
| משתמש יוצר הצעה לגישה לקובץ. | נוצר משאב AccessProposal. |
הצעה חדשה לגישה |
משתמש יוצר אישור בקובץ. |
נוצר משאב Approval. |
בקשת אישור חדשה |
| משתמש מפרסם תגובה בקובץ ב-Google Docs, ב-Sheets או ב-Slides. | נוצר משאב Comment. |
תגובה חדשה |
| משתמש מוסיף קובץ לתיקייה או לאחסון שיתופי. | נוצר משאב File. |
קובץ חדש |
| משתמש יוצר הרשאות בקובץ. | נוצר משאב Permission. |
הרשאה חדשה |
| משתמש משיב לתגובה. | נוצר משאב Reply. |
תשובה חדשה |
קבלת אירועים מ-Google Drive
בעבר, אפליקציית Drive שלכם יכלה לאתר אירועים באמצעות Drive API או Google Drive Activity API. עם הוספת האירועים ב-Drive ל-Google Workspace Events API, יש עכשיו שיטה שלישית לקבלת אירועים:
להירשם לאירועים באמצעות Google Workspace Events API כדי לקבל אירועים כשהם מתרחשים. מידע נוסף זמין במאמר הרשמה לאירועים ב-Google Drive.
להירשם לאירועים באמצעות Drive API. אפשר לקבל אירועי שינוי של משתמשים באמצעות השיטה
changes.watchאו אירועי שינוי של קבצים באמצעות השיטהfiles.watch.שליחת שאילתה לגבי אירועים אחרונים באמצעות קריאה ל-Google Drive Activity API.
בטבלה הבאה מוסברים ההבדלים בין הרשמה לאירועים לבין שליחת שאילתות לגביהם, והסיבות לכל אחת מהאפשרויות:
| הרשמה לאירועים של Google Workspace | הרשמה לאירועי צפייה ב-Drive API | שאילתה לאירועים ב-Drive Activity API | |
|---|---|---|---|
| תרחישים לדוגמה |
|
|
|
| API | Google Workspace Events API | Google Drive API | Google Drive Activity API |
| מקור האירועים | קבצים, תיקיות ותיקיות אחסון שיתופי |
changes.watch וגם files.watch
|
DriveActivity
|
| אירועים נתמכים |
|
Channel
רשימה של סוגי האירועים הנתמכים מופיעה במאמר הסבר על אירועי התראות של Google Drive API במאמרי העזרה של Drive API. |
Action
רשימה של השדות הנתמכים מופיעה במשאב Action במאמרי העזרה של Drive Activity API.
|
| פורמט האירוע | הודעת Pub/Sub בפורמט של מפרט CloudEvent. פרטים נוספים זמינים במאמר מבנה האירועים של Google Workspace. |
משאב של Drive API (Channel)
|
משאב של Drive Activity API (Action)
|
| נתוני אירוע | מחרוזת בקידוד Base64 עם או בלי נתוני משאבים. לדוגמאות של נתוני מטען ייעודי (payload), ראו נתוני אירועים. |
מטען ייעודי (payload) של JSON שמכיל נתוני משאבים. לדוגמה של מטען ייעודי (payload), אפשר לעיין במשאב Channel במאמרי העזרה.
|
מטען ייעודי (payload) של JSON שמכיל נתוני משאבים. לדוגמה של מטען ייעודי (payload), אפשר לעיין בגוף התגובה של activity.query במאמרי העזרה.
|
איך מתחילים לעבוד עם אירועים ב-Drive
במדריך הזה מוסבר איך ליצור ולנהל מינוי לאירועים ב-Google Workspace במשאב ב-Drive. כך האפליקציה תוכל לקבל אירועים דרך Google Cloud Pub/Sub.
יצירת פרויקט של Google Cloud
כדי ליצור פרויקט ב-Google Cloud, קראו את המאמר יצירת פרויקט ב-Google Cloud.
הפעלת Google Workspace Events API, Google Cloud Pub/Sub API ו-Google Drive API
לפני שאתם משתמשים בממשקי Google API, אתם צריכים להפעיל אותם בפרויקט ב-Google Cloud. בכל פרויקט אפשר להפעיל ממשק API אחד או יותר.מסוף Google Cloud
במסוף Google Cloud, פותחים את הפרויקט בענן של האפליקציה ומפעילים את Google Workspace Events API, Pub/Sub API ו-Drive API:
מוודאים שממשקי ה-API מופעלים בפרויקט הנכון ב-Cloud ולוחצים על Next.
מוודאים שמפעילים את ממשקי ה-API הנכונים ולוחצים על הפעלה.
gcloud
בספריית העבודה, נכנסים לחשבון Google:
gcloud auth loginמגדירים את הפרויקט לפרויקט בענן של האפליקציה:
gcloud config set project PROJECT_IDמחליפים את
PROJECT_IDבמזהה הפרויקט של פרויקט הענן שמשויך לאפליקציה.מפעילים את 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 והרשמה אליו.
חשוב להפנות את הבקשות לחשבון השירות של Drive (drive-api-event-push@system.gserviceaccount.com).
יצירת מינוי ל-Drive
אירועי Cloud נשלחים כשנושא המינוי (או כל קובץ אחר בהיררכיה של הנושא) משתנה. לדוגמה, אם יוצרים מינוי באחסון שיתופי וקובץ שמוטמע בכמה תיקיות משנה באחסון השיתופי הזה משתנה, נוצר אירוע. במאמר סוגי אירועים ליצירת מינויים מפורטים המשאבים וסוגי האירועים ב-Drive שנתמכים.
אפליקציית Node.js הבאה יוצרת מינוי לאירועים ב-Drive בקובץ או בתיקייה כדי להאזין לאירועים של שינוי תוכן. מידע נוסף זמין במאמר יצירת מינוי ל-Google Workspace.
כדי להריץ את הדוגמה הזו, ודאו שהתקנתם את Node.js ו-npm. כדי להריץ את הדוגמה הזו, צריך גם לוודא שהתקנתם את יחסי התלות הנדרשים.
# Install needed dependencies
$ npm install googleapis @google-cloud/local-auth axiosכדי ליצור מינוי ב-Drive, משתמשים ב-method 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'];
/**
* 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);
מחליפים את מה שכתוב בשדות הבאים:
SCOPES: היקף הרשאות אחד או יותר ב-OAuth שתומך בכל סוג אירוע במינוי. בפורמט של מערך מחרוזות. כדי לציין כמה היקפים, צריך להפריד ביניהם באמצעות פסיקים. מומלץ להשתמש בהיקף ההרשאות המצומצם ביותר שעדיין מאפשר לאפליקציה לפעול. לדוגמה:'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE: המשאב ב-Google Workspace שאליו נרשמים, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם לקובץ או לתיקייה ב-Drive, משתמשים ב-//drive.googleapis.com/files/FileID.
EVENT_TYPES: סוג אירוע אחד או יותר שרוצים להירשם אליו במשאב המטרה. צריך להזין את הערך כמערך של מחרוזות, למשל'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: ערך בוליאני שמציין אם המינוי כולל נתוני משאבים במטען הייעודי (payload) של האירוע. המאפיין הזה משפיע על משך המינוי. מידע נוסף על נתוני אירועים
True: כולל את כל נתוני המשאבים. כדי להגביל את השדות שייכללו, מוסיפים אתfieldMaskומציינים לפחות שדה אחד למשאב שהשתנה. רק מינויים ל-Chat ול-Drive תומכים במשאבים שכוללים נתוני משאבים.
False: לא כולל נתוני משאבים.
INCLUDE_DESCENDANTS: שדה בוליאני שהוא חלק מ-DriveOptions. האפשרות הזו זמינה רק אםtargetResourceהוא קובץ ב-Drive או אחסון שיתופי שסוג ה-MIME שלו מוגדר כ-application/vnd.google-apps.folder. אי אפשר להגדיר את זה בתיקיית הבסיס של "האחסון שלי" או של תיקיות אחסון שיתופי.
True: המינוי כולל את כל קובצי הצאצא ב-Drive ברשימת האירועים.
False: המינוי נוצר לקובץ היחיד או לאחסון השיתופי שצוין בתורtargetResource.
TOPIC_NAME: השם המלא של נושא Pub/Sub שיצרתם בפרויקט בענן. הנושא הזה ב-Pub/Sub מקבל אירועים מהמינוי. בפורמטprojects/PROJECT_ID/topics/TOPIC_ID. השדהnotificationEndpointמשמש לציון נושא Pub/Sub, והוא המקום שאליו המינוי מעביר אירועים.
בדיקת המינוי ל-Drive
כדי לבדוק אם אתם מקבלים אירועים מ-Drive, אתם יכולים להפעיל אירוע ולמשוך הודעות למינוי ב-Pub/Sub. מידע נוסף זמין במאמר בדיקת המינוי ל-Google Workspace.
עיבוד אירועים ב-Drive באמצעות Cloud Functions
אירועים ב-Drive נשלחים לנושא 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, מינויים ל-Drive בתיקיות ובאחסון שיתופי תמיד שולחים אירוע, גם אם הקובץ שהפעיל את האירוע נמצא הרבה שכבות מתחת לתיקייה שמשמשת למינוי ל-Drive. - גם אם יצרתם מינוי בתיקייה, יכול להיות שלא תקבלו את כל האירועים בהיררכיית הקבצים כי למשתמש או לאפליקציה אין גישה אליהם. במקרה כזה, המינוי נשאר פעיל אבל לא מתקבלים אירועים לגבי משאבים שאין לכם גישה אליהם.
- אפשר להירשם לאירועים בכל הקבצים והתיקיות, אבל לא בתיקיית הבסיס של תיקיות האחסון השיתופי. אפשר להירשם רק לקבצים ולתיקיות בתוך תיקיות אחסון שיתופי. שינויים שבוצעו ישירות בתיקיית הבסיס של אחסון שיתופי לא יפעילו אירועים.
- למשתמש שמאשר את המינוי צריכה להיות הרשאה בקובץ שתואם לאירועים שהוא נרשם אליהם.
- המינוי מקבל רק אירועים של משאבים שלמשתמש יש גישה אליהם דרך חשבון Google Workspace או חשבון Google שלו.
מידע על מכסות של מינויים ומגבלות קצב של יצירת בקשות מופיע במאמר מגבלות שימוש ב-Google Workspace Events API.