קובץ המפרט של התוסף (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 string (חובה) |
גרסת מפרט התוספים ל-Firebase. הערך הנוכחי: |
||||||||
license string (אופציונלי) |
רישיון לתוסף. נדרש רישיון לשימוש בתוסף שלך באמצעות |
||||||||
billingRequired boolean (אופציונלי) |
האם השירותים שבהם התוסף משתמש דורשים חשבון לחיוב ב-Firebase ברמה בתשלום. הערך תמיד מוגדר ל- |
||||||||
displayName string (אופציונלי) |
שם תצוגה ידידותי של התוסף (3-5 מילים). מגבלה של 40 תווים. |
||||||||
description string (אופציונלי) |
תיאור קצר של המשימה שהתוסף מבצע (משפט אחד בערך). | ||||||||
icon string (אופציונלי) |
קובץ שישמש כסמל של התוסף ב- הקובץ הזה חייב להיות קובץ PNG מרובע בגודל שבין 512x512 ל-1,024x1,024 פיקסלים.
צריך לשמור את הקובץ באותה ספרייה כמו כשאתם מעצבים סמל להרחבה, חשוב לזכור את ההנחיות הבאות:
|
||||||||
tags רשימת מחרוזות (אופציונלי) |
תגים שיעזרו למשתמשים לגלות את התוסף.
התגים הבאים ממופים לקטגוריות במרכז התוספים:
marketing ,
messaging ,
payments ,
search ,
shipping ,
social ,
utilities ,
ai
|
||||||||
sourceUrl מחרוזת (אופציונלי) |
כתובת URL ציבורית שבה אפשר לגשת לספריית התוספים. | ||||||||
releaseNotesUrl מחרוזת (אופציונלי) |
כתובת ה-URL הציבורית שבה אפשר לגשת לנתוני הגרסה של התוסף. | ||||||||
author אובייקט author אחד (אופציונלי) |
המחבר הראשי ואיש הקשר של התוסף. author: authorName: Your Company email: extensions@example.com url: https://example.com/
|
||||||||
contributors רשימת אובייקטים של מחבר (אופציונלי) |
מחברים תורמים נוספים של התוסף. contributors: - authorName: Your Name - authorName: Another Contributor email: colleague@example.net url: https://github.com/their-org/
|
ממשקי 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 string (חובה) |
שם Google API השדה חייב להתאים לשדה שם השירות שמופיע בדף הסקירה הכללית של כל API (דוגמה) בספריית Google Cloud API. |
reason string (חובה) |
תיאור קצר של הסיבה לכך שהתוסף צריך להשתמש ב-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 string (חובה) |
תיאור קצר של הסיבה לכך שהתוסף זקוק לגישה שמקבלים מהתפקיד הזה |
resource string (אופציונלי) |
מגבילים את היקף התפקיד למשאב הזה. אם לא מציינים את הפרמטר הזה, ברירת המחדל היא |
שירותים חיצוניים
השדות האלה מציינים את השירותים שאינם של 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 string (חובה) |
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 string (חובה) |
שם הפרמטר. השם הזה משמש להפניה לערך הפרמטר בקוד. |
label string (חובה) |
תיאור קצר של הפרמטר. מוצג למשתמש כשמוצגת לו בקשה להזין את הערך של הפרמטר. |
description string (אופציונלי) |
תיאור מפורט של הפרמטר. מוצג למשתמש כשמוצגת לו בקשה להזין את הערך של הפרמטר. תמיכה ב-Markdown. |
example string (אופציונלי) |
ערך לדוגמה של הפרמטר. |
default string (אופציונלי) |
ערך ברירת המחדל של הפרמטר אם המשתמש משאיר את הערך של הפרמטר ריק. |
validationRegex string (אופציונלי) |
ביטוי רגולרי לאימות הערך שהוגדר על ידי המשתמש לפרמטר. תחביר של Google RE2. |
validationErrorMessage string (אופציונלי) |
הודעת השגיאה שתוצג אם אימות הביטוי הרגולרי נכשל. |
required boolean (אופציונלי) |
מגדירה אם המשתמש יכול לשלוח מחרוזת ריקה כשמוצגת הנחיה להזין את ערך הפרמטר. ברירת המחדל היא true .
|
immutable boolean (אופציונלי) |
ההגדרה קובעת אם המשתמש יכול לשנות את הערך של הפרמטר אחרי ההתקנה (למשל, אם הוא מגדיר מחדש את התוסף). ברירת המחדל היא
הערה: אם מגדירים פרמטר 'location' לפונקציות הפרוסות של התוסף, צריך להגדיר את השדה הזה לערך |
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 מחרוזת |
מציין שהפרמטר יכול להיות ערך אחד ( |
||||||
options רשימת אפשרויות (חובה) |
האפשרויות שמהן המשתמש יכול לבחור
|
פרמטרים של משאבים שניתן לבחור
פרמטרים שניתן לבחור של משאבים מבקשים מהמשתמשים לבחור משאב (מופע של מסד נתונים, קטגוריית אחסון וכו') מהפרויקט.
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 |
מציין שהפרמטר מייצג משאב של פרויקט |
resourceType string (חובה) |
סוג המשאב שהמשתמש יתבקש לבחור. הערכים האפשריים:
עם זאת, רק לקטגוריות של 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 מחרוזת |
מציין שהפרמטר הוא ערך סודי |
משאבים של 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 מחרוזת (חובה) |
שם ידידותי למשתמש לפונקציה המיוצאת. אם לא מציינים את המאפיין השם הסופי של הפונקציה שפורסה יהיה בפורמט הבא: |
||||||||||||||||
type מחרוזת (חובה) |
למשאב פונקציה מדור ראשון:
firebaseextensions.v1beta.function
|
||||||||||||||||
description מחרוזת (חובה) |
תיאור קצר של המשימה שהפונקציה מבצעת עבור התוסף. |
||||||||||||||||
properties (חובה) |
נכסי Cloud Functions מדור ראשון. המאפיינים החשובים ביותר מפורטים בהמשך, אבל אפשר למצוא את הרשימה המלאה בחומר העזר של 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 מחרוזת (חובה) |
שם ידידותי למשתמש לפונקציה המיוצאת. אם לא מציינים את המאפיין השם הסופי של הפונקציה שפורסה יהיה בפורמט הבא: |
||||||||||||||||||||||||||||
type string (חובה) |
למשאב פונקציה מדור שני:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description מחרוזת (חובה) |
תיאור קצר של המשימה שהפונקציה מבצעת עבור התוסף. |
||||||||||||||||||||||||||||
properties (חובה) |
מאפייני Cloud Functions מדור שני. המאפיינים החשובים ביותר מפורטים בהמשך, אבל אפשר למצוא את הרשימה המלאה בחומר העזר של Cloud Functions.
יש גם שלושה שדות מסוג אובייקט עם מאפיינים משלהם:
|
אירועים במחזור החיים
אירועי מחזור חיים מאפשרים לכם לציין פונקציות שפועלות כשמשתמש מתקין, מעדכן או מגדיר מכונה של התוסף. טיפול באירועים במחזור החיים של התוסף
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 (אופציונלי) |
מציינת פונקציה שרצה כשמשתמש מתקין את התוסף.
|
||||||
onUpdate (אופציונלי) |
מציין פונקציה שפועלת כשמשתמש מעדכן את התוסף.
|
||||||
onConfigure (אופציונלי) |
מציין פונקציה שתופעל כשמשתמש מגדיר מחדש את התוסף.
|
אירועים מותאמים אישית (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 string (חובה) |
תיאור האירוע. |