إدارة الدوال

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

نشر الدوال

لنشر الدوال، شغِّل أمر واجهة سطر الأوامر في Firebase:

firebase deploy --only functions

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

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

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

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

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

حذف الدوال

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

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

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

يتيح حذف الدوال الواضحة في واجهة سطر الأوامر لمنصة 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 المصدر ويزيل من إنتاج أي وظائف تمت إزالتها من الملف.

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

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

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

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

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

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

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

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');

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تحديد إصدار Node.js

تتيح حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بوظائف السحابة الإلكترونية إمكانية اختيار وقت تشغيل 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 في 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 الذي تم إنشاؤه في دليل functions/ أثناء عملية الإعداد. على سبيل المثال، في حال الترقية من الإصدار 16 إلى الإصدار 18، يجب أن يبدو الإدخال على النحو التالي: "engines": {"node": "18"}
4. يمكنك اختياريًا اختبار التغييرات باستخدام مجموعة المحاكيات المحلية من Firebase.
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 في 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 التي تم تقديمها في حزمة تطوير البرامج (SDK) لمنصة Firebase للإصدار 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 دقائق. يتوافق مقدار الذاكرة الممنوحة للدالة مع وحدة المعالجة المركزية (CPU) المخصّصة للدالة، كما هو موضّح في قائمة القيم الصالحة التالية للسمة memory:

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

لضبط تخصيص الذاكرة وانتهاء المهلة في Google Cloud Console:

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