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

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

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

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

تثبيت Firebase CLI

لاستخدام محاكي Cloud Functions، عليك أولاً تثبيت واجهة سطر أوامر Firebase:

npm install -g firebase-tools

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

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

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

إذا كنت تريد أن تتفاعل اختبارات الدوالّ مع واجهات برمجة تطبيقات Google أو غيرها من واجهات برمجة تطبيقات Firebase من خلال حزمة تطوير البرامج (SDK) الخاصة بمدير Firebase، قد تحتاج إلى إعداد بيانات اعتماد المشرف.

• تتوفّر لدى مشغّلَي التفعيل Cloud Firestore وRealtime Database بيانات اعتماد كافية، ولا يتطلّبان إعدادًا إضافيًا.
• تتطلّب جميع واجهات برمجة التطبيقات الأخرى، بما في ذلك واجهات برمجة تطبيقات Firebase، مثل Authentication وFCM أو واجهات برمجة تطبيقات Google، مثل Cloud Translation أو Cloud Speech، خطوات الإعداد الموضّحة في هذا القسم. ينطبق ذلك سواء كنت تستخدم Cloud Functions shell أو 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

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

ملاحظة: يُعيد المحاكي تحميل التغييرات التي تجريها على الرموز البرمجية أثناء جلسة نشطة تلقائيًا. إذا كان يجب تحويل الرمز البرمجي (TypeScript وReact)، احرص على إجراء ذلك قبل تشغيل المحاكي. يمكنك تشغيل أداة التحويل البرمجي في وضع المراقبة باستخدام أوامر مثل tsc -w لتحويل الرمز البرمجي وإعادة تحميله تلقائيًا أثناء الحفظ.

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

firebase emulators:start

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

firebase emulators:start --only functions

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

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

تجهيز تطبيقك للتواصل مع المحاكيات

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

تجهيز تطبيقك للدوالّ القابلة للاستدعاء

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

Kotlin+KTX

// 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)
MainActivity.kt

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);
MainActivity.java

Swift

Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
ViewController.swift

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

ملاحظة: Android فقط. قد تؤثر سياسات إعدادات أمان الشبكات في Android في طريقة تفاعل الرمز البرمجي مع محاكي Cloud Functions الذي يعرض البيانات محليًا عبر بروتوكول HTTP غير المشفَّر. بدءًا من Android 9 (المستوى 28 من واجهة برمجة التطبيقات)، يتم تلقائيًا إيقاف ميزة التواصل عبر نص واضح. يمكنك إعداد ملف network_security_config.xml لإضافة محاكي Cloud Functions إلى القائمة المسموح بها من أجل التطوير على المضيف المحلي. اطّلِع على مستندات مطوّري تطبيقات Android ذات الصلة.

تجهيز تطبيقك لمحاكاة وظائف HTTPS

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

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

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

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

تجهيز تطبيقك لمحاكاة وظائف قائمة انتظار المهام

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

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

تجهيز تطبيقك لمحاكاة الدوال التي يتم تشغيلها في الخلفية

يتيح محاكي 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 SDK تلقائيًا بمحاكي Eventarc عند ضبط متغيّر البيئة EVENTARC_EMULATOR. يمكنك تعديل المنفذ التلقائي كما هو موضّح في قسم الضبط Local Emulator Suite.

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

يمكنك الاطّلاع على سجلّات 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، سيتم إرسال عمليات الكتابة هذه إلى محاكي Auth إذا كان قيد التشغيل. إذا تم تنشيط المزيد من الدوالّ من خلال عمليات الكتابة هذه، سيتم تشغيلها في محاكي Cloud Functions.

استضافة Firebase

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

تنبيهات Firebase

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

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

التسجيل

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

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

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