אחרי שעוברים מ-Firebase Extensions לערכת פונקציות, מנהלים את המופעים של הערכה כמו פונקציות Cloud Functions רגילות מהדור השני בפרויקט ב-Firebase. במדריך הזה מוסבר איך להתקין ערכות פונקציות חדשות ישירות מ-npm בלי להעביר תוסף קיים, לעדכן את הפרמטרים של הערכה ואת האפשרויות הגלובליות, לשדרג את הגרסאות של חבילות npm כשהמפרסמים משיקים עדכונים, ולבטל את ההעברה במקרה הצורך.
שימוש בערכת פונקציות מחבילת npm בלי להעביר אותה
אם אתם לא מעבירים פונקציה מתוסף, השימוש בערכת פונקציות מורכב משני חלקים:
התקנת הערכה
כדי להתקין ערכת פונקציות, משתמשים בפקודת ה-CLI הבאה:
firebase functions:kits:install --package <npm-package-name>
דוגמה:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i function-kits/firestore-bigquery-export/source/package.json is unchanged
i function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i functions: Building TypeScript source...
✔ Wrote configuration info to firebase.json
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1
✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project
✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing
# Omitting many more parameters for brevity
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
i functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠ functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.
שינוי אפשרויות גלובליות שמוגדרות כברירת מחדל
כדי להגדיר את האפשרויות הגלובליות של המכונה של הערכה, משנים את הקובץ index.ts שנמצא ב-function-kits/<your-kit-id>/source/src/index.ts.
אם רוצים שברירות המחדל ישותפו בכל המופעים של הערכה, צריך להגדיר אותן ישירות ב-index.ts. אחרת, צריך ליצור פרמטרים שמוגדרים לכל מכונה, לפי הדוגמאות וההוראות שמתועדות ב-index.ts.
פריסת הערכה
כדי לפרוס את ערכת הפונקציות, מריצים את הפקודה:
firebase deploy --only functions:<kit-instance-id>
דוגמה:
firebase deploy --only functions:firestore-bigquery-export --project my-project
פלט:
=== Deploying to 'my-project'...
i deploying functions
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i functions: ensuring required API bigquery.googleapis.com is enabled...
i functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔ functions: required APIs are enabled
i functions: granting declarative IAM roles to managed service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
✔ functions: successfully granted IAM roles
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔ functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔ Deploy complete!
כשמתקינים ופורסים את הערכה, מתבצעות הפעולות הבאות:
- יוצר את
function-kits/firestore-bigquery-export/source, שמכיל את מקור הערכה, כולל קובץindex.tsבסיסי שמייבא ומייצא את חבילת הערכה תוך הגדרת פרמטר שמאפשר לבחור מיקום שונה לכל מופע של הערכה. - יוצר את
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>ומאכלס אותו בנתוני ההגדרות שהוזנו לפונקציה. אם בעדכונים עתידיים יתווספו פרמטרים חדשים, תתבקשו להזין אותם בפריסה הבאה. - יצירת המשאבים הנדרשים של Google Cloud כדי להריץ את הערכה הזו, כולל חשבון שירות עם תפקידי IAM ספציפיים, פונקציות, טריגרים של Eventarc ותורי משימות של Cloud Tasks.
אם יש לכם כמה מופעים של הערכה באותו פרויקט, אתם יכולים לחזור על הפקודות האלה כדי ליצור ולפרוס מופעים חדשים של אותה ערכה. אפשר גם לפרוס מופע אחד של ערכה בכמה פרויקטים ב-Firebase עם הגדרות שונות (לדוגמה, פרויקט בסביבת Staging ופרויקט בסביבת ייצור). מידע נוסף על הגדרות מתקדמות זמין במאמר העברות מתקדמות.
הסרת ערכה
כדי להסיר את הערכה ואת כל המופעים שלה, מריצים את הפקודה:
firebase functions:kits:uninstall --kit <kit-id>
הפעולה הזו מוחקת את כל המופעים וההגדרות שלהם, ומסירה את מקור הערכה מהדיסק.
כדי להסיר רק מופע אחד של הערכה, מריצים את הפקודה:
firebase functions:kits:uninstall --instance <kit-instance-id>
אם יש לכם רק מופע אחד של הערכה, הפעולה הזו תסיר את הערכה כולה.
עדכון של הגדרת ערכה
במהלך ההתקנה או הפריסה הראשונה, תתבקשו להגדיר את כל הפרמטרים של הערכה (אלא אם העברתם הגדרה מתוסף).
הפרמטרים האלה מאוחסנים בקובץ .env בספריית ההגדרות האישיות של המכונה של הערכה. לדוגמה, אם יש לכם מכונה של ערכת כלים בשם firestore-bigquery-export בפרויקט my-project, הקובץ .env נמצא ב-function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
הוא נראה כך:
DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1
אם אתם יודעים איזה ערך אתם רוצים לשנות, אתם יכולים לערוך אותו ישירות בקובץ .env. אם אתם מעדיפים להשתמש בהנחיה האינטראקטיבית שפועלת במהלך ההתקנה והפריסה, הסירו את הפרמטרים שאתם רוצים לשנות מהקובץ .env ופרסו מחדש את המכונה של הערכה. במהלך הפריסה תתבקשו להזין את הפרמטרים האלה.
לדוגמה, אם מוחקים את השורה COLLECTION_PATH=posts ומבצעים פריסה, תתבקשו להזין את הערך במהלך הפריסה:
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)
תחזוקה ושדרוג של ערכת פונקציות
בעלי אתרים יכולים לעדכן את חבילות ה-npm שלהם עם הזמן כדי לתקן באגים, להוסיף תכונות, לעדכן יחסי תלות או לטפל בפרצות אבטחה. מומלץ להתעדכן בגרסאות האלה ולהתקין עדכונים, במיוחד כאלה שמתייחסים לנקודות חולשה באבטחה.
הפקודה functions:kits:install יוצרת בסיס קוד שמתקין ערכה כחבילת npm ומייצאת את כל הפונקציות שלה לכל מופע של הערכה.
כדי לשדרג ערכה, מעדכנים את גרסת החבילה ואז פורסים מחדש כל מופע של הערכה כדי להחיל את השינויים.
איך בודקים אם יש עדכונים לערכה
עוברים לספרייה source של הערכה בכתובת function-kits/<your-kit-id>/source. בספרייה source, מריצים את הפקודה הבאה כדי לקבל דוח על כל חבילות ה-npm המיושנות, כולל ערכת הפונקציות ו-SDK של Cloud Functions:
npm outdated
אם אתם כבר משתמשים בכלי לזיהוי יחסי תלות שצריך לעדכן, כמו Dependabot ל-GitHub, מומלץ לשלב את ספריית הערכה בתהליך העבודה הזה.
עדכון ערכה
כדי לעדכן את הערכה ואת יחסי התלות שלה לגרסה העדכנית ביותר שלא גורמת לכשל (לא כולל עדכוני גרסה ראשית שעשויים להכיל שינויי תוכנה שעלולים לגרום לכשל), מריצים את הפקודה:
npm update --save
אם רוצים לעדכן רק את חבילת ערכת הפונקציות ולא חבילות אחרות, מעבירים את שם החבילה אל npm update:
npm update <package-name> --save
כדי לשדרג חבילה לגרסה הראשית האחרונה (שעשויה להכיל שינויים שעלולים לגרום לכשל), מריצים את הפקודה:
npm update --save <npm-package-name>@latest
כדאי לעיין בתיעוד של החבילה ובהערות הגרסה כדי לראות מה השתנה, ואם צריך לבצע שלבים נוספים לפני או אחרי הפריסה כדי למנוע שינויי תוכנה שעלולים לגרום לכשל.
פריסת מכונות מעודכנות
הרצת npm update מעדכנת רק את קוד המקור המקומי. כדי לעדכן את הפונקציות שפועלות בענן, צריך לפרוס אותן מחדש. כדי לפרוס מחדש את כל הפונקציות בפרויקט, כולל כל ערכות הפונקציות, מריצים את הפקודה:
firebase deploy --only functions
ביטול העברה
כדי לבטל העברה, קודם צריך להתקין מחדש את התוסף. אפשר להשתמש בקובץ .env של הערכה כדי למצוא את ערכי ההגדרות שצריך במהלך ההתקנה.
אחרי פריסת התוסף, מסירים את המופע של הערכה (הפעולה הזו מסירה את כל הערכה אם זה המופע האחרון שנותר):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
שמירת הגדרות של תוספים להעברה עתידית
אחרי 31 במרץ 2027, לא תהיה אפשרות לאחזר הגדרות קיימות של תוספים. אם לא תצליחו להעביר את התוסף לפני 31 במרץ 2027, מומלץ מאוד לשמור אותו למקרה שתחליטו להעביר אותו אחרי התאריך הזה.
כדי לקבל רשימה של מזהי המופעים של התוספים:
אתם יכולים להשתמש בפקודת ה-CLI
ext:listכדי לקבל רשימה של כל המופעים של התוספים בפרויקט Firebase:firebase ext:list --project <project-id>דוגמה:
firebase ext:list --project my-project» firebase ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in my-project: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3 │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export │ ACTIVE │ 0.3.2 │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshootingלפקודה
ext:listיש גם פורמט פלט של JSON. אם התקנתם את הכלי jq, אתם יכולים להשתמש בו כדי לקבל רשימה של כל מזהי המכונות בפרויקט:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'דוגמה:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'פלט:
firestore-bigquery-export-zbrp firestore-bigquery-exportמייצאים את ההגדרות של כל מכונה:
כדי לשמור את ההגדרות של כל מכונה בדיסק, מריצים את פקודת הייצוא הבאה:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>דוגמה:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportפלט:
i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i functions: Saving exported extensions config as a Function Kits .env file i functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control. i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testingבדיסק, הייצוא של מופע התוסף הזה נמצא במיקום כמו
<instance-id>/.env.<project-id>. בדוגמה הזו, הוא נמצא ב-firestore-bigquery-export/.env.my-project.אפשר לחזור על התהליך הזה פעם אחת לכל מופע, והוא יוצר קבוצה של קובצי
.envעם כל ההגדרות של מופעי התוספים, שאפשר להשתמש בהם שוב מאוחר יותר כחלק מההעברה.מעבירים את קובצי ה-
.envשיוצאו למיקום טוב יותר:קובצי
.envשיוצאו מהתוספים הועברו ישירות לפרויקט ב-Firebase, אבל לא צריך אותם ביום-יום אם לא עברתם לערכות פונקציות. אתם יכולים להעביר אותם מהפרויקט לכל מיקום אחסון מתאים אחר עד שתצטרכו אותם בעתיד, או למחוק אותם.