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

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

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

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

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

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

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

אם לא כוללים את immutable, ברירת המחדל של הערך הזה היא false.

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

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

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

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

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