ربط تطبيقك بمحاكي Cloud Functions

قبل ربط تطبيقك بمحاكي Cloud Functions، تأكَّد من فهم سير عمل Firebase Local Emulator Suite بشكل عام، ومن تثبيت وإعداد Local Emulator Suite ومراجعة أوامر واجهة سطر الأوامر.

اختيار مشروع Firebase

يحاكي Firebase Local Emulator Suite المنتجات لمشروع Firebase واحد.

لاختيار المشروع الذي تريد استخدامه، قبل بدء المحاكيات، نفِّذ الأمر firebase use في واجهة سطر الأوامر في دليل العمل. أو يمكنك تمرير العلامة --project إلى كل أمر من أوامر المحاكي.

يتيح Local Emulator Suite محاكاة مشاريع Firebase الحقيقية والمشاريع التجريبية.

نوع المشروع الميزات الاستخدام مع المحاكيات
ريال

مشروع Firebase الحقيقي هو مشروع أنشأته وأعددته (على الأرجح من خلال وحدة تحكّم Firebase).

تحتوي المشاريع الحقيقية على موارد نشطة، مثل مثيلات قواعد البيانات أو حِزم التخزين أو الدوال أو أي موارد أخرى تم إعدادها لمشروع Firebase هذا.

عند العمل على مشاريع Firebase حقيقية، يمكنك تشغيل المحاكيات لأي من المنتجات المتوافقة أو جميعها.

بالنسبة إلى أي منتجات لا تحاكيها، ستتفاعل تطبيقاتك والرمز البرمجي مع المورد المباشر (مثيل قاعدة البيانات، حزمة التخزين، الدالة، وما إلى ذلك).

تجريبي

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

تحتوي أرقام تعريف المشاريع التجريبية على البادئة demo-.

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

ننصحك باستخدام المشاريع التجريبية كلما أمكن ذلك. تتضمّن المزايا ما يلي:

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

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

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

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

إعداد بيئة اختبار محلية

إذا كانت الدوال تعتمد على إعدادات البيئة المستندة إلى dotenv، يمكنك محاكاة هذا السلوك في بيئة الاختبار المحلية.

عند استخدام محاكي Cloud Functions محلي، يمكنك إلغاء متغيرات البيئة لمشروعك من خلال إعداد ملف .env.local. يكون لمحتوى .env.local الأولوية على .env وملف .env الخاص بالمشروع.

على سبيل المثال، يمكن أن يتضمّن المشروع هذه الملفات الثلاثة التي تحتوي على قيم مختلفة قليلاً للتطوير والاختبار المحلي:

.env .env.dev .env.local

PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

عند بدء تشغيل المحاكي في السياق المحلي، يقوم المحاكي بتحميل متغيرات البيئة كما هو موضح:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

الأسرار وبيانات الاعتماد في محاكي Cloud Functions

يتيح محاكي Cloud Functions استخدام الرموز السرية لتخزين معلومات الإعدادات الحساسة والوصول إليها. يحاول المحاكي تلقائيًا الوصول إلى بيانات الاعتماد السرية في الإصدار العلني باستخدام بيانات الاعتماد التلقائية للتطبيق. In certain situations like CI environments, the emulator might fail to access secret values due to permission restrictions.

على غرار دعم محاكي Cloud Functions لمتغيرات البيئة، يمكنك تجاوز قيم البيانات السرية من خلال إعداد ملف .secret.local. ويسهّل ذلك عليك اختبار الدوال محليًا، خاصةً إذا لم يكن لديك إذن الوصول إلى القيمة السرية.

ما هي الأدوات الأخرى المتاحة لاختبار Cloud Functions؟

يتم استكمال محاكي Cloud Functions بأدوات أخرى للنماذج الأولية والاختبار:

  • واجهة Cloud Functions التي تتيح إنشاء النماذج الأولية وتطوير الدوال التفاعلية والتكرارية تستخدم واجهة الأوامر محاكي Cloud Functions مع واجهة REPL للتطوير. لا يتوفّر أي تكامل مع محاكيات Cloud Firestore أو Realtime Database. باستخدام واجهة الأوامر، يمكنك محاكاة البيانات وإجراء استدعاءات الدوال لمحاكاة التفاعل مع المنتجات التي لا يتيحها Local Emulator Suite حاليًا: "إحصاءات Google" و"الإعداد عن بُعد" وCrashlytics.
  • حزمة تطوير البرامج (SDK) لاختبار Firebase في Cloud Functions، وهي إطار عمل Node.js مع mocha لتطوير الدوال في الواقع، توفّر حزمة SDK لاختبار Cloud Functions الأتمتة فوق واجهة Cloud Functions.

يمكنك العثور على مزيد من المعلومات حول واجهة Cloud Functions وحزمة تطوير البرامج (SDK) لاختبار Cloud Functions في اختبار الدوال بشكل تفاعلي واختبار الوحدات في Cloud Functions.

أوجه الاختلاف بين محاكي Cloud Functions والإنتاج

يُعدّ محاكي Cloud Functions قريبًا إلى حدّ كبير من بيئة التشغيل الفعلي في معظم حالات الاستخدام. لقد بذلنا جهدًا كبيرًا لضمان أن يكون كل شيء في بيئة تشغيل Node أقرب ما يكون إلى بيئة الإنتاج. ومع ذلك، لا يحاكي المحاكي بيئة التشغيل الفعلي الكاملة في حاويات، لذا على الرغم من أنّ رمز الدالة سيتم تنفيذه بشكل واقعي، ستختلف الجوانب الأخرى لبيئتك (مثل الملفات المحلية والسلوك بعد تعطُّل الدوال وما إلى ذلك).

Cloud IAM

لا تحاول "مجموعة أدوات المحاكاة" في Firebase تكرار أو اتّباع أي سلوك مرتبط بإدارة الهوية وإمكانية الوصول (IAM) للتشغيل. تلتزم المحاكيات بقواعد أمان Firebase المقدَّمة، ولكن في الحالات التي يتم فيها استخدام "إدارة الهوية وإمكانية الوصول" عادةً، على سبيل المثال لضبط حساب خدمة استدعاء Cloud Functions وبالتالي الأذونات، لا يمكن ضبط المحاكي وسيستخدم الحساب المتاح عالميًا على جهاز المطوّر، على غرار تشغيل نص برمجي محلي مباشرةً.

القيود المفروضة على الذاكرة والمعالج

لا يفرض المحاكي قيودًا على الذاكرة أو المعالج لدوالك. ومع ذلك، يتيح المحاكي استخدام وظائف المهلة من خلال وسيطة وقت التشغيل timeoutSeconds.

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

التخطيط للاختلافات في البيئات المحلية وبيئات التشغيل الفعلي

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

يُرجى العِلم أنّ بيئتك المحلية لتطوير Cloud Functions قد تختلف عن بيئة التشغيل الفعلي في Google:

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

  • Similarly, built-in utilities (e.g., shell commands like ls, mkdir) may differ from versions available in production, especially if you're developing in a non-Linux environment (e.g., macOS). يمكنك معالجة هذه المشكلة باستخدام بدائل Node-only للأوامر الأصلية، أو عن طريق إنشاء ثنائيات Linux لتجميعها مع عملية النشر.

جارٍ إعادة المحاولة

لا تتيح محاكاة Cloud Functions إعادة محاولة تنفيذ الدوال في حال تعذّر تنفيذها.

ما هي الخطوات التالية؟