ربط تطبيقك بمحاكي Cloud Functions

قبل ربط تطبيقك بمحاكي Cloud Functions، تأكَّد من أنّك تفهم سير عمل Firebase Local Emulator Suite بشكل عام، ومن أنّك تثبّت Local Emulator Suite وتضبط إعداداته وتراجع أوامر واجهة سطر الأوامر.

اختيار مشروع Firebase

تحاكي Firebase Local Emulator Suite المنتجات لمشروع واحد على Firebase.

لاختيار المشروع الذي تريد استخدامه، نفِّذ الأمر firebase use في دليل العمل قبل بدء المحاكيات. أو يمكنك تمرير العلامة --project إلى كل أمر من أوامر المحاكي.

تتيح Local Emulator Suite محاكاة مشاريع Firebase الحقيقية ومشاريع العرض التوضيحي.

نوع المشروع الميزات الاستخدام مع المحاكيات
Real

مشروع 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)
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);
Swift
Functions.functions().useEmulator(withHost: "localhost", port: 5001)
Unity
FirebaseFunctions functions = FirebaseFunctions.DefaultInstance;
// Connects to the Functions Emulator running on port 5001
functions.UseFunctionsEmulator("http://127.0.0.1:5001");

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);

Web

firebase.functions().useEmulator("127.0.0.1", 5001);

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

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

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

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

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

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

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

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

Cloud IAM

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

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

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

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

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

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

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

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

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

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

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

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