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

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

• פונקציה של 'הוספת הודעה' שחושפת כתובת URL שמקבלת ערך טקסט וכותבת אותו אל Cloud Firestore.
• פונקציה של 'הפיכה לאותיות רישיות' שמופעלת על Cloud Firestore כתיבה וממירה את הטקסט לאותיות רישיות.

הנה קוד הדוגמה המלא שמכיל את הפונקציות:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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 saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

מידע על המדריך הזה

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

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

יצירת פרויקט Firebase

1. במסוף Firebase, לוחצים על הוספת פרויקט.

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

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

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

3. לוחצים על המשך.

4. (אופציונלי) מגדירים את Google Analytics לפרויקט, כדי ליהנות מחוויה אופטימלית באמצעות המוצרים הבאים של Firebase:‏ Firebase A/B Testing,‏ Cloud Messaging,‏ Crashlytics,‏ In-App Messaging ו-Remote Config (כולל התאמה אישית).

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

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

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

הגדרת הסביבה ו-Firebase CLI

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

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

כדי לאתחל את הפרויקט:

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

5. ממשק ה-CLI מציע את האפשרויות הבאות לתמיכה בשפה:

   • JavaScript
   • TypeScript
   • Python

   במדריך הזה, בוחרים באפשרות JavaScript או Python. למידע על כתיבה ב-TypeScript, אפשר לעיין במאמר כתיבת פונקציות באמצעות TypeScript.

6. ה-CLI מאפשר להתקין יחסי תלות. אפשר לסרב בבטחה אם רוצים לנהל את התלות בדרך אחרת.

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

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

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
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

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

אחרי שמסיימים את משימות ההגדרה, אפשר לפתוח את ספריית המקור ולהתחיל להוסיף קוד כמו שמתואר בקטעים הבאים. בדוגמה הזו, צריך לייבא לפרויקט את המודולים Cloud Functions ו-Admin SDK. מוסיפים לקובץ המקור שורות כמו הבאות:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

השורות האלה טוענות את המודולים הנדרשים ומאתחלות מופע של אפליקציית admin שממנו אפשר לבצע שינויים ב-Cloud Firestore. בכל מקום שבו יש תמיכה ב-Admin SDK, כמו ב-FCM, Authentication ו-Firebase Realtime Database, הוא מספק דרך יעילה לשילוב של Firebase באמצעות Cloud Functions.

ממשק Firebase CLI מתקין באופן אוטומטי את Firebase Admin SDK ואת מודולי Firebase SDK for Cloud Functions כשמפעילים את הפרויקט. מידע נוסף על הוספת ספריות של צד שלישי לפרויקט זמין במאמר טיפול בתלות.

הוספת הפונקציה 'הוספת הודעה'

כדי להוסיף את הפונקציה add message, מוסיפים את השורות הבאות לקובץ המקור:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = 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 getFirestore()
      .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.`});
});
index.js

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

הפונקציה add message היא נקודת קצה (endpoint) של HTTP. כל בקשה לנקודת הקצה יוצרת אובייקטים של בקשה ותשובה שמועברים ל-request handler של הפלטפורמה (onRequest() או on_request).

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

הוספת הפונקציה 'הפיכה לאותיות רישיות'

כדי להשתמש בפונקציה make uppercase, מוסיפים את השורות הבאות לקובץ המקור:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

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

סוגריים מסולסלים – לדוגמה, {documentId} – מקיפים את הפרמטרים, תווים כלליים שחושפים את הנתונים התואמים שלהם בקריאה החוזרת. ‫Cloud Firestore מפעיל את הקריאה החוזרת בכל פעם שנוספות הודעות חדשות.

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

הדמיית ההפעלה של הפונקציות

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

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

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

2. בודקים את הפלט של הפקודה firebase emulators:start כדי לראות את כתובת ה-URL של פונקציית ה-HTTP. הוא ייראה דומה ל-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. יוצרים הודעה חדשה על ידי פתיחת כתובת ה-URL בכרטיסייה חדשה בדפדפן.

5. אפשר לראות את ההשפעות של הפונקציות ב-Emulator Suite UI:

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

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

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

כדי להשלים את המדריך, צריך לפרוס את הפונקציות ואז להריץ אותן.

1. מריצים את הפקודה הבאה כדי לפרוס את הפונקציות:

    firebase deploy --only functions
    

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

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

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

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

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

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

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

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

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

השלבים הבאים

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

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

• תרחישים לדוגמה לשימוש ב-Cloud Functions
• אפשר לנסות את ה-codelab של Cloud Functions.
• בדיקה והפעלה של דוגמאות קוד ב-GitHub