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

تجهيز تطبيقك لمحاكاة وظائف قائمة انتظار المهام

يُنشئ المحاكي تلقائيًا قوائم انتظار مهام محاكية استنادًا إلى تعريفات العوامل المشغِّلة، وتعيد حزمة 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 لتشغيل أي معالجات مسجَّلة.

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

Cloud IAM

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

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

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

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

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

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

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

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

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

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

لا يتيح محاكي Cloud Functions إعادة محاولة تنفيذ الدوالّ في حال تعذّر ذلك.

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