הרחבת Cloud Storage באמצעות Cloud Functions

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

אפשר להפעיל פונקציה בתגובה להעלאה, לעדכון או למחיקה של קבצים ותיקיות ב-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 לבין המיקום של הפונקציה יכול ליצור זמן אחזור משמעותי ברשת. כדי לשפר את הביצועים, מומלץ לציין את מיקום הפונקציה במקרים הרלוונטיים.

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 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 ב-callback.

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

אפשר להשתמש ב-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.