קובץ עזר ל-extension.yaml

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

הטבלאות בדף הזה מתארות את השדות שזמינים בקובץ extension.yaml.

מידע בסיסי ופרטים אישיים מזהים

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
שדות בסיסיים
name
מחרוזת
(חובה)

מזהה התוסף.

יכול להכיל רק אותיות קטנות, מספרים ומקפים, עד 40 תווים.

הערה: הערך הזה משמש ליצירת מזהה המופע של התוסף (שמשמש לאחר מכן ליצירת השמות של חשבון השירות של התוסף והמשאבים הספציפיים לתוסף).

version
מחרוזת
(חובה)

גרסת התוסף.

חייב להיות בפורמט של ניהול גרסאות semver (לדוגמה, 1.2.0).
specVersion
מחרוזת
(חובה)

גרסת המפרט של התוספים ל-Firebase.

הערך הנוכחי: v1beta
license
מחרוזת
(אופציונלי)

רישיון לתוסף.

התוסף חייב להיות ברישיון של Apache-2.0.
billingRequired
boolean
(אופציונלי)

אם השירותים שבהם התוסף משתמש דורשים חשבון לחיוב ב-Firebase ברמת תשלום.

תמיד מוגדר כ-true.
displayName
מחרוזת
(אופציונלי)

שם תצוגה ידידותי לתוסף (3-5 מילים).

מגבלת תווים: 40.
description
מחרוזת
(אופציונלי) 		תיאור קצר של המשימה שהתוסף מבצע (בערך משפט אחד).
icon
מחרוזת
(אופציונלי)

קובץ שישמש כסמל של התוסף ב-extensions.dev ובמסוף Firebase.

הקובץ הזה צריך להיות קובץ PNG ריבועי בגודל שבין 512x512 ל-1,024x1,024 פיקסלים. צריך לשים את הקובץ באותה ספרייה שבה נמצא הקובץ extension.yaml. אי אפשר לציין ספריית משנה.

כשמעצבים סמל לתוסף, חשוב לזכור את ההנחיות הבאות:

  • בוחרים צבעים לרקע ולגרפיקה שמתאימים למותג.
  • השתמשו בצבעים פשוטים לסמל, עד 2 צבעים. שימוש בצבעים רבים עלול לגרום לסמל להיראות עמוס מדי.
  • מאותה סיבה, אל תשתמשו במעברי צבע בסמל. קשה להבחין במעברי צבעים בגדלים קטנים, והם הופכים את הסמל למורכב מבחינה חזותית.
  • השתמשו בתמונות פשוטות וייחודיות שמעבירות את הפונקציונליות של התוסף.
  • אם החברה שלכם מפתחת כמה תוספים, אל תשתמשו בלוגו שלכם כסמל. למשתמשים יהיה קשה להבחין בין התוספים שלך.
  • הגרפיקה צריכה להיות בולטת וברורה. אל תשתמשו בעיצובים עדינים או מורכבים, כי הם לא יוצגו בצורה טובה בגדלים קטנים.
  • אל תכללו מילים שמסבירות מה התוסף עושה. בדרך כלל, אי אפשר לקרוא את הטקסט כשהתמונה קטנה.
tags
רשימה של מחרוזות
(אופציונלי) 		תגים שיעזרו למשתמשים למצוא את התוסף. התגים הבאים ממופים לקטגוריות ב-Extensions Hub: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
מחרוזת
(אופציונלי) 		כתובת URL ציבורית שדרכה אפשר לגשת לספריית התוספים.
releaseNotesUrl
מחרוזת
(אופציונלי) 		כתובת URL ציבורית שבה אפשר לגשת להערות הגרסה של התוסף.
author
אובייקט אחד של מחבר
(אופציונלי)

היוצר הראשי ואיש הקשר של התוסף.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
שדות של מחברים
authorName
מחרוזת
(חובה)

שם המחבר.

הישות יכולה להיות אדם, חברה, ארגון וכו'.
email
מחרוזת
(אופציונלי) 		כתובת האימייל של המחבר.
url
מחרוזת
(אופציונלי) 		כתובת URL ציבורית שבה אפשר לגשת למידע על המחבר.
contributors
רשימה של אובייקטים מסוג author
(אופציונלי)

מחברים נוספים שתרמו לתוסף.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
שדות של מחברים
authorName
מחרוזת
(חובה)

שם המחבר.

הישות יכולה להיות אדם, חברה, ארגון וכו'.
email
מחרוזת
(אופציונלי) 		כתובת האימייל של המחבר.
url
מחרוזת
(אופציונלי) 		כתובת URL ציבורית שבה אפשר לגשת למידע על המחבר.

ממשקי API של Firebase ו-Google Cloud

בשדות האלה מצוינים ממשקי ה-API של Firebase ו-Google שבהם התוסף משתמש. כשהמשתמשים מתקינים את התוסף, הם יכולים לבחור להפעיל את ממשקי ה-API האלה באופן אוטומטי בפרויקט שלהם.

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
שדות API
apiName
מחרוזת
(חובה)

שם ה-API של Google

הערך צריך להתאים לשדה Service name כפי שהוא מופיע בדף הסקירה הכללית של כל API (דוגמה) בספריית ה-API של Google Cloud.

reason
מחרוזת
(חובה) 		תיאור קצר של הסיבה לכך שהתוסף צריך להשתמש ב-API הזה

תפקידי IAM

בשדות האלה מצוינים תפקידי Cloud IAM שהתוסף דורש. חשבון השירות שמוקצה לתוסף מקבל את התפקידים האלה.

אפשר לציין רק אחד מהתפקידים הנתמכים.

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
שדות של תפקידים
role
מחרוזת
(חובה)

שם התפקיד ב-IAM שנדרש כדי שהתוסף יפעל

חייב להיות אחד מהתפקידים הנתמכים

reason
מחרוזת
(חובה) 		תיאור קצר של הסיבה שבגללה התוסף צריך את הגישה שניתנת על ידי התפקיד הזה
resource
מחרוזת
(אופציונלי)

להגביל את היקף התפקיד למשאב הזה.

אם לא מציינים ערך, ברירת המחדל היא projects/${project_id}. צמצום היקף התפקידים

שירותים חיצוניים

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

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
שדות של שירותים חיצוניים
name
מחרוזת
(חובה) 		שם השירות החיצוני שנדרש כדי שהתוסף יפעל
pricingUri
מחרוזת
(חובה) 		URI למידע על תמחור השירות

פרמטרים שהמשתמש יכול להגדיר

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

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
שדות של פרמטרים
param
מחרוזת
(חובה) 		שם הפרמטר. אתם משתמשים בשם הזה כדי להפנות לערך הפרמטר בקוד.
label
מחרוזת
(חובה) 		תיאור קצר של הפרמטר. מוצג למשתמש כשהוא מתבקש להזין את הערך של הפרמטר.
description
מחרוזת
(אופציונלי)

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

יש תמיכה ב-Markdown.
example
מחרוזת
(אופציונלי) 		ערך לדוגמה של הפרמטר.
default
מחרוזת
(אופציונלי) 		ערך ברירת המחדל של הפרמטר אם המשתמש משאיר את ערך הפרמטר ריק.
validationRegex
מחרוזת
(אופציונלי) 		ביטוי רגולרי לאימות הערך שהמשתמש הגדיר לפרמטר. תחביר Google RE2.
validationErrorMessage
מחרוזת
(אופציונלי) 		הודעת השגיאה שתוצג אם האימות של הביטוי הרגולרי ייכשל.
required
boolean
(אופציונלי) 		ההגדרה הזו קובעת אם המשתמש יכול לשלוח מחרוזת ריקה כשהוא מתבקש להזין את ערך הפרמטר. ברירת המחדל היא true.
immutable
boolean
(אופציונלי)

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

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

פרמטרים שניתן לבחור ופרמטרים שניתן לבחור כמה מהם

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

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiSelect
    options:
      - value: red
      - value: green
      - value: blue
שדות של פרמטרים עם שאלות אמריקאיות
type
מחרוזת

select או multiSelect

מציין שהפרמטר יכול להיות ערך אחד (select) או כמה ערכים (multiSelect) שנבחרו מתוך קבוצה של אפשרויות מוגדרות מראש
options
רשימת אפשרויות
(חובה)

האפשרויות שהמשתמש יכול לבחור מתוכן

שדה אפשרויות
value
מחרוזת
(חובה) 		אחד מהערכים שהמשתמש יכול לבחור. זה הערך שמתקבל כשקוראים את ערך הפרמטר בקוד.
label
מחרוזת
(אופציונלי) 		תיאור קצר של האפשרות לבחירה. אם לא מציינים את הפרמטר, ערך ברירת המחדל הוא value.

פרמטרים של משאבים שאפשר לבחור

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

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
שדות של פרמטרים של משאבים
type
מחרוזת

selectresource

מציין שהפרמטר מייצג משאב של פרויקט
resourceType
מחרוזת
(חובה)

סוג המשאב שהמשתמש יתבקש לבחור.

הערכים האפשריים:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

עם זאת, כרגע רק לקטגוריות של Cloud Storage יש ממשק משתמש לבחירה (סוגי משאבים אחרים מוצגים כשדות להזנת טקסט חופשי).

פרמטרים סודיים

ערכים סודיים שהמשתמשים מספקים (כמו מפתחות API) מטופלים באופן שונה:

  • ערכי הסודות מאוחסנים באמצעות Cloud Secret Manager. רק לקוחות מורשים (כמו מופע מותקן של תוסף) יכולים לגשת לערכים האלה.
  • כשהמשתמשים מתבקשים לספק את הערכים האלה, הקלט שלהם לא מוצג.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
שדות של פרמטרים סודיים
type
מחרוזת

secret

מציין שהפרמטר הוא ערך סודי

משאבים של פונקציות Cloud Functions

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

פונקציות Cloud Functions מהדור הראשון

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
שדות של משאבים
name
מחרוזת
(חובה)

שם ידידותי למשתמש של הפונקציה שיוצאה.

אם לא מציינים את המאפיין entryPoint (ראו בהמשך), הערך הזה חייב להיות זהה לשם הפונקציה בקוד המקור של הפונקציות.

השם הסופי של הפונקציה שנפרסה יהיה בפורמט הבא: ext-extension-instance-id-name.
type
מחרוזת
(חובה) 		למשאב של פונקציה מהדור הראשון: firebaseextensions.v1beta.function
description
מחרוזת
(חובה)

תיאור קצר של המשימה שהפונקציה מבצעת בשביל התוסף.
properties
(חובה)

מאפיינים של פונקציות Cloud Functions מהדור הראשון. המאפיינים החשובים ביותר מפורטים בהמשך, אבל הרשימה המלאה מופיעה בחומר העזר של Cloud Functions.

נכסים
location
(אופציונלי)

המיקום שבו רוצים לפרוס את הפונקציה. ברירת המחדל היא us-central1
entryPoint
(אופציונלי) 		שם הפונקציה המיוצאת בקוד המקור של הפונקציות שהתוסף צריך לחפש. ברירת המחדל היא הערך של name שלמעלה.
sourceDirectory
(אופציונלי)

הספרייה שמכילה את package.json בתיקיית השורש שלה. הקובץ של קוד המקור של הפונקציות חייב להיות בספרייה הזו. ברירת המחדל היא functions

הערה: השדה main של package.json מציין את הקובץ של קוד המקור של הפונקציות (כמו index.js).
timeout
(אופציונלי)

זמן הביצוע המקסימלי של הפונקציה.

  • ברירת מחדל: 60s
  • הערך המקסימלי: 540s
availableMemoryMb
(אופציונלי)

נפח הזיכרון ב-MB שזמין לפונקציה.

  • ברירת מחדל: 256
  • ערכים תקינים: 128,‏ 256,‏ 512,‏ 1024 ו-2048
runtime
(מומלץ)

סביבת זמן הריצה של הפונקציה.
httpsTrigger
או
eventTrigger
או
scheduleTrigger
או
taskQueueTrigger
(צריך לציין אחד מסוגי הטריגרים האלה של הפונקציה) 		במאמר כתיבת פונקציות של Cloud Functions לתוסף מופיע מידע ספציפי על כל סוג של טריגר.

פונקציות Cloud Functions מהדור השני

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue
שדות של משאבים
name
מחרוזת
(חובה)

שם ידידותי למשתמש של הפונקציה שיוצאה.

אם לא מציינים את המאפיין entryPoint (ראו בהמשך), הערך הזה חייב להיות זהה לשם הפונקציה בקוד המקור של הפונקציות.

השם הסופי של הפונקציה שנפרסה יהיה בפורמט הבא: ext-extension-instance-id-name.
type
מחרוזת
(חובה) 		למשאב פונקציה מהדור השני: firebaseextensions.v1beta.v2function
description
מחרוזת
(חובה)

תיאור קצר של המשימה שהפונקציה מבצעת בשביל התוסף.
properties
(חובה)

מאפיינים של פונקציות Cloud Functions מהדור השני. המאפיינים החשובים ביותר מפורטים בהמשך, אבל הרשימה המלאה מופיעה בחומר העזר של Cloud Functions.

נכסים
location
(אופציונלי)

המיקום שבו רוצים לפרוס את הפונקציה. ברירת המחדל היא us-central1
sourceDirectory
(אופציונלי)

הספרייה שמכילה את package.json בתיקיית השורש שלה. הקובץ של קוד המקור של הפונקציות חייב להיות בספרייה הזו. ברירת המחדל היא functions

הערה: השדה main של package.json מציין את הקובץ של קוד המקור של הפונקציות (כמו index.js).

יש גם שלושה שדות מסוג אובייקט עם מאפיינים משלהם:

מאפייני buildConfig
buildConfig.runtime
(מומלץ)

סביבת זמן הריצה של הפונקציה.
buildConfig.entryPoint
(אופציונלי) 		שם הפונקציה המיוצאת בקוד המקור של הפונקציות שהתוסף צריך לחפש. ברירת המחדל היא הערך של name שלמעלה.
מאפייני serviceConfig
serviceConfig.timeoutSeconds
(אופציונלי)

זמן הביצוע המקסימלי של הפונקציה.

  • ברירת מחדל: 60
  • הערך המקסימלי: 540
serviceConfig.availableMemory
(אופציונלי) 		נפח הזיכרון שזמין לפונקציה. ברירת המחדל היא 256M. היחידות הנתמכות הן k, M, G, Mi, Gi. אם לא מציינים יחידה, הערך מפורש כבייטים.
מאפייני eventTrigger
eventTrigger.eventType
(חובה) 		סוג האירוע שצריך להאזין לו. במאמר כתיבת פונקציות של Cloud Functions לתוסף מפורטים סוגי האירועים שזמינים לכל מוצר.
eventTrigger.eventFilters
(אופציונלי) 		מסננים שמגבילים עוד יותר את האירועים שצריך להאזין להם. לדוגמה, אפשר להאזין רק לאירועים שתואמים לתבנית משאב ספציפית. במאמר כתיבת פונקציות של Cloud Functions לתוסף מוסבר איך לסנן כל סוג של אירוע.
eventTrigger.channel
(אופציונלי) 		שם הערוץ שמשויך לטריגר בפורמט projects/{project}/locations/{location}/channels/{channel}. אם לא מציינים את המאפיין הזה, הפונקציה תאזין לאירועים בערוץ ברירת המחדל של הפרויקט.
eventTrigger.triggerRegion
(אופציונלי) 		הטריגר יקבל רק אירועים שמקורם באזור הזה. הוא יכול להיות באותו אזור של הפונקציה, באזור אחר, במספר אזורים או באזור גלובלי. אם לא מציינים אזור, ברירת המחדל היא האזור של הפונקציה.

אירועים במחזור החיים

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

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
שדות של אירועים במחזור החיים
onInstall
(אופציונלי)

מציינת פונקציה שפועלת כשמשתמש מתקין את התוסף.

מפרט הפונקציה
function
מחרוזת
(חובה)

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

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

מציינת פונקציה שפועלת כשמשתמש מעדכן את התוסף.

מפרט הפונקציה
function
מחרוזת
(חובה)

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

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

מציינת פונקציה שפועלת כשמשתמש מגדיר מחדש את התוסף.

מפרט הפונקציה
function
מחרוזת
(חובה)

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

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

אירועים בהתאמה אישית (Eventarc)

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

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
שדות של אירועים בהתאמה אישית
type
מחרוזת
(חובה) 		מזהה הסוג של האירוע. המזהה מורכב מ-3 או 4 שדות שמופרדים בנקודות: השדות של מזהה בעל האפליקציה, שם התוסף ושם האירוע הם שדות חובה, והשדה "גרסה" הוא שדה מומלץ. בחרו שם ייחודי ותיאורי לכל סוג אירוע שאתם מפרסמים.
description
מחרוזת
(חובה) 		תיאור האירוע.