אחרי ההעברה מ-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 בספריית ההגדרות של מופע ה-kit. לדוגמה, אם יש לכם מופע של ערכת כלים בשם 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.ajp-testing
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, מומלץ מאוד לשמור את התוסף למקרה שתחליטו לבצע את ההעברה אחרי התאריך הזה.
כדי לקבל רשימה של מזהי מופעי התוספים:
אפשר להשתמש בפקודת
ext:listCLI כדי לקבל רשימה של כל המופעים של התוספים בפרויקט Firebase:firebase ext:list --project <project-id>דוגמה:
firebase ext:list --project my-project» firebaselocal ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in ajp-testing: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ 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, אבל לא צריך אותם בשימוש יומיומי אם לא העברתם אותם לערכות פונקציות. אתם יכולים להעביר אותם מהפרויקט לכל מיקום אחסון מתאים אחר עד שתצטרכו אותם בעתיד או עד שתבחרו למחוק אותם.