Google is committed to advancing racial equity for Black communities. See how.
דף זה תורגם על ידי Cloud Translation API.
Switch to English

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

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

  • 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 Platform (GCP) קיים, תוכל לבחור בפרויקט מהתפריט הנפתח כדי להוסיף משאבים של Firebase לפרויקט זה.

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

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

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

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

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

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

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

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

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

לאחר התקנת Node.js ו- npm, התקן את ה- Firebase CLI בשיטה המועדפת עליך. כדי להתקין את ה- 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 לפני שתדמה או תפרוס את הפונקציות שלך.
  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 שלך לכתיבה ולפריסה של פונקציות. אתה יכול לבחור גרסאות נתמכות אחרות .

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

לאחר שתסיים את משימות ההתקנה, תוכל לפתוח את ספריית המקור ולהתחיל להוסיף קוד כמתואר בסעיפים הבאים. לדוגמא זו, על הפרויקט שלך לייבא את מודולי ה- Cloud Functions ו- Admin 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 Cloud 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 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

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

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

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

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

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

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

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

  1. הפעל firebase emulators:start ובדוק את הפלט עבור כתובת האתר של ממשק המשתמש של אמולטור סוויט. ברירת המחדל היא 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 . באופן אופציונלי, באפשרותך לשנות את ההודעה "uppercaseme" להודעה מותאמת אישית.

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

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

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

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

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

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

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

לאחר שהפונקציות שלך פועלות לפי הצורך באמולטור, תוכל להמשיך בפריסה, בדיקה והפעלתן בסביבת הייצור. זכור שכדי לפרוס את סביבת הריצה המומלצת של Node.js 10, על הפרויקט שלך להיות בתוכנית החיוב של Blaze pay-as-you-go. ראה תמחור פונקציות ענן .

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

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

    $ firebase deploy --only functions
    

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

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

    כתובת ה- URL מכילה את מזהה הפרויקט שלך וכן אזור עבור פונקציית 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 Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

הצעדים הבאים

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

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

מדריך וידאו

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