إدارة الدوال (الجيل الأول)

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

نشر الدوال

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

firebase deploy --only functions

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

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

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

للاطّلاع على القائمة الكاملة للأوامر المتاحة، يُرجى الرجوع إلى مرجع Firebase CLI.

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

حذف الدوال

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

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

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

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

حذف جميع الدوال التي تطابق الاسم المحدّد في جميع المناطق:
```
firebase functions:delete FUNCTION-1_NAME
```
حذف دالة محدّدة قيد التشغيل في منطقة غير تلقائية:
```
firebase functions:delete FUNCTION-1_NAME --region REGION_NAME
```

حذف أكثر من دالة واحدة:

firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

حذف مجموعة دوال محدّدة:
```
firebase functions:delete GROUP_NAME
```

تجاهُل طلب التأكيد:

firebase functions:delete FUNCTION-1_NAME --force

باستخدام الحذف الضمني للدوال، يحلّل الأمر firebase deploy المصدر ويزيل من مرحلة الإنتاج أي دوال تمت إزالتها من الملف.

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

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

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

لإعادة تسمية دالة، أنشئ إصدارًا جديدًا من الدالة في المصدر باستخدام الاسم الجديد، ثم شغِّل أمرَي نشر منفصلَين. ينشر الأمر الأول الدالة المُسمّاة حديثًا، ويزيل الأمر الثاني الإصدار الذي تم نشره سابقًا. على سبيل المثال، إذا كان لديك دالة 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

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

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

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

على سبيل المثال، إذا كان لديك دالة باسم 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 فقط. لتجنُّب الأخطاء، غيِّر نوع مشغّل دالة باتّباع هذا الإجراء:

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

على سبيل المثال، إذا كان لديك دالة 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 خيارات وقت التشغيل التي تم ضبطها في الرمز مع إعدادات الإصدار المنشور حاليًا من الدالة حسب الأولوية التالية:

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

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

ضبط إصدار Node.js

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

Node.js 22
Node.js 20
Node.js 18 (تم إيقافه)

اطّلِع على جدول الدعم للحصول على معلومات مهمة بشأن الدعم المستمر لهذه الإصدارات من Node.js.

لضبط إصدار Node.js، اتّبِع الخطوات التالية:

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

  "engines": {"node": "22"}

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

  {
    "functions": {
      "runtime": "nodejs22"
    }
  }

تفضّل واجهة سطر الأوامر (CLI) القيمة التي تم ضبطها في firebase.json على أي قيمة أو نطاق تضبطه بشكل منفصل في package.json.

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

لترقية وقت تشغيل Node.js، اتّبِع الخطوات التالية:

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

اختيار نظام وحدات Node.js

نظام الوحدات التلقائي في Node.js هو CommonJS (CJS)، ولكن إصدارات Node.js الحالية تتيح أيضًا وحدات ECMAScript (ESM). Cloud Functions يدعم كلا النظامَين.

تلقائيًا، تستخدم الدوال CommonJS. ما يعني أنّ عمليات الاستيراد والتصدير تبدو على النحو التالي:

const functions = require("firebase-functions/v1");

exports.helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

لاستخدام ESM بدلاً من ذلك، اضبط الحقل "type": "module" في ملف package.json :

  {
   ...
   "type": "module",
   ...
  }

بعد ضبط هذا الخيار، استخدِم بنية import وexport في ESM:

import functions from "firebase-functions/v1";

export const helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

يتوافق النظامان معًا بشكل كامل. يمكنك اختيار النظام الذي يناسب مشروعك بشكل أفضل. تعرَّف على مزيد من المعلومات في مستندات Node.js عن الوحدات.

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

تلقائيًا، تحجِّم 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.

ضبط حساب خدمة

يملك حساب الخدمة التلقائي لدوال الجيل الأول، PROJECT_ID@appspot.gserviceaccount.com (يُطلق عليه اسم App Engine default service account) مجموعة واسعة من الأذونات التي تتيح لك التفاعل مع خدمات Firebase وGoogle Cloud الأخرى.

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

const functions = require("firebase-functions/v1");

exports.helloWorld = functions
    .runWith({
        // This function doesn't access other Firebase project resources, so it uses a limited service account.
        serviceAccount:
            "my-limited-access-sa@", // or prefer the full form: "my-limited-access-sa@my-project.iam.gserviceaccount.com"
    })
    .https.onRequest((request, response) => {
        response.send("Hello from Firebase!");
    });

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

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

لضبط تخصيص الذاكرة والمهلة في رمز مصدر الدوال، استخدِم الـ runWith مَعلمة التي تم طرحها في Firebase SDK لـ Cloud Functions 2.0.0. يقبل خيار وقت التشغيل هذا عنصر JSON يتوافق مع RuntimeOptions الواجهة، التي تحدّد قيم timeoutSeconds و memory. على سبيل المثال، تستخدم دالة التخزين هذه غيغابايت واحدة من الذاكرة وتنتهي مهلتها بعد 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، اتّبِع الخطوات التالية:

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