קובץ עזר ל-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: [email protected]
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    url: https://github.com/their-org/

author:
  authorName: Your Company
  email: [email protected]
  url: https://example.com/

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    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

תפקידי 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

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

בשדות האלה מפורטים השירותים שאינם של 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

פרמטרים שניתן להגדיר על ידי משתמשים

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

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

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

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

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

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

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

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

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

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

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

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    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

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

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

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

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

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

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

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