ربط تطبيقك بمحاكي 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

FirebaseFunctions functions = FirebaseFunctions.DefaultInstance;
// Connects to the Functions Emulator running on port 5001
functions.UseFunctionsEmulator("http://127.0.0.1:5001");

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 v2، يقترن محاكي 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 في تشغيل الدوال محليًا.