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

قبل ربط تطبيقك بمحاكي دوال Cloud، تأكَّد من فهم سير العمل العام لحزمة أدوات المحاكاة المحلية من Firebase ومن تثبيت حزمة المحاكي المحلي وإعدادها ومراجعة أوامر واجهة سطر الأوامر الخاصة بها.

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

تحاكي "حزمة أدوات المحاكاة المحلية في Firebase" منتجات مشروع واحد على Firebase.

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

تتيح حزمة المحاكي المحلي إمكانية محاكاة مشاريع Firebase الحقيقية ومشاريع تجريبية.

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

مشروع Firebase الحقيقي هو مشروع أنشأته وضبطته (على الأرجح من خلال "وحدة تحكُّم Firebase").

تتضمّن المشاريع الحقيقية موارد مباشرة، مثل مثيلات قواعد البيانات أو حِزم مساحة التخزين أو الدوال أو أي مورد آخر أعددته لمشروع Firebase هذا.

عند العمل على مشاريع Firebase حقيقية، يمكنك تشغيل أدوات محاكاة لأيٍّ من المنتجات المتوافقة أو جميعها.

بالنسبة إلى أي منتجات لا تحاكيها، ستتفاعل تطبيقاتك ورمزك مع المورد المباشر (مثيل قاعدة البيانات أو حزمة التخزين أو الوظيفة أو غير ذلك).

تجريبي

لا يتضمّن مشروع Firebase التجريبي إعدادات Firebase حقيقية ولا يحتوي على موارد مباشرة. يمكن الوصول إلى هذه المشاريع عادةً من خلال الدروس التطبيقية حول الترميز أو البرامج التعليمية الأخرى.

تتضمّن أرقام تعريف المشاريع الخاصة بالمشاريع التجريبية البادئة demo-.

عند العمل مع مشاريع Firebase التجريبية، تتفاعل تطبيقاتك ورمزك مع المحاكيات فقط. وإذا حاول تطبيقك التفاعل مع مورد لا يعمل المحاكي لديه، لن ينجح هذا الرمز.

ننصحك باستخدام المشاريع التجريبية كلما أمكن ذلك. تتضمّن المزايا ما يلي:

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

استخدِم تطبيقك للتواصل مع المحاكيات

ضبط تطبيقك للدوال القابلة للاستعانة بها

إذا كان النموذج الأوّلي وأنشطة الاختبار تتضمّن دوال خلفية قابلة للاستدعاء، يمكنك ضبط التفاعل مع محاكي Cloud Functions for Firebase على النحو التالي:

Kotlin+KTX
// 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().useFunctionsEmulator(origin: "http://127.0.0.1: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

خصِّص تطبيقك لمحاكاة الدوال التي يتم تشغيلها في الخلفية.

يدعم محاكي دوال السحابة الإلكترونية الدوال التي يتم تشغيلها في الخلفية من المصادر التالية:

  • محاكي قاعدة البيانات في الوقت الفعلي
  • محاكي Cloud Firestore
  • محاكي المصادقة
  • محاكي نشر/اشتراك

لبدء الأحداث في الخلفية، عليك تعديل موارد الواجهة الخلفية باستخدام واجهة مستخدم Emulator Suite أو من خلال ربط تطبيقك أو اختبار الرمز ببرامج المحاكاة باستخدام حزمة تطوير البرامج (SDK) لنظامك الأساسي.

معالِجات اختبار الأحداث المخصّصة الصادرة عن الإضافات

بالنسبة إلى الوظائف التي تنفِّذها للتعامل مع الأحداث المخصَّصة في "إضافات Firebase" باستخدام الإصدار 2 من Cloud Functions، يمكن إقران محاكي Cloud Functions مع محاكي Eventarc لإتاحة مشغّلات Eventarc.

لاختبار معالِجات الأحداث المخصّصة للإضافات التي تُصدر الأحداث، عليك تثبيت مُحاكيات Cloud Functions وEventarc.

يضبط وقت تشغيل Cloud Functions متغيّر بيئة EVENTARC_EMULATOR على localhost:9299 في العملية الحالية إذا كان محاكي Eventarc قيد التشغيل. تتصل حِزم SDK لمشرفي Firebase تلقائيًا بمحاكي Eventarc عند ضبط متغيّر بيئة EVENTARC_EMULATOR. يمكنك تعديل المنفذ التلقائي كما هو موضّح ضمن إعداد مجموعة أدوات المحاكاة المحلية.

عندما يتم ضبط متغيرات البيئة بشكلٍ صحيح، ترسل حزمة تطوير البرامج (SDK) لمشرف Firebase الأحداث تلقائيًا إلى محاكي Eventarc. وفي المقابل، يعيد محاكي Eventarc استدعاء محاكي Cloud Functions لتفعيل أي معالِجات مسجّلة.

يمكنك الاطّلاع على سجلات "الدوال" في واجهة مستخدم Emulator Suite للحصول على تفاصيل حول تنفيذ المعالج.

ضبط بيئة اختبار على الجهاز

إذا كانت الدوال تعتمد على ضبط البيئة المستند إلى dotenv، يمكنك محاكاة هذا السلوك في بيئة الاختبار المحلية.

عند استخدام محاكي محلي للوظائف، يمكنك تجاوز متغيّرات البيئة لمشروعك من خلال إعداد ملف .env.local. يكون لمحتوى .env.local الأولوية على .env وملف .env الخاص بالمشروع.

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

.env .env.dev .env.local
PLANET=الأرض

الجمهور=البشر

الجمهور=فريق مطوّري البرامج الجمهور=أشخاص محليون

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

  $ 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 مع واجهة تشبه واجهة REPL. لا يتم توفير التكامل مع مُحاكيات قاعدة البيانات Cloud Firestore أو Realtime Database. وباستخدام واجهة الأوامر، يمكنك محاكاة البيانات وإجراء استدعاءات الدوال لمحاكاة التفاعل مع المنتجات التي لا تتوافق مع "مجموعة أدوات المحاكاة المحلية": "إحصاءات Google" و"الإعداد عن بُعد" و"Crashlytics".
  • حزمة تطوير البرامج (SDK) لاختبار Firebase لوظائف Cloud، وهي عبارة عن Node.js مع إطار عمل mocha لتطوير الوظائف. في الواقع، توفّر "حزمة تطوير البرامج (SDK) لاختبار دوال السحابة" التشغيل الآلي في واجهة برمجة التطبيقات Cloud Functions.

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

أوجه اختلاف محاكي وظائف السحابة الإلكترونية عن مرحلة الإنتاج

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

Cloud IAM

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

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

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

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

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

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

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

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

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

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

لا يتيح محاكي دوال السحابة الإلكترونية إعادة محاولة تنفيذ الدوال عند التعذُّر.

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