تشغيل الدوال على الجهاز

تتضمّن واجهة سطر أوامر Firebase محاكي Cloud Functions يمكنه محاكاة أنواع الدوال التالية:

  • دوال HTTPS
  • الدوال القابلة للاستدعاء
  • دوال قائمة انتظار المهام
  • الدوال التي تعمل في الخلفية ويتم تشغيلها من Firebase Authentication وRealtime Database وCloud Firestore وCloud Storage وتنبيهات Firebase المتوافقة وCloud Pub/Sub

يمكنك تشغيل الدوال محليًا لاختبارها قبل نشرها في بيئة الإنتاج.

تثبيت Firebase CLI

لاستخدام محاكي Cloud Functions، عليك أولاً تثبيت Firebase CLI:

npm install -g firebase-tools

لاستخدام المحاكي المحلي، يجب أن يعتمد Cloud Functions على:

  • الإصدار 8.0.0 من firebase-admin أو إصدار أحدث
  • الإصدار 3.0.0 من firebase-functions أو إصدار أحدث

إعداد بيانات اعتماد المشرف (اختياري)

إذا أردت أن تتفاعل اختبارات الدوال مع Google APIs أو Firebase APIs الأخرى من خلال مدير SDK في Firebase، قد تحتاج إلى إعداد بيانات اعتماد المشرف.

  • يحتوي المشغّلان Cloud Firestore وRealtime Database على بيانات اعتماد كافية، ولا يتطلّبان إعدادًا إضافيًا.
  • تتطلّب جميع واجهات برمجة التطبيقات الأخرى، بما في ذلك واجهات برمجة تطبيقات Firebase، مثل Authentication وFCM، أو واجهات Google APIs، مثل Cloud Translation أو Cloud Speech، خطوات الإعداد الموضّحة في هذا القسم. ينطبق ذلك سواء كنت تستخدم واجهة Cloud Functions أو firebase emulators:start.

لإعداد بيانات اعتماد المشرف للدوال التي تمت محاكاتها:

  1. افتح لوحة حسابات الخدمة في وحدة تحكّم Google Cloud.
  2. تأكَّد من اختيار حساب الخدمة التلقائي في App Engine، واستخدِم قائمة الخيارات على يسار الصفحة لاختيار إنشاء مفتاح.
  3. عندما يُطلب منك ذلك، اختَر JSON لنوع المفتاح، ثم انقر على إنشاء.

  4. اضبط بيانات الاعتماد التلقائية في Google لتوجيهها إلى المفتاح الذي تم تنزيله:

    نظام التشغيل Unix

    export GOOGLE_APPLICATION_CREDENTIALS="path/to/key.json"
firebase emulators:start

    Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path\to\key.json
firebase emulators:start

بعد إكمال هذه الخطوات، يمكن لاختبارات الدوال الوصول إلى Firebase و Google APIs باستخدام مدير SDK. على سبيل المثال، عند اختبار مُشغِّل Authentication، يمكن للدالة التي تمت محاكاتها استدعاء admin.auth().getUserByEmail(email).

إعداد ضبط الدوال (اختياري)

إذا كنت تستخدم متغيّرات إعداد الدوال المخصّصة، شغِّل أولاً الأمر للحصول على الإعدادات المخصّصة (شغِّل هذا الأمر ضمن دليل functions) في بيئتك المحلية:

firebase functions:config:get > .runtimeconfig.json
# If using Windows PowerShell, replace the above with:
# firebase functions:config:get | ac .runtimeconfig.json

تشغيل مجموعة أدوات المحاكاة

لتشغيل محاكي Cloud Functions، استخدِم الأمر emulators:start:

firebase emulators:start

سيبدأ الأمر emulators:start تشغيل المحاكيات لـ Cloud Functions وCloud Firestore و"قاعدة بيانات الوقت الفعلي" و"استضافة Firebase" استنادًا إلى المنتجات التي بدأتها في مشروع على جهاز المستخدم باستخدام firebase init. إذا أردت بدء محاكي معيّن، استخدِم العلامة --only:

firebase emulators:start --only functions

إذا أردت تشغيل حزمة اختبارية أو نص برمجي للاختبار بعد بدء تشغيل المحاكيات، استخدِم الأمر emulators:exec:

firebase emulators:exec "./my-test.sh"

بعد بدء التشغيل، يبث المحاكي السجلّات من دوالّك إلى نافذة المحطة الطرفية التي يتم تشغيله فيها. وتعرض جميع المخرجات من عبارات console.log() وconsole.info() وconsole.error() وconsole.warn() داخل الدوال.

يُرجى العِلم أنّ مخرجات المحاكي تحاكي نشر الدوال تلقائيًا في منطقة معيّنة (us-central1) قد لا تتطابق مع المنطقة التلقائية الفعلية لنشر الدوال في بيئة الإنتاج. يمكنك الاطّلاع على مواقع Cloud Functions الجغرافية لمزيد من المعلومات حول المناطق.

إعداد تطبيقك للتواصل مع المحاكيات

لإعداد تطبيقك للتفاعل مع المحاكيات، قد تحتاج إلى إجراء بعض الإعدادات الإضافية.

إعداد تطبيقك لاستخدام الدوال القابلة للاستدعاء

إذا كانت أنشطة النموذج الأوّلي والاختبار تتضمّن دوال خلفية قابلة للاستدعاء، اضبط التفاعل مع محاكي Cloud Functions for Firebase على النحو التالي:

Kotlin
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
Swift
Functions.functions().useEmulator(withHost: "localhost", port: 5001)
Unity
FirebaseFunctions functions = FirebaseFunctions.DefaultInstance;
// Connects to the Functions Emulator running on port 5001
functions.UseFunctionsEmulator("http://127.0.0.1:5001");

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);

Web

firebase.functions().useEmulator("127.0.0.1", 5001);

إعداد تطبيقك لمحاكاة وظائف HTTPS

سيتم عرض كل دالة HTTPS في الرمز البرمجي من المحاكي المحلي باستخدام تنسيق عنوان URL التالي:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

على سبيل المثال، سيتم عرض دالة helloWorld بسيطة مع منفذ المضيف والمنطقة التلقائيَين على:

https://localhost:5001/$PROJECT/us-central1/helloWorld

إعداد تطبيقك لمحاكاة وظائف قائمة انتظار المهام

يُعدّ المحاكي تلقائيًا قوائم انتظار المهام التي تتم محاكاتها استنادًا إلى تعريفات المشغّلات، ويعيد مدير SDK توجيه الطلبات المُدرَجة في قائمة الانتظار إلى المحاكي إذا رصد أنّه يعمل من خلال متغيّر البيئة CLOUD_TASKS_EMULATOR_HOST.

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

إعداد تطبيقك لمحاكاة الوظائف التي يتم تشغيلها في الخلفية

يتيح محاكي Cloud Functions استخدام الدوال التي يتم تشغيلها في الخلفية من المصادر التالية:

  • محاكي Realtime Database
  • محاكي Cloud Firestore
  • محاكي Authentication
  • محاكي Pub/Sub
  • محاكي تنبيهات Firebase

لتشغيل أحداث في الخلفية، يمكنك تعديل موارد الخلفية باستخدام Emulator Suite UI أو من خلال ربط تطبيقك أو رمز الاختبار بالمحاكيات باستخدام حزمة تطوير البرامج (SDK) لمنصتك.

اختبار معالِجات الأحداث المخصّصة التي تصدرها الإضافات

بالنسبة إلى الدوال التي تنفّذها لمعالجة أحداث Firebase Extensions المخصّصة باستخدام الإصدار 2 من Cloud Functions، يتم إقران محاكي Cloud Functions مع محاكي Eventarc لإتاحة مشغّلات Eventarc.

لاختبار معالِجات الأحداث المخصّصة للإضافات التي تُصدر أحداثًا، يجب تثبيت محاكيَي Cloud Functions وEventarc.

يضبط وقت تشغيل Cloud Functions متغيّر البيئة EVENTARC_EMULATOR على localhost:9299 في العملية الحالية إذا كان محاكي Eventarc قيد التشغيل. تتصل Firebase Admin SDKs تلقائيًا بمحاكي Eventarc عند ضبط متغيّر البيئة EVENTARC_EMULATOR. يمكنك تعديل المنفذ التلقائي كما هو موضّح في ضبط Local Emulator Suite.

عند ضبط متغيّرات البيئة بشكل صحيح، يرسل Firebase Admin SDK الأحداث تلقائيًا إلى محاكي Eventarc. بدوره، يُجري محاكي Eventarc مكالمة مرة أخرى مع محاكي Cloud Functions لتشغيل أي معالِجات مسجَّلة.

يمكنك الاطّلاع على سجلّات الدوال في Emulator Suite UI للحصول على تفاصيل حول تنفيذ المعالِج.

التفاعلات مع الخدمات الأخرى

تتضمّن مجموعة أدوات المحاكاة عدة برامج محاكاة تتيح اختبار التفاعلات بين المنتجات.

Cloud Firestore

إذا كانت لديك دوال تستخدم حزمة تطوير البرامج (SDK) لمشرف Firebase للكتابة في Cloud Firestore، سيتم إرسال عمليات الكتابة هذه إلى محاكي Cloud Firestore إذا كان قيد التشغيل. إذا تم تشغيل وظائف أخرى من خلال عمليات الكتابة هذه، سيتم تشغيلها في محاكي Cloud Functions.

Cloud Storage

إذا كانت لديك دوال تستخدم حزمة تطوير البرامج (SDK) لمشرف Firebase (الإصدار 9.7.0 أو إصدار أحدث) للكتابة في Cloud Storage، سيتم إرسال عمليات الكتابة هذه إلى محاكي Cloud Storage إذا كان قيد التشغيل. إذا تم تشغيل وظائف أخرى من خلال عمليات الكتابة هذه، سيتم تشغيلها في محاكي Cloud Functions.

Firebase Authentication

إذا كانت لديك دوال تستخدم مدير SDK في Firebase (الإصدار 9.3.0 أو إصدار أحدث) للكتابة في Firebase Authentication، سيتم إرسال عمليات الكتابة هذه إلى محاكي المصادقة إذا كان قيد التشغيل. إذا تم تشغيل وظائف أخرى من خلال عمليات الكتابة هذه، سيتم تشغيلها في محاكي Cloud Functions.

استضافة Firebase:

إذا كنت تستخدم Cloud Functions لإنشاء محتوى ديناميكي لـ Firebase Hosting، يستخدم firebase emulators:start دوال HTTP المحلية كخوادم وكيلة للاستضافة.

تنبيهات Firebase

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

  1. افتح علامة التبويب تنبيهات الحرائق. تعرض علامة التبويب هذه قائمة منسدلة تتضمّن أنواع التنبيهات التي لها مشغّلات مرتبطة بها (على سبيل المثال، إذا كان لديك مشغّل onNewFatalIssuePublished، سيتم عرض crashlytics.newFatalIssue).
  2. اختَر نوع التنبيه. تتم التعبئة التلقائية للنموذج بالقيم التلقائية، والتي يمكن تعديلها. يمكنك تعديل حقول الحدث (يتم استنتاج المعلومات الأخرى من حدث التنبيه أو استخدام قيم وهمية أو إنشاؤها عشوائيًا).
  3. انقر على إرسال تنبيه لإرسال تنبيه اصطناعي إلى محاكي الدوال، مع إتاحة التسجيل في التنبيهات في وحدة تحكّم Firebase (وكذلك في السجلات).

الخطوات التالية

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