חיבור האפליקציה לאמולטור Cloud Functions

לפני שמקשרים את האפליקציה לאמולטור Cloud Functions, חשוב לוודא שמבינים את תהליך העבודה הכולל של Firebase Local Emulator Suite, שהתקנתם והגדרתם את Local Emulator Suite ושבדקתם את פקודות ה-CLI שלו.

בחירת פרויקט ב-Firebase

‫Firebase Local Emulator Suite מדמה מוצרים לפרויקט Firebase יחיד.

כדי לבחור את הפרויקט שבו רוצים להשתמש, לפני שמפעילים את האמולטורים, מריצים את הפקודה firebase use בספריית העבודה. אפשר גם להעביר את הדגל --project לכל פקודת אמולטור.

‫Local Emulator Suite תומך באמולציה של פרויקטים אמיתיים ב-Firebase ושל פרויקטים לדוגמה.

סוג הפרויקט תכונות שימוש באמולטורים
Real

פרויקט Firebase אמיתי הוא פרויקט שיצרתם והגדרתם (לרוב דרך Firebaseהמסוף).

בפרויקטים אמיתיים יש משאבים פעילים, כמו מופעים של מסדי נתונים, קטגוריות אחסון, פונקציות או כל משאב אחר שהגדרתם לפרויקט הזה ב-Firebase.

כשעובדים עם פרויקטים אמיתיים ב-Firebase, אפשר להפעיל אמולטורים לכל המוצרים הנתמכים או לחלק מהם.

לגבי כל המוצרים שאתם לא מדמים, האפליקציות והקוד שלכם יפעלו באינטראקציה עם משאב פעיל (מופע של מסד נתונים, קטגוריית אחסון, פונקציה וכו').

הדגמה

לפרויקט הדגמה ב-Firebase אין הגדרה אמיתית של Firebase ואין לו משאבים פעילים. בדרך כלל ניגשים לפרויקטים האלה באמצעות הדרכות של Codelab או מדריכים אחרים.

מזהי פרויקטים של פרויקטים לדוגמה מתחילים בקידומת demo-.

כשעובדים עם הדגמות של פרויקטים ב-Firebase, האפליקציות והקוד מקיימים אינטראקציה רק עם אמולטורים. אם האפליקציה מנסה ליצור אינטראקציה עם משאב שלא מופעל בו אמולטור, הקוד ייכשל.

מומלץ להשתמש בפרויקטים לדוגמה ככל האפשר. ההטבות כוללות:

  • ההגדרה קלה יותר, כי אפשר להריץ את האמולטורים בלי ליצור פרויקט Firebase
  • רמת בטיחות גבוהה יותר, כי אם הקוד שלכם מפעיל בטעות משאבים שלא מבוססים על אמולציה (משאבי ייצור), אין סיכוי לשינוי נתונים, לשימוש ולחיוב
  • תמיכה טובה יותר במצב אופליין, כי אין צורך לגשת לאינטרנט כדי להוריד את הגדרות ה-SDK.

הגדרת האפליקציה לתקשורת עם האמולטורים

הוספת קוד לאפליקציה כדי להשתמש בפונקציות שאפשר להפעיל

אם פעילויות האב-טיפוס והבדיקה שלכם כוללות פונקציות backend שאפשר להפעיל, צריך להגדיר את האינטראקציה עם האמולטור 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)
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().useEmulator(withHost: "localhost", port: 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.

שימו לב שמערכת השליחה שמשמשת בסביבת הייצור מורכבת יותר מזו שהוטמעה באמולטור, ולכן לא כדאי לצפות שההתנהגות המדומה תשקף במדויק את סביבות הייצור. הפרמטרים בתוך האמולטור מספקים גבולות עליונים לקצב שבו המשימות נשלחות ומנסים לבצע אותן מחדש.

הגדרת האפליקציה להדמיה של פונקציות שמופעלות ברקע

האמולטור של Cloud Functions תומך בפונקציות שמופעלות ברקע מהמקורות הבאים:

  • אמולטור Realtime Database
  • אמולטור Cloud Firestore
  • אמולטור Authentication
  • אמולטור Pub/Sub
  • אמולטור של התראות ב-Firebase

כדי להפעיל אירועים ברקע, צריך לשנות את משאבי ה-backend באמצעות התג Emulator Suite UI, או לחבר את האפליקציה או את קוד הבדיקה לאמולטורים באמצעות ה-SDK של הפלטפורמה.

בדיקת רכיבי handler לאירועים מותאמים אישית שמופקים על ידי תוספים

בפונקציות שמטפלות בFirebase Extensions אירועים מותאמים אישית עם Cloud Functions v2, האמולטור של Cloud Functions משויך לאמולטור של Eventarc כדי לתמוך בטריגרים של Eventarc.

כדי לבדוק את ה-handlers של אירועים מותאמים אישית לתוספים ששולחים אירועים, צריך להתקין את 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 כדי להפעיל את כל ה-handlers הרשומים.

אפשר לבדוק את היומנים של Functions ב-Emulator Suite UI כדי לקבל פרטים על הביצוע של handler.

הגדרת סביבת בדיקה מקומית

אם הפונקציות שלכם מסתמכות על הגדרת סביבה מבוססת dotenv, אתם יכולים לחקות את ההתנהגות הזו בסביבת הבדיקה המקומית.

כשמשתמשים באמולטור מקומי Cloud Functions, אפשר להגדיר קובץ .env.local כדי לשנות את משתני הסביבה של הפרויקט. התוכן של .env.local מקבל עדיפות על פני .env וקובץ .env הספציפי לפרויקט.

לדוגמה, פרויקט יכול לכלול את שלושת הקבצים האלה עם ערכים שונים מעט לפיתוח ולבדיקה מקומית:

.env .env.dev .env.local
PLANET=Earth

קהל=בני אדם

AUDIENCE=Dev 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. באמצעות המעטפת, אפשר ליצור נתוני דמה ולבצע קריאות לפונקציות כדי לדמות אינטראקציה עם מוצרים שLocal Emulator Suite לא תומך בהם כרגע: Analytics,‏ Remote Config ו-Crashlytics.
  • ‫Firebase Test SDK for 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, אבל במצבים שבהם בדרך כלל נעשה שימוש ב-IAM, למשל כדי להגדיר חשבון שירות שמפעיל את Cloud Functions וכך גם את ההרשאות, אי אפשר להגדיר את האמולטור והוא ישתמש בחשבון שזמין באופן גלובלי במחשב של המפתח, בדומה להרצה ישירה של סקריפט מקומי.

הגבלות על זיכרון ומעבד

האמולטור לא אוכף הגבלות על הזיכרון או על המעבד של הפונקציות. עם זאת, האמולטור תומך בפונקציות של פסק זמן באמצעות הארגומנט של זמן הריצה timeoutSeconds.

שימו לב: זמן ההפעלה של הפונקציה עשוי להיות שונה מהזמן שנדרש להפעלה בסביבת הייצור, כשמריצים פונקציות באמולטור. מומלץ, אחרי שתכננתם ובדקתם פונקציות באמצעות האמולטור, להריץ בדיקות מוגבלות בסביבת הייצור כדי לוודא את זמני הביצוע.

תכנון ההבדלים בין סביבות מקומיות וסביבות ייצור

מכיוון שהאמולטור פועל במחשב המקומי, הוא תלוי בסביבה המקומית שלכם לאפליקציות ולתוכניות וכלי עזר מובנים.

חשוב לזכור שהסביבה המקומית לפיתוח Cloud Functions עשויה להיות שונה מסביבת הייצור של Google:

  • ההתנהגות של אפליקציות שמתקינים באופן מקומי כדי לדמות את סביבת הייצור (למשל, ImageMagick מהמדריך הזה) עשויה להיות שונה מההתנהגות בסביבת הייצור, במיוחד אם נדרשות גרסאות שונות או אם הפיתוח מתבצע בסביבה שאינה Linux. מומלץ לפרוס עותק בינארי משלכם של התוכנית החסרה לצד פריסת הפונקציה.

  • באופן דומה, יכול להיות שיהיו הבדלים בין כלי עזר מובנים (למשל, פקודות shell כמו ls, mkdir) לבין הגרסאות שזמינות בסביבת הייצור, במיוחד אם אתם מפתחים בסביבה שהיא לא Linux (למשל, macOS). כדי לפתור את הבעיה הזו, אפשר להשתמש בחלופות שמבוססות על Node בלבד לפקודות מקוריות, או ליצור קבצים בינאריים של Linux כדי לאגד אותם עם הפריסה.

מנסה שוב

האמולטור של Cloud Functions לא תומך בניסיון חוזר להפעלת פונקציות במקרה של כשל.

מה הלאה?