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


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

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

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

تشغيل دالة عند التغييرات في 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 عددًا من سمات عناصر 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 عند معاودة الاتصال.

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

باستخدام دوال 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

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

الاطّلاع على المزيد من الأمثلة

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