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

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

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

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

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

צור פרויקט Firebase

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

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

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

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

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

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

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

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

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

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

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

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

לאחר השלמת משימות ההתקנה, תוכל לפתוח את ספריית המקור ולהתחיל להוסיף קוד כמתואר בסעיפים הבאים. עבור מדגם זה, הפרויקט שלך חייב לייבא את פונקציות ענן ומודולים 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 מודולים, ו לאתחל admin מופע יישום שממנו ענן Firestore שניתן יהיה לבצע שינויים. בכל מקום SDK של ניהול תמיכה זמינה, כפי שהוא עבור FCM, אימות, ו Firebase זמן אמת Database, זה מספק דרך רבת עוצמה כדי לשלב Firebase באמצעות פונקציות ענן.

Firebase CLI מתקין אוטומטית את Firebase ו- Firebase SDK עבור מודולי צומת פונקציות ענן בעת ​​אתחול הפרויקט. כדי להוסיף ספריות צד 3 לפרויקט שלך, אתה יכול לשנות 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 הם סינכרוני (בדומה פונקציות callable ), אז אתה צריך לשלוח תגובה מהר ככל האפשר העבודה ולדחות באמצעות ענן firestore. addMessage() HTTP פונקציה מעביר ערך טקסט 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} -surround "פרמטרים," ג'וקר חושפי המידע המתאים שלהם ההתקשרות.

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

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

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

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

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

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

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

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

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

  5. צפה בהשפעות הפונקציות בממשק המשתמש של Emulator Suite:

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

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

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

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

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

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

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

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

    $ firebase deploy --only functions
    

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

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

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

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

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

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

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

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

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

סקור את קוד המדגם המלא

הנה השלים 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});
    });

הצעדים הבאים

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

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

הדרכת וידאו

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