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