טריגרים של Cloud Storage (דור ראשון)

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

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

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

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

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

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

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

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

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

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

מגדירים את האירוע בתוך הגורם המטפל באירועים של on, כמו שמוצג למעלה לגבי 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 לטיפול בתהליכים חיצוניים, כמו משימות העיבוד של התמונות הממוזערות בדוגמה, צריך לייבא גם את child-process-promise:

const functions = require('firebase-functions/v1');
const { initializeApp } = require('firebase-admin/app');
const { getStorage } = require('firebase-admin/storage');
initializeApp();
const path = require('path');

//library for resizing images
const sharp = /** @type {typeof import('sharp')} */ (require('sharp'));
index.js

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

דוגמה: טרנספורמציה של תמונה

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

// Download file from bucket.
const bucket = getStorage().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.