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

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

    כשמציינים פרמטר מהסוג הזה, המשתמשים מקבלים בווידג'ט הבחירה בממשק המשתמש של ההתקנה אפשרות בחירה ידידותית יותר. לכן, מומלץ להשתמש בפרמטרים מסוג 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, ברירת המחדל של אפשרות הרשימה היא הצגה של value.
resourceType
(נדרש אם הפרמטר type הוא selectResource) 		מחרוזת

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

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

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

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

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

הביטוי הרגולרי (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 של המשתמש
  • אם נתיב מסד הנתונים שצוין קיים במסד הנתונים של המשתמש

עם זאת, כשהתוסף פורס את המשאבים שלו, במסוף 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 תוויות להחלה על כל המשאבים בתוסף