مشغِّلات 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 وموقع الدالة إلى زيادة وقت استجابة الشبكة بشكل كبير. لتحسين الأداء، ننصحك بتحديد موقع الدالة عند الضرورة.

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