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

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

نشر الدوال

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

firebase deploy --only functions

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

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

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

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

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

حذف الدوال

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

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

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

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

  • لحذف جميع الدوال التي تتطابق مع الاسم المحدّد في جميع المناطق: 

    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

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

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

  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 أو gcloud CLI وكنت لا تريد أن يتم تجاهل هذه القيم في كل عملية نشر، اضبط الخيار preserveExternalChanges على true. عند ضبط هذا الخيار على true، تدمج Firebase خيارات وقت التشغيل المحدّدة في الرمز مع إعدادات الإصدار الحالي من الدالة الذي تم نشره، وذلك حسب الأولوية التالية:

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

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

ضبط إصدار Node.js

تتيح حزمة تطوير البرامج (SDK) الخاصة بـ 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، يمكنك ضبط وقت التشغيل لحزمة تطوير البرامج (SDK) الخاصة بـ Firebase في Cloud Functions ضمن firebase.json بدلاً من ذلك:

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

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

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

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

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

اختيار نظام وحدات 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",
   ...
  }

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

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

في ما يلي بعض الأمور التي يجب مراعاتها عند تحديد قيمة 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
    });

الحدّ الأقصى لعدد مثيلات الدالة

لضبط الحد الأقصى لعدد المثيلات في الرمز المصدر للدالة، استخدِم الطريقة 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
    });

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

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

ضبط حساب خدمة

يملك حساب الخدمة التلقائي للجيل الأول من الدوال، PROJECT_ID@appspot.gserviceaccount.com (المعروف باسم حساب الخدمة التلقائي في App Engine)، مجموعة كبيرة من الأذونات التي تتيح لك التفاعل مع خدمات 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 التي تم تقديمها في حزمة تطوير البرامج (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
    });

الحدّ الأقصى لقيمة 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 Cloud، انقر على Cloud Functions من القائمة اليمنى.
  2. اختَر دالة من خلال النقر على اسمها في قائمة الدوال.
  3. انقر على رمز تعديل في القائمة أعلى الصفحة.
  4. اختَر تخصيص ذاكرة من القائمة المنسدلة التي تحمل التصنيف الذاكرة المخصّصة.
  5. انقر على المزيد لعرض الخيارات المتقدّمة، وأدخِل عددًا من الثواني في مربّع النص المهلة.
  6. انقر على حفظ لتعديل الدالة.