محرک های ذخیره سازی ابری

شما می‌توانید در پاسخ به آپلود، به‌روزرسانی یا حذف فایل‌ها و پوشه‌ها در Cloud Storage یک تابع را فعال کنید.

مثال‌های این صفحه بر اساس یک تابع نمونه است که هنگام آپلود فایل‌های تصویری در Cloud Storage فعال می‌شود. این تابع نمونه نحوه دسترسی به ویژگی‌های رویداد، نحوه دانلود یک فایل در یک نمونه Cloud Functions و سایر اصول مدیریت رویدادهای Cloud Storage را نشان می‌دهد.

ماژول‌های مورد نیاز را وارد کنید

برای شروع، ماژول مورد نیاز برای مدیریت رویدادهای Cloud Storage را وارد کنید:

نود جی اس

 const {onObjectFinalized} = require("firebase-functions/storage");

پایتون

 from firebase_functions import storage_fn

برای ساخت نمونه کامل، وابستگی‌های مربوط به Firebase Admin SDK و ابزارهای پردازش تصویر را نیز اضافه کنید:

نود جی اس

 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();

پایتون

 import io
import pathlib

from PIL import Image

from firebase_admin import initialize_app

initialize_app()
from firebase_admin import storage

محدوده یک تابع Cloud Storage

از الگوی زیر برای محدود کردن تابع خود به یک فضای Cloud Storage خاص و تنظیم گزینه‌های دلخواه استفاده کنید:

نود جی اس

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

پایتون

# 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]):
    # ...

در مقابل، تابع تولیدکننده‌ی تصویر بندانگشتیِ مثال، به سطل پیش‌فرض پروژه محدود می‌شود:

نود جی اس

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

پایتون

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

محل تابع را تنظیم کنید

عدم تطابق بین مکان‌ها می‌تواند منجر به شکست در استقرار شود. همچنین، فاصله بین محل قرارگیری یک سطل Cloud Storage و محل عملکرد می‌تواند تأخیر قابل توجهی در شبکه ایجاد کند. برای جلوگیری از این موقعیت‌ها، مکان عملکرد را طوری مشخص کنید که با محل سطل/راه‌انداز به یکی از روش‌های زیر مطابقت داشته باشد:

  • محل تابع همان محل تریگر است
  • مکان تابع درون مکان تریگر است (وقتی ناحیه تریگر دوگانه/چند ناحیه‌ای باشد)
  • اگر ناحیه تریگر روی us-central1 تنظیم شده باشد، تابع می‌تواند در هر مکانی باشد.

مدیریت رویدادهای Cloud Storage

این کنترل‌کننده‌ها برای پاسخ به رویدادهای Cloud Storage در دسترس هستند:

نود جی اس

  • onObjectArchived فقط زمانی ارسال می‌شود که یک باکت، قابلیت نسخه‌بندی شیء را فعال کرده باشد. این رویداد نشان می‌دهد که نسخه زنده یک شیء به یک نسخه بایگانی شده تبدیل شده است، یا به این دلیل که بایگانی شده است یا به این دلیل که توسط آپلود شیء دیگری با همین نام، بازنویسی شده است.
  • onObjectDeleted زمانی ارسال می‌شود که یک شیء به طور دائم حذف شده باشد. این شامل اشیاء بازنویسی شده یا حذف شده به عنوان بخشی از پیکربندی چرخه عمر سطل می‌شود. برای سطل‌هایی که قابلیت نسخه‌بندی شیء فعال است، این پیام هنگام بایگانی یک شیء ارسال نمی‌شود (به onArchive مراجعه کنید)، حتی اگر بایگانی از طریق متد storage.objects.delete انجام شود.
  • onObjectFinalized زمانی ارسال می‌شود که یک شیء جدید (یا نسل جدیدی از یک شیء موجود) با موفقیت در سطل ایجاد شود. این شامل کپی یا بازنویسی یک شیء موجود نیز می‌شود. آپلود ناموفق این رویداد را فعال نمی‌کند.
  • onMetadataUpdated زمانی ارسال می‌شود که فراداده‌های یک شیء موجود تغییر کند.

پایتون

  • on_object_archived فقط زمانی ارسال می‌شود که یک باکت ، نسخه‌بندی شیء را فعال کرده باشد. این رویداد نشان می‌دهد که نسخهٔ زندهٔ یک شیء به یک نسخهٔ بایگانی‌شده تبدیل شده است، یا به این دلیل که بایگانی شده یا به این دلیل که توسط بارگذاری شیء دیگری با همین نام بازنویسی شده است.
  • on_object_deleted زمانی ارسال می‌شود که یک شیء به طور دائم حذف شده باشد. این شامل اشیاء بازنویسی شده یا حذف شده به عنوان بخشی از پیکربندی چرخه عمر سطل می‌شود. برای سطل‌هایی که قابلیت نسخه‌بندی شیء فعال است، این پیام هنگام بایگانی یک شیء ارسال نمی‌شود (به onArchive مراجعه کنید)، حتی اگر بایگانی از طریق متد storage.objects.delete انجام شود.
  • on_object_finalized زمانی ارسال می‌شود که یک شیء جدید (یا نسل جدیدی از یک شیء موجود) با موفقیت در سطل ایجاد شود. این شامل کپی یا بازنویسی یک شیء موجود نیز می‌شود. آپلود ناموفق این رویداد را فعال نمی‌کند.
  • on_metadata_updated زمانی ارسال می‌شود که متادیتای یک شیء موجود تغییر کند.

دسترسی به ویژگی‌های شیء Cloud Storage

Cloud Functions تعدادی از ویژگی‌های شیء Cloud Storage مانند اندازه شیء و نوع محتوای آن را برای فایل به‌روزرسانی‌شده نمایش می‌دهند. ویژگی metageneration هر زمان که تغییری در فراداده شیء ایجاد شود، افزایش می‌یابد. برای اشیاء جدید، مقدار metageneration 1 است.

نود جی اس

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.

پایتون

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 (!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.");
}

پایتون

# 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

دانلود، تبدیل و آپلود فایل

در برخی موارد، ممکن است دانلود فایل‌ها از Cloud Storage ضروری نباشد. با این حال، برای انجام کارهای فشرده مانند تولید تصویر بندانگشتی از فایلی که در Cloud Storage ذخیره شده است، باید فایل‌ها را در نمونه توابع - یعنی ماشین مجازی که کد شما را اجرا می‌کند - دانلود کنید.

با استفاده از Cloud Functions به همراه برنامه‌های پردازش تصویر مانند sharp برای Node.js و Pillow برای پایتون، می‌توانید روی فایل‌های تصویری گرافیکی دستکاری انجام دهید. در زیر مثالی از نحوه ایجاد تصویر بندانگشتی برای یک فایل تصویری آپلود شده آمده است:

نود جی اس

/**
 * 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!");
});

فایل را در یک دایرکتوری موقت در نمونه Cloud Functions خود دانلود کنید. در این مکان، می‌توانید فایل را در صورت نیاز پردازش کرده و سپس در Cloud Storage بارگذاری کنید. هنگام انجام وظایف ناهمزمان، مطمئن شوید که یک promise جاوا اسکریپت را در callback خود برمی‌گردانید.

پایتون

@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")

این کد یک تصویر کوچک ۲۰۰x۲۰۰ برای تصویر ذخیره شده در یک دایرکتوری موقت ایجاد می‌کند، سپس آن را دوباره به Cloud Storage آپلود می‌کند.