مشغّلات Cloud Storage (الجيل الأول)

يمكنك تفعيل دالة استجابةً لتحميل الملفات والمجلدات أو تعديلها أو حذفها في Cloud Storage.

تستند الأمثلة في هذه الصفحة إلى نموذج دالة يتم تشغيلها عند تحميل ملفات الصور إلى Cloud Storage. توضّح هذه الدالة النموذجية كيفية الوصول إلى سمات الأحداث، وكيفية تنزيل ملف إلى مثيل Cloud Functions، وأساسيات أخرى للتعامل مع أحداث Cloud Storage.

لمزيد من الأمثلة على حالات الاستخدام، يُرجى الاطّلاع على ما الذي يمكنني فعله باستخدام Cloud Functions؟

تفعيل دالة عند إجراء تغييرات على Cloud Storage

استخدِم functions.storage لإنشاء دالة تعالج أحداث Cloud Storage. بناءً على ما إذا كنت تريد تحديد نطاق الدالة على حزمة Cloud Storage معيّنة أو استخدام الحزمة التلقائية، استخدِم أحد الخيارات التالية:

على سبيل المثال، يقتصر نموذج أداة إنشاء الصور المصغّرة على الحزمة التلقائية للمشروع:

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

يتيح Cloud Storage الأحداث التالية:

  • onArchive يتم إرسالها فقط عندما يكون الدلو قد فعّل تحديد إصدارات العناصر. يشير هذا الحدث إلى أنّ النسخة المباشرة من عنصر أصبحت نسخة مؤرشفة، إما لأنّها تمت أرشفتها أو لأنّه تم استبدالها من خلال تحميل عنصر يحمل الاسم نفسه.
  • 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.

يستخدم نموذج إنشاء الصور المصغّرة بعض هذه السمات لرصد حالات الخروج التي تعرض فيها الدالة ما يلي:

// 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.');
}

تنزيل ملف وتحويله وتحميله

في بعض الحالات، قد لا يكون من الضروري تنزيل الملفات من 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 { 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'));

استخدِم 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!");

تنشئ هذه التعليمة البرمجية صورة مصغّرة بحجم 200x200 للصورة المحفوظة في دليل مؤقت، ثم تحمّلها مرة أخرى إلى Cloud Storage.

استكشاف المزيد من الأمثلة

تشمل الأمثلة الإضافية على وظائف تحويل الوسائط الشائعة تحويل ترميز الصور والإشراف على المحتوى واستخراج بيانات EXIF الوصفية. تتوفّر القائمة الكاملة للأمثلة على GitHub.