טריגרים של Cloud Storage

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

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

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

מייבאים את המודולים הנדרשים

כדי להתחיל, מייבאים את המודול הנדרש לטיפול באירועי Cloud Storage:

Node.js

 const {onObjectFinalized} = require("firebase-functions/v2/storage");
index.js

Python

 from firebase_functions import storage_fn
main.py

כדי ליצור את הדוגמה המלאה, צריך להוסיף גם את יחסי התלות של Firebase Admin SDK וכלי עיבוד התמונות:

Node.js

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

// library for image resizing
const sharp = require("sharp");

initializeApp();
index.js

Python

 import io
import pathlib

from PIL import Image

from firebase_admin import initialize_app

initialize_app()
from firebase_admin import storage
main.py

הגדרת היקף לפונקציה Cloud Storage

משתמשים בתבנית הבאה כדי להגביל את הפונקציה לקטגוריה ספציפית של Cloud Storage ולהגדיר את האפשרויות הרצויות:

Node.js

// scope handler to a specific bucket, using storage options parameter
export archivedopts = onObjectArchived({ bucket: "myBucket" }, (event) => {
  //…
});

Python

# Scope handler to a specific bucket using storage options parameter
@storage_fn.on_object_archived(bucket="myBucket")
def archived_bucket(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
    # ...

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

Node.js

exports.generateThumbnail = onObjectFinalized({cpu: 2}, async (event) => {
// ...
});

Python

@storage_fn.on_object_archived()
def generatethumbnail(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
    # ...

הגדרת המיקום של הפונקציה

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

• מיקום הפונקציה זהה למיקום הטריגר
• מיקום הפונקציה נמצא בתוך מיקום הטריגר (כשאזור הטריגר הוא דו-אזורי או רב-אזורי)
• הפונקציה יכולה להיות בכל מיקום אם אזור הטריגר מוגדר כ-us-central1

טיפול באירועי Cloud Storage

הגורמים המטפלים הבאים מאפשרים להגיב לאירועים של Cloud Storage:

Node.js

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

Python

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

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

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

Node.js

const fileBucket = event.data.bucket; // Storage bucket containing the file.
const filePath = event.data.name; // File path in the bucket.
const contentType = event.data.contentType; // File content type.
index.js

Python

bucket_name = event.data.bucket
file_path = pathlib.PurePath(event.data.name)
content_type = event.data.content_type
main.py

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

Node.js

// Exit if this is triggered on a file that is not an image.
if (!contentType.startsWith("image/")) {
  return logger.log("This is not an image.");
}
// Exit if the image is already a thumbnail.
const fileName = path.basename(filePath);
if (fileName.startsWith("thumb_")) {
  return logger.log("Already a Thumbnail.");
}
index.js

Python

# Exit if this is triggered on a file that is not an image.
if not content_type or not content_type.startswith("image/"):
    print(f"This is not an image. ({content_type})")
    return

# Exit if the image is already a thumbnail.
if file_path.name.startswith("thumb_"):
    print("Already a thumbnail.")
    return
main.py

הורדה, טרנספורמציה והעלאה של קובץ

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

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

Node.js

/**
 * When an image is uploaded in the Storage bucket,
 * generate a thumbnail automatically using sharp.
 */
exports.generateThumbnail = onObjectFinalized({cpu: 2}, async (event) => {

  const fileBucket = event.data.bucket; // Storage bucket containing the file.
  const filePath = event.data.name; // File path in the bucket.
  const contentType = event.data.contentType; // File content type.

  // Exit if this is triggered on a file that is not an image.
  if (!contentType.startsWith("image/")) {
    return logger.log("This is not an image.");
  }
  // Exit if the image is already a thumbnail.
  const fileName = path.basename(filePath);
  if (fileName.startsWith("thumb_")) {
    return logger.log("Already a Thumbnail.");
  }

  // Download file into memory from bucket.
  const bucket = getStorage().bucket(fileBucket);
  const downloadResponse = await bucket.file(filePath).download();
  const imageBuffer = downloadResponse[0];
  logger.log("Image downloaded!");

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

  // Prefix 'thumb_' to file name.
  const thumbFileName = `thumb_${fileName}`;
  const thumbFilePath = path.join(path.dirname(filePath), thumbFileName);

  // Upload the thumbnail.
  const metadata = {contentType: contentType};
  await bucket.file(thumbFilePath).save(thumbnailBuffer, {
    metadata: metadata,
  });
  return logger.log("Thumbnail uploaded!");
});
index.js

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

Python

@storage_fn.on_object_finalized()
def generatethumbnail(event: storage_fn.CloudEvent[storage_fn.StorageObjectData]):
    """When an image is uploaded in the Storage bucket, generate a thumbnail
    automatically using Pillow."""

    bucket_name = event.data.bucket
    file_path = pathlib.PurePath(event.data.name)
    content_type = event.data.content_type

    # Exit if this is triggered on a file that is not an image.
    if not content_type or not content_type.startswith("image/"):
        print(f"This is not an image. ({content_type})")
        return

    # Exit if the image is already a thumbnail.
    if file_path.name.startswith("thumb_"):
        print("Already a thumbnail.")
        return

    bucket = storage.bucket(bucket_name)

    image_blob = bucket.blob(str(file_path))
    image_bytes = image_blob.download_as_bytes()
    image = Image.open(io.BytesIO(image_bytes))

    image.thumbnail((200, 200))
    thumbnail_io = io.BytesIO()
    image.save(thumbnail_io, format="png")
    thumbnail_path = file_path.parent / pathlib.PurePath(f"thumb_{file_path.stem}.png")
    thumbnail_blob = bucket.blob(str(thumbnail_path))
    thumbnail_blob.upload_from_string(thumbnail_io.getvalue(), content_type="image/png")
main.py

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