Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

התחל בעבודה: כתוב, בדוק ופרס את הפונקציות הראשונות שלך

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

  • addMessage() , שחושף כתובת URL שמקבלת ערך טקסט וכותבת אותו ל- Cloud Firestore.
  • makeUppercase() , המפעיל ב- Cloud Firestore לכתוב והופך את הטקסט לאותיות רישיות.

בחרנו בפונקציות JavaScript של Cloud Firestore ו- HTTP המופעלות עבור מדגם זה, בין היתר מכיוון שניתן לבדוק ביסודיות את גורמי הרקע הללו באמצעות Firebase Local Emulator Suite . ערכת כלים זו תומכת גם בהפעלת מסדי נתונים בזמן אמת, PubSub, Auth ו- HTTP. סוגים אחרים של טריגרים ברקע כגון Remote Config, TestLab ו- triggers של Analytics ניתנים לבדיקה אינטראקטיבית באמצעות ערכות כלים שלא מתוארות בדף זה.

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

צור פרויקט Firebase

  1. במסוף Firebase , לחץ על הוסף פרויקט , ואז בחר או הזן שם פרויקט .

    אם יש לך פרויקט Google Cloud קיים, תוכל לבחור בפרויקט מהתפריט הנפתח כדי להוסיף משאבי Firebase לפרויקט זה.

  2. (אופציונלי) אם אתה יוצר פרויקט חדש, אתה יכול לערוך את מזהה הפרויקט .

    Firebase מקצה אוטומטית מזהה ייחודי לפרויקט Firebase שלך. בקר ב- Understand Firebase Projects כדי ללמוד כיצד Firebase משתמש במזהה הפרויקט.

  3. לחץ על המשך .

  4. (אופציונלי) הגדר את Google Analytics לפרויקט שלך, המאפשר לך חוויה אופטימלית באמצעות כל אחד ממוצרי Firebase הבאים:

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

  5. לחץ על צור פרויקט (או הוסף Firebase , אם אתה משתמש בפרויקט Google Cloud קיים).

Firebase מספק אוטומטית משאבים לפרויקט Firebase שלך. לאחר סיום התהליך, תועבר לדף הסקירה הכללית של פרויקט Firebase שלך ​​במסוף Firebase.

הגדר את Node.js ואת ה- Firebase CLI

תזדקק לסביבת Node.js כדי לכתוב פונקציות, ותצטרך את ה- CLI של Firebase כדי לפרוס פונקציות בזמן הריצה של פונקציות ענן. להתקנת Node.js ו- npm , מומלץ מנהל גרסאות הצומת .

לאחר התקנת Node.js ו- npm, התקן את ה- CLI של Firebase בשיטה המועדפת עליך. כדי להתקין את ה- CLI באמצעות npm, השתמש ב:

npm install -g firebase-tools

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

אתחל את הפרויקט שלך

כאשר אתה מבצע אתחול של Firebase SDK לפונקציות ענן, אתה יוצר פרויקט ריק המכיל תלות וקוד דוגמה מינימלי כלשהו, ​​ובוחרים ב- TypeScript או ב- JavaScript לפונקציות הלחנה. למטרות הדרכה זו, יהיה עליך לאתחל את Cloud Firestore.

לאתחול הפרויקט שלך:

  1. הפעל firebase login כדי להתחבר דרך הדפדפן ואמת את הכלי firebase.
  2. עבור לספריית הפרויקטים שלך ב- Firebase.
  3. הפעל את firebase init firestore . עבור הדרכה זו, אתה יכול לקבל את ערכי ברירת המחדל כאשר תתבקש להתקין כללי Firestore וקבצי אינדקס. אם עדיין לא השתמשת ב- Cloud Firestore בפרויקט זה, תצטרך גם לבחור מצב התחלה ומיקום עבור Firestore כמתואר בסעיף התחל בעבודה עם Cloud Firestore .
  4. הפעל firebase init functions . הכלי נותן לך אפשרות להתקין תלות עם npm. זה בטוח לדחות אם אתה רוצה לנהל תלות בדרך אחרת, אם כי אם אתה npm install תצטרך להריץ את npm install לפני הדמיה או פריסה של הפונקציות שלך.
  5. הכלי נותן לך שתי אפשרויות לתמיכה בשפה:

    להדרכה זו בחר JavaScript .

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

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

הקובץ package.json שנוצר במהלך האתחול מכיל מפתח חשוב: "engines": {"node": "10"} . זה מציין את גרסת Node.js שלך לכתיבה ולפריסה של פונקציות. אתה יכול לבחור גרסאות נתמכות אחרות .

ייבא את המודולים הדרושים ואתחל אפליקציה

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

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

שורות אלה טוענות את firebase-functions firebase-admin ו- firebase-admin , ומאתחלות מופע של אפליקציית admin שממנו ניתן לבצע שינויים ב- Cloud Firestore. בכל מקום שתמיכת Admin SDK זמינה, כמו גם עבור FCM, אימות ומסד נתונים בזמן אמת של Firebase, היא מספקת דרך עוצמתית לשילוב Firebase באמצעות פונקציות ענן.

ה- Firebase CLI מתקין באופן אוטומטי את מודולי Firebase ו- Firebase SDK עבור ענן פונקציות ענן בעת ​​אתחול הפרויקט שלך. כדי להוסיף ספריות של צד שלישי לפרויקט שלך, תוכל לשנות את package.json ולהפעיל את npm install . למידע נוסף, ראה טיפול בתלות .

הוסף את הפונקציה addMessage()

addMessage() , הוסף שורות אלה ל- index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

addMessage() היא נקודת סיום HTTP. כל בקשה לנקודת הקצה מביאה לאובייקטים של בקשה ותגובה בסגנון ExpressJS המועברים onRequest() .

פונקציות HTTP הן סינכרוניות (בדומה לפונקציות הניתנות להתקשרות ), לכן עליך לשלוח תגובה במהירות האפשרית ולדחות את העבודה באמצעות Cloud Firestore. פונקציית HTTP addMessage() מעבירה ערך טקסט לנקודת הקצה של HTTP ומכניסה אותו למסד הנתונים מתחת לנתיב /messages/:documentId/original .

הוסף את הפונקציה makeUppercase()

makeUppercase() , הוסף שורות אלה ל- index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

makeUppercase() Firestore נכתב. פונקציית ref.set מגדירה את המסמך להאזנה. מסיבות ביצוע, עליך להיות ספציפי ככל האפשר.

סוגריים - למשל, {documentId} פרמטרים "סראונד", תווים כלליים החושפים את הנתונים התואמים שלהם בקולבק.

Cloud Firestore מפעיל את onWrite() להתקשרות onWrite() בכל פעם שנכתבים או מתעדכנים נתונים במסמך הנתון.

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

לחקות את ביצוע הפונקציות שלך

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

כדי לחקות את הפונקציות שלך:

  1. הפעל firebase emulators:start ובדוק את הפלט עבור כתובת ה- URL של ממשק המשתמש של אמולטור סוויט. ברירת המחדל היא localhost: 4000 , אך עשויה להתארח ביציאה אחרת במחשב שלך. הזן את כתובת האתר בדפדפן שלך כדי לפתוח את ממשק המשתמש של אמולטור סוויט.

  2. בדוק את הפלט של firebase emulators:start פקודת firebase emulators:start עבור כתובת ה- URL של פונקציית HTTP addMessage() . זה ייראה דומה ל- http://localhost:5001/MY_PROJECT/us-central1/addMessage , אלא ש:

    1. MY_PROJECT יוחלף במזהה הפרויקט שלך.
    2. היציאה עשויה להיות שונה במכונה המקומית שלך.
  3. הוסף את מחרוזת השאילתה ?text=uppercaseme בסוף כתובת ה- URL של הפונקציה. זה אמור להיראות בערך כמו: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . לחלופין, באפשרותך לשנות את ההודעה "אותיות גדולות" להודעה מותאמת אישית.

  4. צור הודעה חדשה על ידי פתיחת כתובת האתר בכרטיסייה חדשה בדפדפן שלך.

  5. צפה בהשפעות הפונקציות בממשק המשתמש של סוויטת אמולטור:

    1. בכרטיסיה יומנים , אתה אמור לראות יומנים חדשים המציינים שהפונקציות addMessage() ו- makeUppercase() רצו:

      פונקציות i: תחילת הביצוע של "addMessage"

      פונקציות i: תחילת הביצוע של "makeUppercase"

    2. בכרטיסייה Firestore , אתה אמור לראות מסמך המכיל את ההודעה המקורית שלך, כמו גם את הגרסה הגדולה של ההודעה שלך (אם במקור היא הייתה "עליונה", תראה "UPPERCASEME").

פריסת פונקציות לסביבת ייצור

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

להשלמת ההדרכה, פרוס את הפונקציות שלך ואז בצע את addMessage() כדי להפעיל את makeUppercase() .

  1. הפעל פקודה זו כדי לפרוס את הפונקציות שלך:

    $ firebase deploy --only functions
    

    לאחר הפעלת פקודה זו, ה- Firebase CLI מוציא את כתובת ה- URL עבור כל נקודות קצה של פונקציית HTTP. במסוף שלך, אתה אמור לראות שורה כמו הבאה:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
    

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

    אם אתה נתקל בשגיאות גישה כגון "לא ניתן לאשר גישה לפרויקט", נסה לבדוק את כינויי הפרויקט שלך.

  2. באמצעות כתובת ה- URL של addMessage() ידי ה- CLI, הוסף פרמטר של שאילתת טקסט ופתח אותו בדפדפן:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
    

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

לאחר פריסה וביצוע פונקציות, באפשרותך להציג יומנים במסוף Firebase עבור פונקציות ענן . אם עליך למחוק פונקציות בפיתוח או בייצור, השתמש ב- CLI של Firebase.

בדוק את קוד הדוגמה השלם

הנה functions/index.js שהושלמו המכילות את הפונקציות addMessage() ו- makeUppercase() . פונקציות אלה מאפשרות לך להעביר פרמטר לנקודת קצה של HTTP שכותב ערך ל- Cloud Firestore, ולאחר מכן להפוך אותו על ידי אותיות גדולות בכל התווים במחרוזת.

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

הצעדים הבאים

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

למידע נוסף על פונקציות ענן, תוכל גם לבצע את הפעולות הבאות:

מדריך וידאו

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