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

פרמטרים הם המנגנון שבאמצעותו משתמש יכול להתאים אישית כל מופע מותקן של תוסף. פרמטרים דומים למשתני הסביבה של תוסף. הערכים של הפרמטרים יכולים להיות מאוכלסים אוטומטית (מסופקים על ידי 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 (כמו קטגוריית Storage ברירת המחדל) או שהם ספציפיים לתוסף (כמו מזהה המופע של התוסף).

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

למרות ש-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 (string): הערך בפועל של האפשרות שאפשר לבחור

השדה value הוא חובה בשדה options.
אם לא מציינים את label, ברירת המחדל של האפשרות list היא הצגה של value.
resourceType
(נדרש אם הפרמטר type הוא selectResource) 		מחרוזת

סוג משאב Firebase שהמשתמש יתבקש לבחור. בשלב הזה, רק מאגרי Cloud Storage תומכים בבוררי משאבים:

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

המערכת תתעלם מערכים לא ידועים של resourceType וממשק המשתמש יציג את הפרמטר כשדה קלט string חופשי.
example
(אופציונלי) 		מחרוזת

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מומלץ מאוד להודיע למשתמשים בקובץ 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 תוויות להחלה על כל המשאבים בתוסף