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