إدارة الوظائف

يمكنك نشر الدوال وحذفها وتعديلها باستخدام Firebase أوامر سطر الأوامر أو من خلال ضبط خيارات وقت التشغيل في رمز مصدر الدوال.

دوال النشر

لنشر الدوال، عليك تشغيل الأمر Firebase CLI:

firebase deploy --only functions

ينشر واجهة سطر الأوامر Firebase تلقائيًا جميع الدوال المصدر في نفس الوقت. إذا كان مشروعك يحتوي على أكثر من 5 دوال، ننصحك باستخدام العلامة --only مع أسماء دوال معيّنة لنشر الدوال التي حرّرتها فقط. نشر دوال محددة فإن ذلك يؤدي إلى تسريع عملية النشر ويساعدك على تجنب الوقوع في حصص النشر. على سبيل المثال:

firebase deploy --only functions:addMessage,functions:makeUppercase

عند نشر أعداد كبيرة من الدوال، قد تتجاوز حصة معيارية وتلقى رسائل خطأ HTTP 429 أو 500. لحل المشكلة فإن ذلك، يؤدي إلى نشر الدوال في مجموعات مكونة من 10 أشخاص أو أقل.

يمكنك الاطّلاع على مرجع واجهة سطر الأوامر Firebase للحصول على قائمة كاملة بالسمات المتاحة الأوامر.

يبحث Firebase CLI تلقائيًا في مجلد functions/ عن رمز المصدر. يمكنك تنظيم الدوال إذا كنت تفضّل ذلك. في قواعد رموز برمجية أو مجموعات متعددة من الملفات.

حذف الدوالّ

يمكنك حذف الدوالّ التي تم نشرها سابقًا بالطُرق التالية:

• بشكل صريح في واجهة سطر الأوامر Firebase مع functions:delete
• بشكل صريح في وحدة تحكّم Google Cloud.
• بشكل ضمني عن طريق إزالة الدالة من المصدر قبل نشرها

تطلب منك جميع عمليات الحذف confirm قبل إزالة الدالة من مرحلة الإنتاج.

يتيح حذف الدالة الفاضح في واجهة سطر الأوامر Firebase استخدام الوسيطات المتعددة. بالإضافة إلى الدوال وتسمح لك بتحديد دالة تعمل في منطقة معينة. يمكنك أيضًا إلغاء طلب التأكيد.

# Delete all functions that match the specified name in all regions.
firebase functions:delete myFunction

# Delete a specified function running in a specific region.
firebase functions:delete myFunction --region us-east-1

# Delete more than one function
firebase functions:delete myFunction myOtherFunction

# Delete a specified functions group.
firebase functions:delete groupA

# Bypass the confirmation prompt.
firebase functions:delete myFunction --force

من خلال ميزة حذف الدوال الضمنية، تُحلِّل firebase deploy مصدرك ويُزال من الإصدار العلني أي دوال تمّت إزالتها من الملف.

تعديل اسم الدالة أو منطقتها أو عامل تشغيلها

إذا كنت تقوم بإعادة تسمية أو تغيير المناطق أو تشغيل الدوال التي لمعالجة حركة بيانات الإنتاج، يمكنك اتّباع الخطوات الواردة في هذا القسم لتجنّب فقدان الأحداث أثناء التعديل. قبل اتباع هذه الخطوات، تأكد أولاً من أن تكون الدالة idempoent، (مثبّتة تلقائيًا)، لأنّ سيتم تشغيل كل من الإصدارين الجديد والقديم من الدالة على نفس الوقت أثناء التغيير.

إعادة تسمية دالة

لإعادة تسمية دالة، أنشئ نسخة جديدة تمت إعادة تسميتها للدالة في المستند المصدر. ثم تشغيل أمرين منفصلين للنشر. ينشر الأمر الأول الدالة المُسمّاة حديثًا، ويزيل الأمر الثاني الإصدار الذي تم نشره سابقًا. على سبيل المثال، إذا كانت لديك دالة Node.js يُسمى webhook وتريد إلى webhookNew، راجع الرمز على النحو التالي:

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

// after
const functions = require('firebase-functions/v1');

exports.webhookNew = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

بعد ذلك، شغّل الأوامر التالية لنشر الدالة الجديدة:

# Deploy new function called webhookNew
firebase deploy --only functions:webhookNew

# Wait until deployment is done; now both webhookNew and webhook are running

# Delete webhook
firebase functions:delete webhook

تغيير منطقة أو مناطق الدالة

إذا كنت تغيّر المناطق المحدّدة لسمة تعالج الزيارات في قناة الإصدار العلني، يمكنك منع فقدان الأحداث من خلال اتّباع الخطوات التالية بالترتيب:

1. أعد تسمية الدالة، وغيّر منطقتها أو مناطقها كما هو مطلوب.
2. يمكنك نشر الدالة التي تمت إعادة تسميتها، ما يؤدي إلى تشغيل الرمز البرمجي نفسه مؤقتًا في كلتا مجموعتَي المناطق.
3. احذف الدالة السابقة.

على سبيل المثال، إذا كانت لديك دالة يُسمى webhook ومتوفر حاليًا منطقة الدوال التلقائية في us-central1، وتريد نقلها إلى asia-northeast1، يجب أولاً تعديل رمز المصدر لإعادة تسمية وتنقيح المنطقة.

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

// after
const functions = require('firebase-functions/v1');

exports.webhookAsia = functions
    .region('asia-northeast1')
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

بعد ذلك، يمكنك نشر التطبيق من خلال تنفيذ:

firebase deploy --only functions:webhookAsia

هناك الآن دالتَان متطابقتان قيد التشغيل: يتم تشغيل webhook في us-central1، ويتم تشغيل webhookAsia في asia-northeast1.

بعد ذلك، يمكنك حذف webhook:

firebase functions:delete webhook

الآن، هناك دالة واحدة فقط - webhookAsia، وهي قيد التشغيل في asia-northeast1.

تغيير نوع عامل تشغيل الدالة

أثناء تطوير عملية نشر Cloud Functions for Firebase بمرور الوقت، قد تحتاج إلى تغيير نوع عامل تشغيل الدالة لأسباب مختلفة. على سبيل المثال، قد تريد التغيير من نوع من أحداث Firebase Realtime Database أو Cloud Firestore إلى نوع آخر.

لا يمكن تغيير نوع حدث الدالة فقط من خلال تغيير رمز المصدر وتشغيل firebase deploy. لتجنُّب الأخطاء، غيِّر نوع عامل تشغيل الدالة باتّباع الإجراء التالي:

1. عدِّل رمز المصدر لتضمين دالة جديدة بنوع المشغِّل المطلوب.
2. نشر الدالة، ما يؤدي إلى تشغيل الدالتَين القديمة والجديدة مؤقتًا
3. احذف الدالة القديمة من عملية الإنتاج صراحةً باستخدام واجهة سطر الأوامر Firebase.

على سبيل المثال، إذا كانت لديك دالة Node.js باسم objectChanged تتضمّن نوع الحدث التقليدي onChange وأردت تغييره إلى onFinalize، عليك أولاً إعادة تسمية الدالة وتعديلها لتضمين نوع الحدث onFinalize.

// before
const functions = require('firebase-functions/v1');

exports.objectChanged = functions.storage.object().onChange((object) => {
    return console.log('File name is: ', object.name);
});

// after
const functions = require('firebase-functions/v1');

exports.objectFinalized = functions.storage.object().onFinalize((object) => {
    return console.log('File name is: ', object.name);
});

بعد ذلك، نفِّذ الأوامر التالية لإنشاء الدالة الجديدة أولاً، قبل حذف الدالة القديمة:

# Create new function objectFinalized
firebase deploy --only functions:objectFinalized

# Wait until deployment is done; now both objectChanged and objectFinalized are running

# Delete objectChanged
firebase functions:delete objectChanged

ضبط خيارات وقت التشغيل

يتيح لك Cloud Functions for Firebase تحديد خيارات بيئة التشغيل، مثل Node.js. إصدار وقت التشغيل ومهلة كل دالة، وتخصيص الذاكرة، والحد الأدنى/الحد الأقصى لمثيلات الوظائف.

كإحدى أفضل الممارسات، يجب ضبط هذه الخيارات (باستثناء إصدار Node.js) على كائن تهيئة داخل رمز الدالة. هذا النمط RuntimeOptions هو مصدر الحقيقة لخيارات وقت تشغيل الدالة، إلغاء الخيارات التي تم ضبطها باستخدام أي طريقة أخرى (مثل استخدام "وحدة تحكُّم Google Cloud" أو gcloud CLI).

إذا كان سير عمل التطوير يتضمّن ضبط خيارات وقت التشغيل يدويًا من خلال Google Cloud Console أو واجهة سطر أوامر gcloud CLI ولا تريد أن يتم تجاوز هذه القيم في كل عملية نشر، اضبط الخيار preserveExternalChanges على true. عند ضبط هذا الخيار على true، تدمج Firebase خيارات وقت التشغيل التي تم ضبطها في الرمز البرمجي مع إعدادات الإصدار المنشور حاليًا من الدالة باستخدام الأولوية التالية:

1. يتم ضبط الخيار في رمز الدوال: إلغاء التغييرات الخارجية.
2. تم ضبط الخيار على RESET_VALUE في رمز الدوال: إلغاء التغييرات الخارجية باستخدام القيمة التلقائية.
3. لم يتم ضبط الخيار في رمز الدوال، ولكن تم ضبطه في دالة منشورة حاليًا: استخدِم الخيار المحدّد في الدالة المنشورة.

لا يُنصح باستخدام الخيار preserveExternalChanges: true في معظم السيناريوهات لأنّه لن يعود الرمز المصدر الكامل للحقائق حول خيارات وقت التشغيل لوظائفك. في حال استخدامه، تحقَّق من وحدة تحكّم Google Cloud أو استخدِم واجهة سطر الأوامر لعرض التهيئة الكاملة للدالة.

ضبط إصدار Node.js

تتيح حزمة تطوير البرامج (SDK) Firebase للنطاق Cloud Functions اختيار وقت تشغيل Node.js. يمكنك اختيار تنفيذ جميع الدوال في مشروع حصريًا في بيئة التشغيل. بيئة تتوافق مع أحد إصدارات Node.js المتوافقة هذه:

• Node.js 20 (إصدار تجريبي)
• Node.js 18
• Node.js 16
• Node.js 14

لضبط إصدار Node.js:

يمكنك ضبط الإصدار في الحقل "engines" في package.json. ملف تم إنشاؤه في دليل functions/ أثناء الإعداد. على سبيل المثال، لاستخدام الإصدار 18 فقط، عدِّل هذا السطر في package.json:

  "engines": {"node": "18"}

إذا كنت تستخدم مدير حِزم Yarn أو كانت لديك متطلبات محدّدة أخرى لمحاولة حقل engines، يمكنك ضبط وقت التشغيل لحزمة SDK Firebase لنظام التشغيل Cloud Functions في firebase.json بدلاً من ذلك:

  {
    "functions": {
      "runtime": "nodejs18" // or nodejs14, nodejs16 or nodejs20
    }
  }

يستخدم واجهة سطر الأوامر القيمة المعينة في firebase.json لصالح أي قيمة أو نطاق تضبطه بشكل منفصل في package.json.

ترقية وقت تشغيل Node.js

لترقية وقت تشغيل Node.js:

1. تأكَّد من أنّ مشروعك يستخدم خطة أسعار Blaze.
2. يُرجى التأكّد من استخدام الإصدار 11.18.0 من واجهة سطر الأوامر Firebase أو إصدار أحدث.
3. غيِّر قيمة engines في ملف package.json الذي تم إنشاؤه في directory functions/ أثناء الإعداد. على سبيل المثال، إذا كنت تقوم بالترقية من الإصدار 16 إلى الإصدار 18، من المفترض أن تظهر بالشكل التالي: "engines": {"node": "18"}
4. يمكنك اختياريًا اختبار التغييرات باستخدام Firebase Local Emulator Suite
5. إعادة نشر جميع الدوال.

التحكّم في سلوك التحجيم

بشكلٍ تلقائي، يعمل Cloud Functions for Firebase على زيادة عدد مثيلات الجري استنادًا إلى عدد الطلبات الواردة، ومن المحتمل أن يتم خفضها إلى صفر في حالات انخفاض عدد الزيارات. ومع ذلك، إذا كان تطبيقك يتطلب أسعارًا مخفَّضة وقت الاستجابة وأردت تقليل عدد عمليات التشغيل على البارد، يمكنك تغيير السلوك الافتراضي عن طريق تحديد حد أدنى لعدد مثيلات الحاوية التي سيتم دافئ وجاهزًا لتقديم الطلبات.

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

تقليل عدد عمليات التشغيل من وضع غير نشط

لضبط الحد الأدنى لعدد نُسخ الدالة في رمز المصدر، استخدِم الإجراء runWith . تقبل هذه الطريقة كائن JSON يتوافق مع RuntimeOptions التي تحدد قيمة minInstances. على سبيل المثال: تضبط هذه الدالة 5 مثيلات على الأقل للحفاظ على الدفء:

exports.getAutocompleteResponse = functions
    .runWith({
      // Keep 5 instances warm for this latency-critical function
      minInstances: 5,
    })
    .https.onCall((data, context) => {
      // Autocomplete a user's search term
    });
index.js

إليك بعض النقاط التي يجب مراعاتها عند ضبط قيمة في السمة minInstances:

• إذا غيّر Cloud Functions for Firebase مستوى أداء تطبيقك بدرجة أكبر من minInstances، فستواجه بداية باردة لكل مثيل أعلى من هذا الحد.
• ويُرجى العِلم بأنّ عمليات البدء الباردة لها أشد تأثير في التطبيقات التي تشهد حركة مرور حادة. إذا كان يشهد تطبيقك زيادة كبيرة في عدد الزيارات، وقد ضبطت قيمة minInstances عالية بما يكفي ينخفض عدد مرات التشغيل على البارد عند كل زيادة في عدد الزيارات، وستلاحظ زيادة كبيرة زمن انتقال منخفض بالنسبة إلى التطبيقات التي تتلقّى زيارات مستمرة، من غير المرجّح أن تؤثر عمليات التشغيل على البارد بشكل كبير في الأداء.

• قد يكون من المنطقي ضبط الحد الأدنى لعدد النُسخ في بيئات الإنتاج، ولكن ينبغي عادةً تجنُّب ذلك في بيئات الاختبار. للانتقال إلى الصفر في اختبار المشروع مع الاستمرار في تقليل عمليات التشغيل على البارد في مشروع الإنتاج، يمكن ضبط minInstances استنادًا إلى متغير البيئة FIREBASE_CONFIG:

  // Get Firebase project id from `FIREBASE_CONFIG` environment variable
  const envProjectId = JSON.parse(process.env.FIREBASE_CONFIG).projectId;
  
  exports.renderProfilePage = functions
      .runWith({
        // Keep 5 instances warm for this latency-critical function
        // in production only. Default to 0 for test projects.
        minInstances: envProjectId === "my-production-project" ? 5 : 0,
      })
      .https.onRequest((req, res) => {
        // render some html
      });
  index.js
  

الحد من الحد الأقصى لعدد النُسخ لدالة

لضبط الحد الأقصى لعدد المثيلات في رمز المصدر للدالة، استخدِم الأسلوب runWith . تقبل هذه الطريقة كائن JSON يتوافق مع RuntimeOptions التي تحدد لـ maxInstances. على سبيل المثال، تضبط هذه الدالة حدًا أقصى على 100. الحالات التي لا تربك فيها قاعدة بيانات افتراضية قديمة:

exports.mirrorOrdersToLegacyDatabase = functions
    .runWith({
      // Legacy database only supports 100 simultaneous connections
      maxInstances: 100,
    })
    .firestore.document("orders/{orderId}")
    .onWrite((change, context) => {
      // Connect to legacy database
    });
index.js

في حال زيادة حجم دالة HTTP إلى الحد الأقصى maxInstances، يتم تنفيذ الطلبات الجديدة تم وضعه في قائمة الانتظار لمدة 30 ثانية ثم تم رفضه مع رمز الاستجابة 429 Too Many Requests في حال عدم توفّر أي مثيل بحلول ذلك الوقت.

لمزيد من المعلومات عن أفضل الممارسات لاستخدام إعدادات الحد الأقصى لعدد النُسخ، اطّلِع على هذه أفضل الممارسات لاستخدام maxInstances.

ضبط مهلة تخصيص الذاكرة

في بعض الحالات، قد يكون للدوال متطلبات خاصة لمدة طويلة. قيمة أو تخصيص كبير من الذاكرة. يمكنك تعيين هذه القيم إما في Google Cloud Console أو في رمز المصدر الخاص بالدالة (Firebase فقط)

لضبط تخصيص الذاكرة ومهلة في رمز المصدر للدوال، استخدِم runWith تم تقديم معلَمة في Firebase SDK للإصدار 2.0.0 من Cloud Functions. يقبل خيار وقت التشغيل هذا كائن JSON متوافقًا مع واجهة RuntimeOptions التي تحدّد قيمتَي timeoutSeconds وmemory. على سبيل المثال، تستخدِم وظيفة التخزين هذه 1 غيغابايت من الذاكرة وتنتهي مهلته بعد 300 ثانية:

exports.convertLargeFile = functions
    .runWith({
      // Ensure the function has enough memory and time
      // to process large files
      timeoutSeconds: 300,
      memory: "1GB",
    })
    .storage.object()
    .onFinalize((object) => {
      // Do some complicated things that take a lot of memory and time
    });
index.js

الحد الأقصى لقيمة timeoutSeconds هو 540، أو 9 دقائق. تتوافق كمية الذاكرة الممنوحة لدالة مع وحدة المعالجة المركزية المخصّصة للدالة، كما هو موضّح بالتفصيل في قائمة القيم الصالحة memory:

• ‫128MB - 200 ميغاهرتز
• 256MB — 400 ميغاهرتز
• 512MB — 800 ميغاهرتز
• 1GB - ‫1.4 غيغاهرتز
• 2GB — 2.4 غيغاهرتز
• 4GB - ‫4.8 غيغاهرتز
• 8GB: 4.8 غيغاهرتز

لضبط إعدادات تخصيص الذاكرة والمهلة في وحدة تحكُّم Google Cloud، اتّبِع الخطوات التالية:

1. في وحدة تحكّم Google Google Cloud، اختَر Cloud Functions من القائمة على يمين الصفحة.
2. حدد دالة عن طريق النقر فوق اسمها في قائمة الدوال.
3. انقر على رمز تعديل في القائمة العلوية.
4. اختَر مساحة تخصيص ذاكرة من القائمة المنسدلة التي تحمل الاسم المساحة المخصّصة للذاكرة.
5. انقر على المزيد لعرض الخيارات المتقدّمة، وأدخِل عددًا من الثواني في مربّع نص المهلة.
6. انقر على حفظ لتعديل الدالة.