טריגרים של Cloud Storage

דור שני דור ראשון

אתם יכולים להפעיל פונקציה בתגובה להעלאה, לעדכון או למחיקה של קבצים ותיקיות ב-Cloud Storage.

הדוגמאות בדף הזה מבוססות על פונקציה לדוגמה שמופעלת כשמעלים קובצי תמונות אל Cloud Storage. פונקציית הדוגמה הזו מדגימה איך לגשת למאפייני אירועים, איך להוריד קובץ למופע Cloud Functions ועוד פעולות בסיסיות לטיפול באירועי Cloud Storage.

דוגמאות נוספות לתרחישי שימוש מופיעות במאמר מה אפשר לעשות עם Cloud Functions?

הפעלת פונקציה בשינויים ב-Cloud Storage

משתמשים ב-functions.storage כדי ליצור פונקציה שמטפלת באירועים של Cloud Storage. בהתאם לכך שרוצים להגדיר את הפונקציה לCloud Storage bucket ספציפי או להשתמש ב-bucket שמוגדר כברירת מחדל, משתמשים באחת מהאפשרויות הבאות:

• ‫functions.storage.object() כדי להאזין לשינויים באובייקטים בקטגוריית Cloud Storage שמוגדרת כברירת מחדל.
• ‫functions.storage.bucket('bucketName').object() כדי לעקוב אחרי שינויים באובייקטים בקטגוריה ספציפית.

לדוגמה, הדוגמה של מחולל התמונות הממוזערות מוגבלת לקטגוריית ברירת המחדל של הפרויקט:

exports.firstGenGenerateThumbnail = functions.storage.object().onFinalize(async (object) => {
  // ...
});

חשוב: המרחק בין המיקום של מאגר Cloud Storage לבין המיקום של הפונקציה יכול ליצור זמן אחזור משמעותי ברשת. כדי לשפר את הביצועים, כדאי לציין את מיקום הפונקציה במקרים הרלוונטיים.

‫Cloud Storage תומך באירועים הבאים:

• ‫onArchive מתרחש רק אם האפשרות object versioning מופעלת בקטגוריה. האירוע הזה מציין שהגרסה הפעילה של אובייקט הפכה לגרסה בארכיון – בגלל שהיא הועברה לארכיון או כי העלאה של אובייקט באותו שם החליפה את האובייקט הקיים.
• onDelete מתרחש כשאובייקט נמחק באופן סופי. זה כולל גם אובייקטים שנמחקים או שנכתבים מחדש כחלק מהגדרות מחזור החיים של הקטגוריה. בקטגוריות שבהן מופעל ניהול גרסאות של אובייקטים, האירוע הזה לא נשלח כשמעבירים אובייקט לארכיון (ראו onArchive), גם אם ההעברה לארכיון מתבצעת באמצעות השיטה storage.objects.delete.
• onFinalize מתרחש כשנוצר אובייקט חדש בקטגוריה (או כשאובייקט קיים נוצר מחדש). זה כולל העתקה או שכתוב של אובייקט קיים. האירוע הזה לא יופעל במקרה של העלאה שנכשלה.
• onMetadataUpdate מתרחש כשהמטא-נתונים של אובייקט קיים משתנים.

מגדירים את האירוע בתוך on event handler כמו שמוצג למעלה עבור onFinalize.

גישה למאפייני אובייקט Cloud Storage

‫Cloud Functions חושף מספר מאפייני אובייקט של Cloud Storage, כמו size ו-contentType, עבור הקובץ שעודכן. הערך של המאפיין metageneration גדל בכל פעם שחל שינוי במטא-נתונים של האובייקט. באובייקטים חדשים, הערך של metageneration הוא 1.

const fileBucket = object.bucket; // The Storage bucket that contains the file.
const filePath = object.name; // File path in the bucket.
const contentType = object.contentType; // File content type.
index.js

בדוגמה ליצירת תמונות ממוזערות נעשה שימוש בחלק מהמאפיינים האלה כדי לזהות מקרים שבהם הפונקציה מחזירה:

// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith('image/')) {
  return functions.logger.log('This is not an image.');
}

// Get the file name.
const fileName = path.basename(filePath);
// Exit if the image is already a thumbnail.
if (fileName.startsWith('thumb_')) {
  return functions.logger.log('Already a Thumbnail.');
}
index.js

הורדה, שינוי והעלאה של קובץ

במקרים מסוימים, יכול להיות שלא יהיה צורך להוריד קבצים מ-Cloud Storage. עם זאת, כדי לבצע משימות אינטנסיביות כמו יצירת תמונה ממוזערת מקובץ שמאוחסן ב-Cloud Storage, צריך להוריד קבצים למופע של הפונקציות – כלומר, למכונה הווירטואלית שמריצה את הקוד.

כדי להוריד בקלות אובייקטים ולהעלות אותם מחדש אל Cloud Storage, מתקינים את Google Cloud Storage באמצעות npm install --save @google-cloud/storage ומייבאים אותו. כדי להשתמש ב-JavaScript promises לטיפול בתהליכים חיצוניים כמו משימות עיבוד התמונות הממוזערות בדוגמה, צריך גם לייבא את child-process-promise:

const functions = require('firebase-functions/v1');
const admin = require('firebase-admin');
admin.initializeApp()
const path = require('path');

//library for resizing images
const sharp = require('sharp');
index.js

משתמשים ב-gcs.bucket.file(filePath).download כדי להוריד קובץ לספרייה זמנית במופע Cloud Functions. במיקום הזה, תוכלו לעבד את הקובץ לפי הצורך ואז להעלות אותו אל Cloud Storage. כשמבצעים משימות אסינכרוניות, חשוב להחזיר הבטחה של JavaScript בקריאה החוזרת.

דוגמה: שינוי תמונה

אפשר להשתמש ב-Cloud Functions יחד עם תוכנות לעיבוד תמונות כמו sharp כדי לבצע מניפולציות בקובצי תמונות גרפיות. הדוגמה הבאה מראה איך ליצור תמונה ממוזערת לקובץ תמונה שהועלה:

// Download file from bucket.
const bucket = admin.storage().bucket(fileBucket);
const metadata = {
  contentType: contentType,
};
const downloadResponse = await bucket.file(filePath).download();
const imageBuffer = downloadResponse[0];
functions.logger.log("Image downloaded!");

// Generate a thumbnail using sharp.
const thumbnailBuffer = await sharp(imageBuffer).resize({
  width: 200,
  height: 200,
  withoutEnlargement: true,
}).toBuffer();
functions.logger.log("Thumbnail created");

// Upload the thumbnail with a 'thumb_' prefix.
const thumbFileName = `thumb_${fileName}`;
const thumbFilePath = path.join(path.dirname(filePath), thumbFileName);
await bucket.file(thumbFilePath).save(thumbnailBuffer, {
  metadata: metadata,
});
return functions.logger.log("Thumbnail uploaded!");
index.js

הקוד הזה יוצר תמונה ממוזערת בגודל 200x200 לתמונה שנשמרה בספרייה זמנית, ואז מעלה אותה בחזרה אל Cloud Storage.

דוגמאות נוספות

עוד דוגמאות לפונקציות נפוצות של טרנספורמציה של מדיה, כולל טרנסקוד של תמונות, סינון תוכן וחילוץ מטא-נתונים של EXIF. הרשימה המלאה של הדוגמאות זמינה ב-GitHub.