העברת תוספים ל-Firebase אל Cloud Functions

במדריך הזה מוסבר איך להעביר את התוספים מסביבת Firebase Extensions שהוצאה משימוש לפונקציה שהמשתמשים מתקינים ופורסים בבסיס הקוד שלהם ב-Cloud Functions ל-Firebase (דור שני).

זו הדרך המומלצת להעברה. ‫Firebase ינהל רשימה של תוספים עם מקבילות npm רשמיות. המדריך הזה מסביר איך ליצור אותם.

במדריך הזה, התוסף Stream Cloud Firestore to BigQuery (firestore-bigquery-export) משמש כדוגמה. כל קטע מסתיים בדוגמה מעשית שמראה איך התוסף נראה לפני ההעברה ואיך הוא נראה אחרי ההעברה, בתור חבילת @firebase-function-kits/firestore-bigquery-export.

הרשמה לקבלת מידע נוסף ועזרה בהעברת תוספים

אם יש לכם שאלות לגבי המעבר מ-Firebase Extensions, אתם יכולים לפנות אלינו בכתובת firebase-extensions-migrator-support-external@google.com. אנחנו גם נשלח אימייל לקבוצה הזו כשנעדכן את המדריך עם מידע נוסף על אריזה, בדיקה והפצה של פונקציות מהדור השני.

כדי להצטרף לקבוצה, שולחים הודעה לכתובת firebase-extensions-migrator-support-external+subscribe@google.com. בתגובה תקבלו אימייל עם בקשת חברות. אתם צריכים להשיב לאימייל הזה, ולא ללחוץ על הכפתור "הצטרפות לקבוצה".

לפני שמתחילים

כדי להשלים את ההעברה הזו כפי שמתואר, תשתמשו בתכונות הבאות של Cloud Functions:

  • Parameterized Configuration. כל פרמטר שמצהירים עליו ב-extension.yaml הופך לפרמטר מוגדר בקוד החבילה.

  • תפקידי IAM דקלרטיביים וממשקי API נדרשים. כל תפקיד שמצהירים עליו ב-extension.yaml הופך לקריאה ל-requiresRole(...), וכל API הופך לקריאה ל-requiresAPI(...) בקוד החבילה. בזמן הפריסה, ה-CLI של Firebase מקצה את התפקידים שהוצהרו לחשבון שירות מנוהל של סביבת זמן ריצה, ומפעיל את ממשקי ה-API שהוצהרו בשמכם.

  • אירועים במחזור החיים של Cloud Functions בסיסי קוד. בסיסי הקוד של Cloud Functions תומכים עכשיו באירועים במחזור החיים, בדומה ל-Firebase Extensions. מצהירים על הגדרת זמן ההתקנה וזמן העדכון באמצעות ה-lifecycle hooks‏ afterFirstDeploy(...) ו-afterRedeploy(...). הן מחליפות את lifecycleEvents שהצהרתם עליהן ב-extension.yaml.

העברת קוד המקור של Firebase Extensions לפונקציה מהדור השני

(אופציונלי) העברה אוטומטית באמצעות המיומנות של סוכן Firebase

אתם יכולים להפוך את שלבים 1 עד 8 לאוטומטיים (יצירת מלאי של משאבים, הפעלת שדרוגים, המרות של פרמטרים וסודות, IAM הצהרתי, הוקים של מחזור חיים ויצירת קובץ README של החבילה) באמצעות המיומנות הרשמית של סוכן ה-AI של extension-to-functions-codebase.

מתקינים את הסקיל

אם אתם או עוזר ה-AI שלכם לתכנות (Gemini ב-Firebase, ‏ Cursor, ‏ Claude Code, ‏ GitHub Copilot) עדיין לא התקנתם את המיומנות, הריצו את הפקודה הבאה באמצעות ה-CLI של המיומנויות:

npx skills add firebase/agent-skills --skill extension-to-functions-codebase

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

"Please migrate this Firebase Extension into a publishable 2nd Gen Function Kit package following the instructions in the extension-to-functions-codebase skill."

1. הוספת התוסף למלאי

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

בודקים את כל אחד מהדברים הבאים ורושמים את הממצאים:

  • ‫extension.yaml, שבו מצהירים על הפרמטרים, הפונקציות, האירועים, תפקידי ה-IAM, ממשקי ה-API הנדרשים, הסודות ו-lifecycle hooks.

  • ‫functions/, שמכילה את קוד הפונקציה, יחסי התלות, תצורת ה-build, הטריגרים והפונקציות של תור המשימות.

  • ‫README.md,‏ PREINSTALL.md ו-POSTINSTALL.md, שכוללים שלבי הגדרה, אזהרות והערות לגבי חיוב.

  • ‫scripts/, שמכיל כלי ייבוא, מילוי, IAM, תיקון או העברה, וכל כלי אחר שאתם שולחים לצד התוסף.

לאחר מכן, לכל פריט ב-extension.yaml, מחליטים איפה הוא ימוקם בחבילת ה-npm:

  • ממירים את הגדרות המשתמש לפרמטרים של Cloud Functions (שלב 4).

  • המרת הסודות לסודות של Cloud Functions (שלב 4).

  • ממירים את תפקידי ה-IAM להצהרות requiresRole(...) (שלב 6).

  • ממירים את ממשקי ה-API הנדרשים של Google להצהרות requiresAPI(...) במקומות המתאימים (שלב 6).

  • ממירים את ה-hooks של ההתקנה והעדכון להצהרות afterFirstDeploy(...) ו-afterRedeploy(...) (שלב 7).

  • ממירים את מזהי המופעים מ-EXT_INSTANCE_ID ל-FIREBASE_KIT_INSTANCE_ID (שלב 4).

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

קריאה של firestore-bigquery-export/extension.yaml ו-functions/ יוצרת את המלאי הזה:

בextension.yaml מספר / ערך לאן הוא מועבר
params ‫25 (COLLECTION_PATH,‏ DATASET_ID,‏ TABLE_ID,‏ DATASET_LOCATION,‏ VIEW_TYPE,‏ …) ‫Cloud Functions פרמטרים (שלב 4)
apis bigquery.googleapis.com requiresAPI(...) (שלב 6)
roles ‫bigquery.dataEditor,‏ datastore.user,‏ bigquery.user requiresRole(...) (שלב 6)
resources טריגר אחד לאירוע (fsexportbigquery) + פונקציות של תור משימות (initBigQuerySync, setupBigQuerySync) פונקציות של חבילות שיוצאו (שלב 3)
lifecycleEvents onInstall ← initBigQuerySync; onUpdate / onConfigure ← setupBigQuerySync afterFirstDeploy / afterRedeploy (שלב 7)
מזהה מופע לא בשימוש (אין קריאות של EXT_INSTANCE_ID) אין מה להעביר
scripts/ ‫import/ (מילוי חוסרים), gen-schema-view/ נשמרים כסקריפטים (לא רלוונטי כאן)

ניתוח. התוסף לא מצהיר על פרמטרים של type: secret, ולכן אין מה להעביר לסודות בשלב 4. הטריגר של האירוע כבר מהדור השני, ורק הפונקציות של תור המשימות עדיין מהדור הראשון (רלוונטי לשלב 3).

2. עדכון package.json

מעדכנים את הקובץ package.json של התוסף. אם אתם מעבירים תוסף אחד, הוא יכול להיות ברמה הבסיסית (root) של package.json. אם אתם מעבירים הרבה תוספים במאגר אחד, תנו לכל תוסף חבילה משלו.

גרסאות SDK מינימליות: צריך להצהיר על firebase-functions >= 7.4.0 ועל firebase-admin >= 14.2.0 כיחסי תלות. צריך להצהיר על הגרסה של firebase-functions גם כתלות מקבילה, כדי שבפרויקט Cloud Functions של המשתמשים תהיה אותה גרסה של ה-SDK שבה הספרייה נכתבה.

{
  "name": "<package-name>",
  "version": "1.0.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "firebase-functions": "^7.4.0",
    "firebase-admin": "^14.2.0"
  }
}

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

לפני. הקובץ functions/package.json של התוסף הוא פרטי, מציין את מזהה התוסף ומצהיר על firebase-functions כיחסי תלות ישירים:

{
  "name": "firestore-bigquery-export",
  "main": "lib/index.js",
  "private": true,
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^6.3.2"
  }
}

אחרי. חבילה שניתן לפרסם: שם מוגדר, מפה של exports, ו-firebase-functions הועבר אל peerDependencies:

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.1.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": "22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.4.0"
  },
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^7.4.0"
  }
}

3. שדרוג פונקציות מהדור הראשון לדור השני

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

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

לפני. דור ראשון:

import * as functions from "firebase-functions/v1";

export const sync = functions.firestore
  .document("{collectionId}/{documentId}")
  .onWrite(async (change, context) => {
    await handleWrite(change.before, change.after, context.params);
  });

אחרי. דור שני:

import { onDocumentWritten } from "firebase-functions/firestore";

export const syncV2 = onDocumentWritten(
  { document: "{collectionId}/{documentId}" },
  async ({ change, context }) =>
    await handleWrite(change.before, change.after, context.params)
);

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

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

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

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

defineString("DATABASE_REGION", {
  label: "Firestore Instance Location",
  description:
    "Where is the Firestore database located? You can check your current database location at https://console.cloud.google.com/firestore/databases. The functions in this kit deploy to the Cloud Run region closest to this location.",
  input: select({
    "Multi-region (Europe - Belgium and Netherlands)": "eur3",
    "Multi-region (United States)": "nam5",
    "Multi-region (Iowa, North Virginia, and Oklahoma)": "nam7",
    "Iowa (us-central1)": "us-central1",
    // More locations...
  })
});

// Firestore multi-region locations are not Cloud Run regions; deploying a
// function to one hard-fails, so they map to a region inside the multi-region.
const MULTI_REGION_TO_FUNCTION_REGION: Record<string, string> = {
  nam5: "us-central1",
  nam7: "us-central1",
  eur3: "europe-west1",
};

/**
 * Maps a Firestore database location to the Cloud Run region the functions
 * should deploy to. The lookup is case-insensitive and ignores surrounding
 * whitespace, as the CLI's own region handling is. Regional locations pass
 * through lowercased; an unset or blank location returns `undefined`, meaning
 * the functions declare no region.
 */
export function firestoreLocationToFunctionRegion(
  location: string | undefined
): string | undefined {
  const normalized = location?.trim().toLowerCase();
  if (!normalized) {
    return undefined;
  }
  return MULTI_REGION_TO_FUNCTION_REGION[normalized] ?? normalized;
}

const functionRegion = firestoreLocationToFunctionRegion(
  process.env.DATABASE_REGION
);

export const fsexportbigquery = onDocumentWritten(
  {
    region: functionRegion,
    // Other configuration
  },
  (event) => handleDocumentWrite(event, getHandlerContext())
);

בפריסה הראשונה של הערכה, המשתמשים יתבקשו להזין את DATABASE_REGION והפונקציות ייפרסו ב-functionRegion המתאים שלמעלה, כדי לתקן בעיות במיקום של הפונקציות שמופעלות על ידי אירועים בדור השני.

4. המרת פרמטרים וסודות של תוספים

פרמטרים

כל פרמטר שמצהירים עליו ב-extension.yaml הופך לפרמטר של Cloud Functions.

המרת קריאות ישירות של הסביבה:

const collectionPath = process.env.COLLECTION_PATH;

לתוך Cloud Functions פרמטרים:

import { defineString } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const collectionPath = defineString("COLLECTION_PATH");

// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
  { document: collectionPath },
  async (event) => {
    // Call .value() to read the string inside a handler
    const path = collectionPath.value();
    await handleWrite(path, event);
  }
);

משתמשים ב-collectionPath.value() כדי לקרוא את המחרוזת בתוך handler, ומשתמשים ב-collectionPath ישירות במקום שבו צפוי פלייסהולדר, כמו נתיב טריגר של פונקציה.

ה-CLI של Firebase מגלה את הפרמטרים וקורא את הערכים שלהם מ-.env, מ-.env.<projectId> או מציג בקשות למשתמשים במהלך הפריסה. חשוב להשתמש באותם שמות של פרמטרים כדי שהערכים מההתקנה הקיימת יועברו.

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

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

לפני. פרמטר שהוצהר ב-extension.yaml, נקרא כמשתנה סביבה גולמי ב-config.ts:

# extension.yaml
- param: COLLECTION_PATH
  label: Collection path
  type: string
  required: true
// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,

אחרי. ‫defineString אחד; ה-CLI מגלה אותו וקורא מ-.env:

// src/config.ts
import { defineString } from "firebase-functions/params";

collectionPath: defineString("COLLECTION_PATH", {
  label: "Collection path",
  // We now support "nonEmpty: true" to ensure a value other than the empty string
  // is entered, analogous to "required: true" in extension.yaml
  input: { text: { nonEmpty: true } }
}),

שם הפרמטר לא השתנה, כך ש-.env קיים ממשיך לפעול.

מזהה מופע

התוספים קוראים את מזהה המופע שלהם מ-EXT_INSTANCE_ID, שמוזרק על ידי סביבת זמן הריצה של התוספים. ערכות פונקציות קוראות את מזהה המכונה שלהן מ-FIREBASE_KIT_INSTANCE_ID, שמוגדר על ידי ה-CLI של Firebase לכל מכונה של ערכה למפתח של המכונה במפה instances ב-firebase.json. ה-CLI מספק אותו במהלך הגילוי בזמן הפריסה, באמולטור ובפונקציות שנפרסו.

מזהה המכונה הוא לא פרמטר, אז אל תצהירו עליו באמצעות defineString. למעשה, FIREBASE_... היא תחילית שמורה בקובצי .env, כך שהמשתמשים לא יוכלו להגדיר אותה או לשנות אותה שם. הערכים שה-CLI מוסיף לא גלויים למערכת הפרמטרים. לקרוא אותו ישירות מהסביבה:

// Before
const instanceId = process.env.EXT_INSTANCE_ID;

// After
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

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

דוגמה מעשית: מחיקת נתוני משתמשים

(התוסף Stream Cloud Firestore to BigQuery לא קורא את מזהה המכונה שלו, אז אין מה להעביר שם. התוסף Delete User Data משתמש בו כדי לתת שמות לנושאי Pub/Sub שלו).

לפני. לקרוא כמשתנה סביבה גולמי ב-config.ts עם הקידומת ext- שבה משתמשים בתוספים למשאבים שלהם:

// functions/src/config.ts
discoveryTopic: `ext-${process.env.EXT_INSTANCE_ID}-discovery`,
deletionTopic: `ext-${process.env.EXT_INSTANCE_ID}-deletion`,

אחרי. קריאה פשוטה של process.env של FIREBASE_KIT_INSTANCE_ID שמשמשת לשני פרמטרים רגילים כדי שהמשתמשים יוכלו לשנות את שמות הנושאים:

// src/config.ts
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;

// Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
// discovery without freezing an empty topic name into the manifest.
discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
  default: `kit-${instanceId}-discovery`,
}),
deletionTopicName: defineString("DELETION_TOPIC_NAME", {
  default: `kit-${instanceId}-deletion`,
}),

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

// ...
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
if (!instanceId) {
  throw new Error(
    "FIREBASE_KIT_INSTANCE_ID is not set. It is provided automatically to " +
      "kit instances by firebase-tools >= 15.32.0; deploy or emulate this " +
      "kit with a supported CLI version."
  );
}
// ...

הבדיקה הזו פועלת כשה-handler פותר את ההגדרות שלו בפעם הראשונה, כך שמשתנה חסר מייצר שגיאת זמן ריצה ברורה במקום פונקציות שקשורות באופן שקט לנושאי kit-undefined-*. כדי לדחות את הפריסה עצמה, צריך לבצע את הבדיקה ברמת המודול כדי שהיא תפעל במהלך הגילוי. מכיוון שה-CLI שואב את מזהה המכונה מ-firebase.json, אין INSTANCE_ID שניתן להגדרה, ואין צורך לסנכרן בין כמה מכונות.

סודות

ב-extension.yaml, אתם מצהירים על סודות באמצעות type: secret. סביבת זמן הריצה של התוספים מאחסנת ומקשרת אותם, כך שקוד התוסף יכול לקרוא את process.env.PARAM_NAME ישירות. בבסיס קוד אופייני של Cloud Functions, מצהירים על כל סוד ומקשרים אותו באופן מפורש:

import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";

const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);

אחרי שהתוסף מועבר לחבילה או לערכה של npm, ההפניות לסודות מנוהלות בקובץ .env של משתמש הקצה. חשוב לא לשנות את שמות הסודות שהצהרתם עליהם בקוד בכלל. במהלך ההעברה, הסודות של משתמשי הקצה מועברים בהתאם.

דוגמה מעשית: הפעלת אימייל מ-Cloud Firestore

לפני. המשתנים MAIL_COLLECTION ו-SMTP_PASSWORD נקראים כמשתני סביבה גולמיים ב-config.ts:

# extension.yaml
- param: MAIL_COLLECTION
  label: Email documents collection
  type: string
  default: mail
  required: true

- param: SMTP_PASSWORD
  label: SMTP password
  type: secret
// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,

אחרי. קובץ defineString אחד וקובץ defineSecret אחד. ה-CLI מזהה את שניהם וקורא מ-.env:

import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const mailCollection = defineString("MAIL_COLLECTION", {
  label: "Email documents collection",
  default: "mail"
});

const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });

export const processQueue = onDocumentWritten(
  { document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
  async (event) => {
    const collection = mailCollection.value();
    const password = smtpPassword.value();
    // ...
  }
);

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

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

בגרסאות קודמות של Admin SDK, התוספים היו צריכים להעביר את מזהה המופע של התוסף כפרמטר שני כדי לטרגט פונקציה של תור משימות באותו תוסף. החל מגרסה 14.2.0 של firebase-admin, זה לא נדרש ולא מומלץ. כברירת מחדל, Task Queue API מטרגט עכשיו תורי משימות באותו הקשר (לדוגמה, תוסף או ערכה). אפשר ומומלץ להסיר את הפרמטר הזה מהקוד, גם כתוסף וגם כפונקציות נפרדות. הסרת הפרמטר הזה מבטיחה ניידות ותאימות קדימה.

כל שאר הפרטים של הקריאה להוספה לתור – נתיב המשאב של locations/<region>/functions/<name>, המטען הייעודי (payload) של המשימה והלוגיקה של ניסיון חוזר – נשארים ללא שינוי.

במאמר הוספת פונקציות לתור באמצעות Cloud Tasks מוסבר איך להוסיף פונקציות לתור באמצעות Cloud Tasks.

לפני. תוסף מהדור הראשון:

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${config.location}/functions/syncBigQuery`,
  process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);

אחרי. תוסף מהדור השני:

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${process.env.FUNCTION_REGION}/functions/syncBigQuery`
);
await queue.enqueue(taskData);

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

6. הצהרה על ממשקי ה-API ותפקידי ה-IAM הנדרשים

מעבירים את דרישות ה-IAM וה-API של התוסף מ-extension.yaml לקוד:

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");

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

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

לפני. הוצהר ב-extension.yaml; סביבת זמן הריצה של התוספים הפעילה את ה-API והעניקה את התפקידים לחשבון מנוהל:

apis:
  - apiName: bigquery.googleapis.com
roles:
  - role: bigquery.dataEditor
  - role: datastore.user
  - role: bigquery.user

אחרי. מוצהר בקוד באמצעות requiresAPI ו-requiresRole:

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI(
  "bigquery.googleapis.com",
  "Needed to write changelog rows and views"
);
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");

אם התוסף מפרסם אירועים של Eventarc, צריך גם להגדיר את התפקידים וממשקי ה-API הנדרשים לפרסום אירועים. בעבר, התוספים טיפלו בזה בלי שהיה צורך לבצע שינויים בקובץ extensions.yaml. אפשר לעשות את זה באופן מותנה בקוד, כך שהערכה תבקש את ההרשאות האלה רק כשמשתמשים בערוץ Eventarc בהתאמה אישית.

if (!!process.env.EVENTARC_CHANNEL) {
  requiresRole("roles/eventarc.publisher");
  requiresAPI(
    "eventarcpublishing.googleapis.com",
    "Publishes the extension's custom events to its Eventarc channel."
  );
}

7. המרת הוקים של מחזור חיים

אם התוסף קורא ל-getExtensions().runtime() (לדוגמה, setProcessingState או setFatalError), צריך למחוק את הקריאות האלה, כי הן גורמות לשגיאה אם הן נקראות מפונקציה מהדור השני שנפרסה באופן רגיל. מצב מחזור החיים מנוהל עכשיו על ידי afterFirstDeploy ו-afterRedeploy, שבהם לא נעשה שימוש במעקב אחרי המצב הזה.

‫Firebase Extensions יכול להפעיל את ההגדרה כשמשתמש מתקין, מעדכן או מגדיר מחדש תוסף. בחבילת ה-npm, מצהירים בקוד על פעולות מקבילות במחזור החיים.

להגדרה חד-פעמית:

import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";

export const runInitialSetup = onTaskDispatched(async (request) => {
  await initializeResources(request.data);
});

afterFirstDeploy({
  task: {
    function: "runInitialSetup",
    body: {}
  }
});

לעדכונים של הגדרות אישיות או קוד:

import { afterRedeploy } from "firebase-functions/lifecycle";

afterRedeploy({
  task: {
    function: "runInitialSetup",
    body: { reconcile: true }
  }
});

הפעולות במחזור החיים צריכות להיות אידמפוטנטיות. יכול להיות שהמשתמשים יצטרכו להריץ אותם שוב באופן ידני אם השליחה או ההפעלה נכשלו:

firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

לפני. ‫lifecycleEvents ב-extension.yaml, שמופעל על ידי סביבת זמן הריצה של התוספים:

lifecycleEvents:
  onInstall:
    function: initBigQuerySync
    processingMessage: Configuring BigQuery Sync.
  onUpdate:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync
  onConfigure:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync

אחרי. מוצהר בקוד; המשימה מקצה את BigQuery בפריסה הראשונה:

import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";

afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });

ההקצאה היא אידמפוטנטית, כך שהפעלה מחדש מתאימה בין מערך הנתונים, הטבלה והתצוגות. המשתמשים יכולים להפעיל מחדש באופן ידני באמצעות firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME.

8. הגדרת מסמכים למשתמשים

כותבים README של חבילה שמסביר לפחות:

  • ערכי ה-.env שהחבילה דורשת.
  • הסודות שהחבילה דורשת, ואיך להעביר ערכי סודות קיימים.
  • תפקידי ה-IAM שהחבילה מצהירה עליהם באמצעות requiresRole(...).
  • ממשקי ה-API של Google שהחבילה מפעילה או דורשת.
  • ה-lifecycle hooks שהחבילה מצהירה עליהם, ואיך להריץ אותם מחדש באופן ידני.
  • הערות בנוגע לחיוב.
  • מה השתנה בהשוואה לתוסף המקורי.
  • איך החבילה מקבלת את מזהה המכונה שלה (FIREBASE_KIT_INSTANCE_ID שמוגדר על ידי ה-CLI) ואיך כל הפונקציות של המכונה נפרסות עם הקידומת kit-<instanceId>-.

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

החבילה README כוללת טבלה קונקרטית של "מה השתנה":

בעיה כמו התוסף בתור @firebase-function-kits/firestore-bigquery-export
הגדרה פרמטרים של תוספים ‫Cloud Functions פרמטרים דרך .env
IAM ניתנה על ידי תוספים ‫requiresRole(...), מוחל בפריסה
ניהול תצורה משימה במחזור החיים לפי תוספים משימה אחת (afterFirstDeploy מתוך afterRedeploy)
שמות הפונקציות ext-<instanceId>-fsexportbigquery ‫fsexportbigquery (אפשר להוסיף קידומת)
מזהה מופע EXT_INSTANCE_ID שהוחדרו על ידי תוספים ‫FIREBASE_KIT_INSTANCE_ID, הוגדר על ידי ה-CLI מ-firebase.json

9. בדיקת הפונקציה מהדור השני

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

כדי להפעיל את setGlobalOptions להגדרת אפשרויות גלובליות כמו אזור או מעבד (CPU) שמוגדרים כברירת מחדל, צריך לעשות זאת רק כשפורסים את הערכה כפונקציה עצמאית מהדור השני. כשהערכה מותקנת כחבילת npm, המשתמשים קוראים ל-setGlobalOptions בקוד העטיפה שלהם כדי להגדיר את הפרמטרים האלה, והם יקבלו אזהרות אם זה יקרה פעמיים. כדי להגן על הקריאה הזו, אפשר לבדוק את משתנה הסביבה FIREBASE_KIT_INSTANCE_ID:

import { setGlobalOptions } from "firebase-functions";

if (!process.env.FIREBASE_KIT_INSTANCE_ID) {
  setGlobalOptions({
    region: "us-east1",
    maxInstances: 10,
  });
}

חשוב לוודא שאתם משתמשים ב-firebase-tools >= 15.32.0, ולפרוס את הפונקציה שהומרה לדור השני בפרויקט בדיקה עם המשאבים המתאימים כדי לבדוק את ההתנהגות שלה. אם כבר הגדרתם פרויקט לבדיקה של התוסף, מריצים את הפקודה הבאה:

firebase deploy --only functions

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

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

אנחנו מאמתים את הסנכרון בין Cloud Firestore ל-BigQuery מקצה לקצה:

  1. בדף Cloud Firestore במסוף Firebase, יוצרים את האוסף שהגדרתם בתור COLLECTION_PATH (users), אם הוא עדיין לא קיים.
  2. יוצרים מסמך בשם bigquery-mirror-test שמכיל שדות עם ערכים כלשהם.
  3. בדף BigQuery במסוף Google Cloud, שולחים שאילתה לטבלת יומן השינויים הגולמי. הוא צריך להכיל שורה אחת שמתעדת את יצירת המסמך:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`
    
  4. שולחים שאילתה לתצוגה האחרונה, שאמורה להחזיר את אירוע השינוי האחרון של המסמך היחיד שקיים (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`
    
  5. מוחקים את המסמך bigquery-mirror-test ב-Cloud Firestore. הוא נעלם מהתצוגה האחרונה, ואירוע DELETE נוסף לטבלת יומן השינויים הגולמי.

    אתם יכולים לבדוק את ההיסטוריה המלאה של מסמך אחד באמצעות:

    SELECT *
       FROM `PROJECT_ID.analytics.users_raw_changelog`
       WHERE document_name = "bigquery-mirror-test"
       ORDER BY timestamp ASC
    

ההבדלים בין בדיקת התוסף לבין בדיקת האתר:

  • הטריגר נפרס בתור fsexportbigquery (ללא קידומת כשפורסים כפונקציה רגילה מהדור השני ולא כערכה), ולא בתור ext-<instanceId>-fsexportbigquery. חפשו את השם הזה בלוח הבקרה וביומנים של Cloud Functions.
  • הקוד פועל עכשיו ב-Firebase Local Emulator Suite כפונקציות רגילות. אפשר להגדיר את ערך הפרמטרים לשימוש באמולטור באמצעות .env.local. אפשר גם לבצע בדיקת יחידה (unit test) של הקוד באמצעות ה-SDK של firebase-functions-test, כפי שמתואר במאמר בדיקת יחידה של Cloud Functions.
  • ההקצאה לא מנוהלת יותר על ידי סביבת זמן הריצה של התוספים. אם טבלת יומן השינויים חסרה אחרי הפריסה, צריך להריץ מחדש את משימת ההגדרה באופן ידני: firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME. המשימה היא אידמפוטנטית, כך שהרצה חוזרת שלה מתאימה בין מערך הנתונים, הטבלה והתצוגות.
  • ערכי הפרמטרים מגיעים מ-.env ולא מטופס ההתקנה, כך שהפעלות חוזרות של firebase deploy לא יהיו אינטראקטיביות אחרי ש-.env יושלם.

10. פרסום ערכת הפונקציות ב-npm

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

אחרי שהערכה תפורסם ב-npm, אפשר יהיה להתקין אותה באמצעות firebase functions:kits:install והיא תופיע כתחליף הרשמי לתוסף.

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

לפני הפרסום:

  1. בוחרים שם לחבילה. אפשר להשתמש בשמות עם או בלי היקף (ראו את המדריכים למעלה). שימו לב שחבילות מוגדרות כפרטיות כברירת מחדל, אז צריך להעביר את --access public.
  2. בונים ובודקים את מה ששולחים. הנתיבים main ו-types מצביעים על הפלט המקומפל (lib/ בדוגמה שלנו), ולכן צריך לכלול את הספרייה הזו בקובץ ה-tar שפורסם. משתמשים ב-.npmignore או ברשימת היתרים של files, ובודקים את התוצאה באמצעות npm pack --dry-run. סקריפט prepublishOnly שמריץ את ה-build מונע פרסום של פלט לא עדכני.

package.json תוספות שהופכות את הפרסום לבטוח כברירת מחדל:

{
  "files": ["lib", "README.md", "CHANGELOG.md"],
  "publishConfig": { "access": "public", "tag": "next" },
  "scripts": {
    "build": "tsc -b",
    "prepublishOnly": "npm run build && npm test"
  }
}

השדה "publishConfig": { "tag": "next" } מבטיח ש-npm publish פשוט אף פעם לא יחליף את latest.

יצירת גרסה מועמדת להפצה:

לדוגמה, כדי להגדיל את הגרסה באופן מקומי מ-0.0.2-rc.3 ל-0.0.2-rc.4 (הפעולה הזו מבצעת commit ומתייגת ב-Git אם package.json נמצא ברמה הבסיסית (root) של המאגר):

npm version prerelease --preid rc

כדי לפרסם את הגרסה המועמדת להפצה ולרשום את @your-org/your-kit@0.0.2-rc.4 ב-npm עם התג next:

npm publish

יכול להיות שיעברו כמה דקות עד שהגרסה החדשה תופיע באתר npm. הפקודה npm view קוראת את המרשם ישירות:

npm view @your-org/your-kit versions dist-tags

אחרי שתסיימו את שלב 11 ושלב 12 במדריך הזה, תוכלו לקדם את החבילה לגרסה יציבה:

npm version 0.0.2
npm publish --tag latest
npm dist-tag add @your-org/your-kit@0.0.2 next

הערה לגבי npm-shrinkwrap.json: מומלץ מאוד לכלול קובץ npm-shrinkwrap.json בחבילה. אם לא תעשו את זה, ה-CLI יציג למשתמשים אזהרה בזמן ההתקנה. כך אפשר לוודא שהמשתמשים משתמשים בדיוק ביחסי התלות שבדקתם, ולהגן מפני התקפות על שרשרת האספקה. עם זאת, קובץ shrinkwrap מוחל באופן מילולי בפרויקטים של המשתמשים, כולל במהלך ה-build של Cloud Functions (npm ci), שבו רשומות לפיתוח בלבד עלולות להיכשל עם EBADPLATFORM. יכול להיות שתצטרכו להסיר את הרשומות של "dev": true ו-devDependencies מהעותק של shrinkwrap שפורסם.

דוגמה מעשית: העברת נתונים בסטרימינג מ-Cloud Firestore אל BigQuery

ה-package.json של הערכה בזמן הגרסה המועמדת הרביעית להפצה:

{
  "name": "@firebase-function-kits/firestore-bigquery-export",
  "version": "0.0.2-rc.4",
  "repository": {
    "type": "git",
    "url": "https://github.com/firebase/extensions.git",
    "directory": "kits/firestore-bigquery-export"
  },
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "engines": { "node": "22" },
  "scripts": { "build": "tsc -b" }
}

שימו לב שבמקרה הזה, הערכה נמצאת במונוריפו, ולכן חשוב לכלול את repository.directory כדי שהקישור למרשם של npm יפנה לתיקייה הנכונה. הערך CHANGELOG.md מכיל הערות לגבי הגרסה הממתינה.

11. בדיקה כערכת פונקציות

אחרי שמפרסמים את הערכה, מומלץ לבדוק אותה באמצעות npm.

מוודאים שאתם משתמשים בגרסה >= 15.32.0 של firebase-tools ומתקינים את הערכה:

firebase functions:kits:install --package <your-package-name>@<your-prerelease-version>

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

firebase deploy --only functions:<your-kit-instance-id>

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

מאמתים שוב את הערכה לפי ההוראות בשלב 9. בודקים את הפונקציה מהדור השני. עכשיו, כשאתם פורסים באמצעות ערכות, לפונקציות שלכם יש קידומת והן נקראות kit-<instance-id>-<method-name>. כך אפשר ליצור כמה מופעים של ערכות, ולפרוס את אותה פונקציה כמה פעמים בפרויקט, כל פעם עם שם ייחודי.

12. החלפת ההעברה לבדיקה

אתם יכולים להגדיר מופע של תוסף פעיל ואז להשתמש במדריך להעברת נתונים (מיגרציה) (באמצעות firebase ext:migrate --package או פקודות ה-CLI של ערכות הפונקציות) כדי לסיים את בדיקת ערכת הפונקציות כתחליף להעברת נתונים.

13. הודעה למשתמשים ול-Google על התוסף הרשמי שמחליף את התוסף הקודם

אחרי שערכת הפונקציות החלופית מוכנה וזמינה כחבילת npm שהמשתמשים צריכים לעבור אליה, צריך להודיע למשתמשים ול-Google על החלופה הרשמית הזו. מעדכנים את הקובץ README.md במאגר ב-GitHub שמארח את התוסף, עם הפרטים הבאים:

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="<your-extesion-id>" package="<your-npm-package-name>" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `<your-extension>` is deprecated. Migrate to the [<your-npm-package-name>](<link-to-your-npm-package>) package.

‫Google סורקת קובצי README של תוספים מוכרים כדי למצוא הערות כמו <!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->, ומשתמשת בהן כדי לאכלס את המאגר הרשמי של ההחלפות שמאוחסנות במאגר firebase-tools בתור replacements.json. אפשר גם לבדוק את replacements.json כדי לראות אילו README.md ייסרקו בשביל התוסף. הרשימה הרשמית של החלופות מתעדכנת מדי שבוע.

דוגמה מעשית: העברת נתונים מ-Cloud Firestore אל BigQuery

התוסף firestore-bigquery-export README.md מכיל:

<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `firebase/firestore-bigquery-export` is deprecated. Please migrate to the [`@firebase-function-kits/firestore-bigquery-export`](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export) package.