ربط تطبيقك بمحاكي 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
• أمان أقوى، لأنّه إذا استدعى الرمز عن طريق الخطأ موارد غير محاكاة (في مرحلة الإنتاج)، لن يكون هناك أي احتمال لتغيير البيانات أو الاستخدام أو الفوترة
• دعم أفضل بلا إنترنت، لأنّه ليست هناك حاجة إلى الوصول إلى الإنترنت لتنزيل إعداد حزمة تطوير البرامج (SDK)

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

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

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

// 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

// 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

Functions.functions().useEmulator(withHost: "localhost", port: 5001)
ViewController.swift

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

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

إعداد تطبيقك لمحاكاة دوال 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 الأحداث المخصّصة باستخدام Cloud Functions الإصدار 2، يقترن محاكي 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 الخاص بالمشروع.

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

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

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

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

يتيح محاكي Cloud Functions استخدام الأسرار لـ تخزين معلومات الإعداد الحساسة والوصول إليها. سيحاول المحاكي تلقائيًا الوصول إلى أسرار مرحلة الإنتاج باستخدام بيانات الاعتماد التلقائية للتطبيق. في حالات معيّنة، مثل بيئات التكامل المستمر (CI)، قد يتعذّر على المحاكي الوصول إلى قيم الأسرار بسبب قيود الأذونات.

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

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

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

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

يمكنك الاطّلاع على مزيد من المعلومات عن واجهة Cloud Functions وحزمة Cloud Functions Test SDK في اختبار الدوال بشكل تفاعلي و الاختبار على مستوى الوحدة لـ Cloud Functions.

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

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

Cloud IAM

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

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

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

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

التخطيط للاختلافات في البيئتَين المحلية وبيئة الإنتاج

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

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

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

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

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

لا يتيح محاكي Cloud Functions إعادة محاولة الدوال عند حدوث خطأ.

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

• للاطّلاع على مجموعة منسّقة من الفيديوهات وأمثلة تفصيلية حول كيفية إجراء ذلك، يُرجى اتّباع قائمة تشغيل التدريب على محاكيات Firebase.
• مزيد من المعلومات عن محاكي Cloud Functions for Firebase في تشغيل الدوال محليًا.