عوامل التشغيل في Cloud Storage

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

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

للحصول على مزيد من الأمثلة حول حالات الاستخدام، يمكنك الاطّلاع على المقالة ماذا يمكنني أن أفعل باستخدام دوال Cloud؟

تشغيل دالة عند حدوث تغييرات في 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 لا يتم إرساله إلا عندما تعمل حزمة على تفعيل تحديد إصدارات العناصر. يشير هذا الحدث إلى أنّ النسخة المنشورة من أحد العناصر أصبحت نسخة مؤرشفة، إما لأنّه تمت أرشفتها أو لأنّه تم استبدالها من خلال تحميل عنصر يحمل الاسم نفسه.
• onDelete يتم إرساله عند حذف عنصر نهائيًا. ويشمل ذلك العناصر التي يتم استبدالها أو حذفها كجزء من إعدادات دورة حياة الحزمة. بالنسبة إلى الحِزم التي تم فيها تفعيل تحديد إصدارات العناصر، لا يتم إرسال هذه السمة عند أرشفة العنصر (راجِع onArchive)، حتى إذا كان يتم الأرشفة من خلال طريقة storage.objects.delete.
• onFinalize يتم إرساله عند إنشاء عنصر جديد (أو جيل جديد من عنصر حالي) في الحزمة بنجاح. وهذا يشمل نسخ عنصر حالي أو إعادة كتابته. ولا يؤدي تعذُّر التحميل إلى تشغيل هذا الحدث.
• onMetadataUpdate يتم إرساله عند تغيير البيانات الوصفية لعنصر حالي.

اضبط الحدث ضمن معالِج أحداث "on" كما هو موضّح أعلاه في "onFinalize".

الوصول إلى سمات عناصر Cloud Storage

تعرض "وظائف Cloud" عددًا من سمات عناصر 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. في هذا الموقع، يمكنك معالجة الملف حسب الحاجة ثم تحميله إلى Cloud Storage. عند تنفيذ مهام غير متزامنة، تأكد من عرض وعود JavaScript في معاودة الاتصال.

مثال: تحويل الصورة

باستخدام دوال Cloud مع برامج معالجة الصور مثل 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

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

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

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