ربط تطبيقك بمحاكي 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)
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().useEmulator(withHost: "localhost", port: 5001)
ViewController.swift

Web

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

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 الخاص بالمشروع.

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

.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 مع استخدام الأسرار لـ تخزين معلومات الإعداد الحساسة والوصول إليها. سيحاول المحاكي تلقائيًا الوصول إلى أسرار الإنتاج باستخدام بيانات الاعتماد التلقائية للتطبيق. في حالات معيّنة، مثل بيئات التكامل المستمر (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 إعادة محاولة الدوال عند حدوث خطأ.

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