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

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

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

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

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

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

כשמגדירים פרמטר עם הערך 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 Connector 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 תוויות שיוחלו על כל המשאבים בתוסף