ربط تطبيقك بمحاكي 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().useFunctionsEmulator(origin: "http://127.0.0.1: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

تجهيز تطبيقك لمحاكاة دوال قائمة المهام

يُنشئ المحاكي تلقائيًا قوائم انتظار مهام محاكية استنادًا إلى تعريفات العوامل المشغِّلة، وتعيد حزمة Admin SDK توجيه الطلبات المُدرَجة في قائمة الانتظار إلى المحاكي إذا رصدت أنّها تعمل من خلال متغيّر CLOUD_TASKS_EMULATOR_HOST في البيئة.

يُرجى العِلم أنّ نظام الإرسال المستخدَم في قناة الإصدار العلني أكثر تعقيدًا من النظام الذي تم تنفيذه في المحاكي، لذا لا تتوقّع أن يعكس سلوك الإصدار المُحاكي بدقة بيئات الإصدار العلني. تحدِّد المَعلمات ضمن الemualator الحدود القصوى لمعدّل إرسال المهام وإعادة المحاولة.

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

يتيح محاكي 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 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.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، قد يتعذّر على المحاكي الوصول إلى القيم السرية بسبب قيود الأذونات.

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

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

يتمّ استخدام محاكي Cloud Functions مع أدوات أخرى لإنشاء النماذج الأولية والاختبار:

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

يمكنك الاطّلاع على مزيد من المعلومات عن حِزم تطوير البرامج (SDK) لاختبار Cloud Functions وShell لوظائف Cloud في مقالتَي اختبار الدوالّ بشكل تفاعلي واختبار الوحدات في Cloud Functions.

أوجه الاختلاف بين محاكي Cloud Functions والإصدار العلني

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

Cloud IAM

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

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

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

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

التخطيط للاختلافات في البيئتَين المحلية والعلنية

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

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

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

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

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

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

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

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