הפניה עבור 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 Extensions.

ערך נוכחי: v1beta

license
חוּט
(אופציונאלי)

רישיון להרחבה.

התוסף שלך חייב להיות מורשה באמצעות Apache-2.0 .

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

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

תמיד מוגדר true .

displayName
חוּט
(אופציונאלי)

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

מגבלת 40 תווים.

description
חוּט
(אופציונאלי)
תיאור קצר של המשימה שההרחבה שלך מבצעת (~1 משפט).
icon
חוּט
(אופציונאלי)

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

קובץ זה חייב להיות PNG מרובע בין 512x512 ל-1024x1024 פיקסלים. שים את הקובץ באותה ספרייה כמו extension.yaml ; אינך יכול לציין ספריית משנה.

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

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

מחבר ראשי ונקודת קשר להרחבה.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
שדות מחבר
authorName
חוּט
(נדרש)

שם המחבר.

יכול להיות אדם, חברה, ארגון וכו'.

email
חוּט
(אופציונאלי)
כתובת המייל של המחבר.
url
חוּט
(אופציונאלי)
כתובת אתר ציבורית שבה ניתן לגשת למידע על המחבר.
contributors
רשימת אובייקטי המחבר
(אופציונאלי)

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

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
שדות מחבר
authorName
חוּט
(נדרש)

שם המחבר.

יכול להיות אדם, חברה, ארגון וכו'.

email
חוּט
(אופציונאלי)
כתובת המייל של המחבר.
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

חייב להתאים לשדה שם השירות כפי שמופיע בדף הסקירה הכללית של כל ממשק API ( דוגמה ) בספריית Google Cloud API

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

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
חוּט
(אופציונאלי)
ביטוי רגולרי לאימות הערך המוגדר על ידי המשתמש של הפרמטר. תחביר RE2 של גוגל .
validationErrorMessage
חוּט
(אופציונאלי)
הודעת שגיאה שתוצג אם אימות הביטוי הרגולרי נכשל.
required
בוליאני
(אופציונאלי)
מגדיר אם המשתמש יכול לשלוח מחרוזת ריקה כאשר הוא מתבקש להזין את ערך הפרמטר. ברירת true .
immutable
בוליאני
(אופציונאלי)

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

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

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

משאבי פונקציית ענן

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

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

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
(נדרש)

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

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

פונקציות ענן מהדור השני

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
(נדרש)

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

נכסים
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
(נדרש)
סוג האירוע להקשיב לו. עיין ב- Write Cloud Functions עבור הרחבה עבור סוגי האירועים הזמינים עבור כל מוצר.
eventTrigger.eventFilters
(אופציונאלי)
מסננים שמגבילים עוד יותר את האירועים להאזנה. לדוגמה, תוכל להאזין רק לאירועים התואמים לדפוס משאבים ספציפי. ראה כתוב פונקציות ענן עבור הרחבה למידע על סינון כל סוג של אירוע.
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 ויש לה הוגדר תור משימות.

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

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

מפרט פונקציה
function
חוּט
(נדרש)

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

יש להצהיר על פונקציה זו בסעיף resources ויש לה הוגדר תור משימות.

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

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

מפרט פונקציה
function
חוּט
(נדרש)

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

יש להצהיר על פונקציה זו בסעיף resources ויש לה הוגדר תור משימות.

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
חוּט
(נדרש)
תיאור האירוע.