הגדרה של פרמטרים בתוסף ושימוש בהם

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

הפרמטרים האלה זמינים להפניה בקוד המקור של הפונקציות של התוסף, בקובץ extension.yaml ובקובץ POSTINSTALL.md. כך נראה התחביר להפניה לפרמטר שנקרא PARAMETER_NAME:

  • בקוד המקור של הפונקציות, משתמשים במודול params (לדוגמה, params.defineInt("PARAMETER_NAME")) או ב-process.env.PARAMETER_NAME.

  • ב-extension.yaml וב-POSTINSTALL.md, משתמשים ב-${param:PARAMETER_NAME}.

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

פרמטרים שמאוכלסים באופן אוטומטי

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

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

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

הפניה לפרמטר שמאוכלס באופן אוטומטי תיאור ערך הפרמטר (שסופק על ידי Firebase)
פרמטרים עם ערכי ברירת מחדל מהפרויקט ב-Firebase
PROJECT_ID המזהה הייחודי של הפרויקט ב-Firebase שבו התוסף מותקן

פורמט כללי:
project-id

ערך לדוגמה:
project-123

DATABASE_URL כתובת ה-URL של מכונת Realtime Database המוגדרת כברירת מחדל בפרויקט Firebase

פורמט כללי:
https://project-id-default-rtdb.firebaseio.com
(מופעים בארה"ב)
או
https://project-id-default-rtdb.region-code.firebasedatabase.app
(מופעים מחוץ לארה"ב)

ערך לדוגמה:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

שם המכונה כברירת מחדל של Realtime Database בפרויקט Firebase

בדרך כלל הערך הזה זהה למזהה הפרויקט, או מסתיים ב--default-rtdb.

פורמט כללי:
project-id

ערך לדוגמה:
project-123

STORAGE_BUCKET שם הקטגוריה המוגדרת כברירת מחדל ב-Cloud Storage של פרויקט Firebase

פורמט כללי:
PROJECT_ID.firebasestorage.app

ערך לדוגמה:
project-123.firebasestorage.app

פרמטר עם ערך ברירת מחדל מהתקנת התוסף
EXT_INSTANCE_ID

מזהה ייחודי של מופע התוסף המותקן

הערך הזה נוצר מהשדה name שצוין בקובץ extension.yaml.

פורמט כללי למופע הראשון שהותקן (מוקצה באופן אוטומטי על ידי Firebase; לא ניתן לשינוי על ידי המשתמש במהלך ההתקנה):
name-from-extension.yaml

ערך לדוגמה:
my-awesome-extension


פורמט כללי למופע השני של ההתקנה ומעלה (מוקצה באופן אוטומטי על ידי Firebase; המשתמש יכול לשנות אותו במהלך ההתקנה):
name-from-extension.yaml-4-digit-alphanumeric-hash

ערך לדוגמה:
my-awesome-extension-6m31

פרמטרים שהמשתמש הגדיר

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

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

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

בקטע params בקובץ extension.yaml, משתמשים בשדות הבאים כדי להגדיר פרמטר שמוגדר על ידי המשתמש:

שדה סוג תיאור
param
(חובה)
מחרוזת שם הפרמטר
label
(חובה)
מחרוזת

תיאור קצר של הפרמטר

מוצג למשתמש כשהוא מתבקש להזין את הערך של הפרמטר

description
(אופציונלי)
מחרוזת

תיאור מפורט של הפרמטר

מוצג למשתמש כשהוא מתבקש להזין את הערך של הפרמטר

תמיכה ב-Markdown

type
(אופציונלי)
מחרוזת

מנגנון הקלט שבאמצעותו המשתמש מגדיר את ערך הפרמטר (לדוגמה, הזנת טקסט ישירות או בחירה מתוך רשימה נפתחת)

הערכים התקינים כוללים:

  • ‫string: מאפשרת להזין טקסט חופשי (בכפוף למגבלות של validationRegex)
  • ‫select: מאפשר לבחור רשומה אחת מתוך רשימה מוגדרת מראש של אפשרויות. אם מציינים את הערך הזה, צריך להגדיר גם את השדה options.
  • ‫multiSelect: מאפשר לבחור רשומה אחת או יותר מרשימה מוגדרת מראש של אפשרויות. אם מציינים את הערך הזה, צריך להגדיר גם את השדה options.
  • ‫selectResource: מאפשרת לבחור סוג ספציפי של משאב Firebase (כמו קטגוריית Cloud Storage) מהפרויקט של המשתמש.

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

    אם מציינים את הערך הזה, צריך להגדיר גם את השדה resourceType.

  • ‫secret: מאפשר לאחסן מחרוזות רגישות, כמו מפתחות API לשירותים של צד שלישי. הערכים האלה יאוחסנו ב-Cloud Secret Manager.

    ‫Cloud Secret Manager הוא שירות בתשלום, והשימוש בו עלול לגרום לחיובים למשתמשים שמתקינים את התוסף. אם אתם משתמשים בסוג הפרמטר secret, חשוב לתעד בקובץ PREINSTALL שהתוסף משתמש ב-Cloud Secret Manager.

אם משמיטים את השדה הזה, הפרמטר מקבל את ערך ברירת המחדל type של string.

options
(חובה אם הפרמטר type הוא select או multiSelect)
list

רשימת ערכים שהמשתמש יכול לבחור מתוכה

כוללים את השדות label ו-value בשדה options:

  • label (מחרוזת): תיאור קצר של האפשרות שאפשר לבחור
  • ‫value (מחרוזת): הערך בפועל של האפשרות שניתן לבחור.

השדה value נדרש בשביל השדה options.
אם משמיטים את label, אפשרות הרשימה מוגדרת כברירת מחדל להצגת value.

resourceType
(חובה אם הפרמטר type הוא selectResource)
מחרוזת

סוג המשאב ב-Firebase שהמשתמש יתבקש לבחור. נכון לעכשיו, רק קטגוריות של Cloud Storage תומכות בבוררי משאבים:

סוג המשאב מזהה הסוג
קטגוריה אחת (Cloud Storage) storage.googleapis.com/Bucket

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

example
(אופציונלי)
מחרוזת

ערך לדוגמה של הפרמטר

validationRegex
(אופציונלי)
(רלוונטי רק כשהפרמטר type הוא string)
מחרוזת

מחרוזת של ביטוי רגולרי לאימות הערך של הפרמטר שהמשתמש הגדיר

הביטוי הרגולרי עובר קומפילציה באמצעות ספריית go: ‏RE2

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

validationErrorMessage
(אופציונלי)
מחרוזת

הודעת השגיאה שתוצג אם validationRegex נכשל

למידע נוסף על הודעות שגיאה, עיינו בקטע אימות והודעות שגיאה שבהמשך.

default
(אופציונלי)
מחרוזת

ערך ברירת המחדל של הפרמטר אם המשתמש משאיר את ערך הפרמטר ריק

אם רלוונטי, אפשר לציין ערך של פרמטר שמאוכלס באופן אוטומטי לערך של default (לדוגמה, אפשר לעיין בפרמטר IMG_BUCKET של התוסף Resize Images).

required
(אופציונלי)
בוליאני

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

אם משמיטים את required, ערך ברירת המחדל הוא true (כלומר, פרמטר חובה).

immutable
(אופציונלי)
בוליאני

ההגדרה קובעת אם המשתמש יכול לשנות את ערך הפרמטר אחרי ההתקנה (לדוגמה, אם הוא מגדיר מחדש את התוסף)

אם לא מציינים את immutable, ערך ברירת המחדל הוא false.

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

אימות והודעות שגיאה לגבי ערכים שהמשתמשים מגדירים

כשמגדירים פרמטר עם type של string, צריך להגדיר אימות מתאים של ביטויים רגולריים באמצעות השדה validationRegex של הפרמטר.

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

  • אם מסד הנתונים או הקטגוריה ב-Cloud Storage שצוינו מוגדרים בפרויקט Firebase של המשתמש
  • אם הנתיב שצוין למסד הנתונים קיים במסד הנתונים של המשתמש

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

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

פרמטרים של המערכת

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

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

עם זאת, אם לתוסף יש דרישות מיוחדות למשאבים, אתם יכולים להגדיר ערכים ספציפיים ברמת המשאב בקובץ extension.yaml. הגדרות אלה לכל משאב יחליפו את ההגדרות של המשתמש לכל המופעים של התוסף. לדוגמה:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

אלה הפרמטרים הזמינים של המערכת:

שם תווית (ידידותית למשתמש) השדה התואם ב-properties תיאור
firebaseextensions.v1beta.function/location מיקום location באיזה אזור צריך לפרוס את Cloud Functions?
firebaseextensions.v1beta.function/memory זיכרון לפונקציות memory כמה מגה-בייט של זיכרון צריך להקצות לכל פונקציה?
firebaseextensions.v1beta.function/timeoutSeconds זמן קצוב לתפוגה של פונקציה timeout כמה שניות פונקציות צריכות לפעול לפני שהזמן הקצוב לתפוגה יסתיים?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings תעבורת נתונים יוצאת (egress) של מחבר VPC vpcConnectorEgressSettings שליטה בתנועה יוצאת כשמוגדר מחבר VPC
firebaseextensions.v1beta.function/vpcConnector מחבר VPC vpcConnector מקשר בין Cloud Functions למחבר VPC שצוין.
firebaseextensions.v1beta.function/minInstances מספר מינימלי של מכונות פונקציה minInstances המספר המינימלי של המופעים של הפונקציה הזו שיופעלו בבת אחת
firebaseextensions.v1beta.function/maxInstances מספר מקסימלי של מכונות פונקציה maxInstances המספר המקסימלי של מופעים של הפונקציה הזו שאפשר להריץ בו-זמנית
firebaseextensions.v1beta.function/ingressSettings הגדרות של תעבורת נתונים נכנסת (ingress) ingressSettings ההגדרה הזו קובעת מאיפה תתקבל תנועה נכנסת
firebaseextensions.v1beta.function/labels תוויות labels תוויות שיוחלו על כל המשאבים בתוסף