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

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

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

  $ 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 may 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 تكرار أي سلوك مرتبط بإدارة الهوية وإمكانية الوصول أو الالتزام به عند التشغيل. تلتزم المحاكيات بقواعد أمان 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 إعادة محاولة تنفيذ الدوال في حال تعذّر تنفيذها.

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

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