مشغِّلات Cloud Storage

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

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

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

تشغيل دالة عند حدوث تغييرات في 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 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.
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 promises للتعامل مع العمليات الخارجية، مثل مَهمّات معالجة الصور المصغّرة في العينة، عليك أيضًا استيراد 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 Functions مع برامج معالجة الصور، مثل 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.