Referenz für „extension.yaml“

Die Spezifikationsdatei Ihrer Erweiterung (extension.yaml) enthält die Metadaten Ihrer Erweiterung, deklariert die von der Erweiterung erstellten Ressourcen sowie die von der Erweiterung erforderlichen APIs und den Zugriff und definiert alle von der Erweiterung bereitgestellten von Nutzern konfigurierten Parameter.

In den Tabellen auf dieser Seite werden die Felder beschrieben, die für eine extension.yaml-Datei verfügbar sind.

Allgemeine und personenidentifizierbare Informationen

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/
Grundlegende Felder
name
String
(erforderlich)

Kennung für die Erweiterung.

Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten. Die maximale Länge beträgt 40 Zeichen.

Hinweis:Dieser Wert wird verwendet, um die Instanz-ID der Erweiterung zu generieren. Diese wird dann verwendet, um die Namen des Dienstkontos und der erweiterungsspezifischen Ressourcen zu generieren.

version
String
(erforderlich)

Version der Erweiterung.

Sie muss der SemVer-Versionierung entsprechen (z. B. 1.2.0).
specVersion
String
(erforderlich)

Version der Firebase Extensions-Spezifikation.

Aktueller Wert: v1beta
license
string
(optional)

Lizenz für die Erweiterung.

Ihre Erweiterung muss mit Apache-2.0 lizenziert sein.
billingRequired
boolean
(optional)

Ob für die von der Erweiterung verwendeten Dienste ein Firebase-Rechnungskonto für die kostenpflichtige Stufe erforderlich ist.

Immer auf true gesetzt.
displayName
String
(optional)

Anschaulicher Anzeigename für die Erweiterung (3–5 Wörter).

Maximal 40 Zeichen.
description
String
(optional) 		Kurze Beschreibung der Aufgabe, die Ihre Erweiterung ausführt (~1 Satz).
icon
string
(optional)

Datei, die als Symbol der Erweiterung auf extensions.dev und in der Firebase-Konsole verwendet werden soll.

Diese Datei muss ein quadratisches PNG-Bild mit einer Größe von 512 × 512 bis 1.024 × 1.024 Pixeln sein. Legen Sie die Datei im selben Verzeichnis wie extension.yaml ab. Sie können kein Unterverzeichnis angeben.

Beachte beim Entwerfen eines Symbols für deine Erweiterung die folgenden Richtlinien:

  • Wählen Sie Hintergrund- und Artworkfarben aus, die zu Ihrer Marke passen.
  • Verwenden Sie nur zwei Farben für die Symbolfarben. Mehrere Farben können dein Symbol visuell überfordern.
  • Aus demselben Grund sollten Sie auch keine Farbverläufe in Ihrem Symbol verwenden. Farbverläufe sind bei kleinen Größen schwer zu erkennen und machen das Symbol visuell komplex.
  • Verwenden Sie einfache, eindeutige Bilder, die die Funktionen Ihrer Erweiterung veranschaulichen.
  • Wenn dein Unternehmen mehrere Erweiterungen entwickelt, verwende nicht dein Logo als Symbol. Nutzer haben Schwierigkeiten, zwischen Ihren Erweiterungen zu unterscheiden.
  • Das Artwork sollte grafisch und prägnant sein. Verwenden Sie keine filigranen oder aufwendigen Grafiken, da sich diese in kleineren Größen nicht gut darstellen.
  • Geben Sie keine Wörter an, die erklären, wozu Ihre Erweiterung dient. Text ist in kleineren Größen oft unleserlich.
tags
Liste von Strings
(optional) 		Tags, mit denen Nutzer Ihre Erweiterung leichter finden Die folgenden Tags sind Kategorien im Erweiterungs-Hub zugeordnet: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
string
(optional) 		Öffentliche URL, unter der auf das Erweiterungsverzeichnis zugegriffen werden kann.
releaseNotesUrl
string
(optional) 		Öffentliche URL, unter der die Versionshinweise für die Erweiterung aufgerufen werden können.
author
ein Autorobjekt
(optional)

Hauptautor und Ansprechpartner für die Erweiterung.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Felder für den Autor
authorName
String
(erforderlich)

Name des Autors.

Das kann eine Person, ein Unternehmen oder eine Organisation sein.
email
string
(optional) 		E-Mail-Adresse des Autors.
url
string
(optional) 		Öffentliche URL, unter der Informationen zum Autor abgerufen werden können.
contributors
Liste der Autorenobjekte
(optional)

Alle weiteren Mitwirkenden an der Erweiterung.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Autorenfelder
authorName
String
(erforderlich)

Name des Autors.

Das kann eine Person, ein Unternehmen oder eine Organisation sein.
email
string
(optional) 		E-Mail-Adresse des Autors.
url
string
(optional) 		Öffentliche URL, unter der Informationen zum Autor abgerufen werden können.

Firebase- und Google Cloud APIs

In diesen Feldern werden die Firebase- und Google APIs angegeben, die von der Erweiterung verwendet werden. Wenn Nutzer die Erweiterung installieren, können sie diese APIs automatisch in ihrem Projekt aktivieren.

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-Felder
apiName
String
(erforderlich)

Name der Google API

Muss dem Feld Dienstname entsprechen, das auf der Übersichtsseite jeder API (Beispiel) in der Google Cloud API-Bibliothek aufgeführt ist.

reason
String
(erforderlich) 		Eine kurze Beschreibung, warum die Erweiterung diese API verwenden muss

IAM-Rollen

In diesen Feldern werden die Cloud IAM-Rollen angegeben, die für die Erweiterung erforderlich sind. Diese Rollen werden dem Dienstkonto zugewiesen, das für die Erweiterung bereitgestellt wurde.

Sie können nur eine der unterstützten Rollen angeben.

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
Rollenfelder
role
String
(erforderlich)

Name der IAM-Rolle, die für den Betrieb der Erweiterung erforderlich ist

Sie muss eine der unterstützten Rollen sein.

reason
String
(erforderlich) 		Eine kurze Beschreibung, warum die Erweiterung den Zugriff benötigt, der durch diese Rolle gewährt wird
resource
String
(optional)

Beschränken Sie den Umfang der Rolle auf diese Ressource.

Der Standardwert ist projects/${project_id}, wenn nichts angegeben ist. Weitere Informationen finden Sie unter Umfang von Rollen reduzieren.

Externe Dienstleistungen

In diesen Feldern werden die Dienste angegeben, die nicht von Firebase oder Google stammen und von der Erweiterung verwendet werden (in der Regel REST APIs). Die Firebase-Erweiterungsplattform bietet keine Möglichkeit, die Autorisierung für diese Dienste automatisch zu aktivieren oder durchzuführen.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Felder für externe Dienste
name
String
(erforderlich) 		Name des externen Dienstes, der für den Betrieb der Erweiterung erforderlich ist
pricingUri
String
(erforderlich) 		URI zu Preisinformationen für den Dienst

Von Nutzern konfigurierbare Parameter

Diese Felder definieren die Parameter, die die Erweiterung Nutzern zur Konfiguration zur Verfügung stellt.

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
Parameterfelder
param
String
(erforderlich) 		Name des Parameters. Mit diesem Namen wird im Code auf den Parameterwert verwiesen.
label
String
(erforderlich) 		Kurze Beschreibung des Parameters. Wird dem Nutzer angezeigt, wenn er zur Eingabe des Parameterwerts aufgefordert wird.
description
string
(optional)

Detaillierte Beschreibung des Parameters. Wird dem Nutzer angezeigt, wenn er zur Eingabe des Parameterwerts aufgefordert wird.

Unterstützt Markdown.
example
string
(optional) 		Beispielwert für den Parameter.
default
string
(optional) 		Standardwert für den Parameter, wenn der Nutzer den Wert des Parameters leer lässt.
validationRegex
string
(optional) 		Regulärer Ausdruck zur Validierung des vom Nutzer konfigurierten Werts des Parameters. Google RE2-Syntax
validationErrorMessage
string
(optional) 		Fehlermeldung, die angezeigt wird, wenn die Regex-Validierung fehlschlägt.
required
boolean
(optional) 		Gibt an, ob der Nutzer einen leeren String einreichen kann, wenn er nach dem Wert des Parameters gefragt wird. Die Standardeinstellung ist true.
immutable
boolean
(optional)

Gibt an, ob der Nutzer den Parameterwert nach der Installation ändern kann, z. B. wenn er die Erweiterung neu konfiguriert. Die Standardeinstellung ist false.

Hinweis:Wenn Sie einen „location“-Parameter für die bereitgestellten Funktionen der Erweiterung definieren, legen Sie dieses Feld auf true fest.
type
string
(optional) 		Der Parametertyp. Für spezielle Parametertypen gelten möglicherweise zusätzliche Anforderungen oder eine andere Benutzeroberfläche. Weitere Informationen finden Sie in den folgenden Abschnitten.

Auswählbare und mehrfach auswählbare Parameter

Auswählbare und mehrfach auswählbare Parameter fordern Nutzer auf, eine der vordefinierten Optionen auszuwählen.

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
Multiple-Choice-Parameterfelder
type
String

select oder multiselect

Gibt an, dass der Parameter einen Wert (select) oder mehrere Werte (multiselect) aus einer Reihe vordefinierter Optionen sein kann.
options
Liste der Optionen
(erforderlich)

Die Optionen, aus denen der Nutzer auswählen kann

Optionsfelder
value
String
(erforderlich) 		Einer der Werte, die der Nutzer auswählen kann. Sie erhalten diesen Wert, wenn Sie den Parameterwert im Code lesen.
label
string
(optional) 		Kurze Beschreibung der auswählbaren Option. Wenn keine Angabe gemacht wird, lautet der Standardwert value.

Auswählbare Ressourcenparameter

Auswählbare Ressourcenparameter fordern Nutzer auf, eine Ressource (Datenbankinstanz, Storage-Bucket usw.) aus ihrem Projekt auszuwählen.

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
Felder für Ressourcenparameter
type
String

selectresource

Gibt an, dass der Parameter eine Projektressource darstellt.
resourceType
String
(erforderlich)

Der Ressourcentyp, den der Nutzer auswählen soll.

Zulässige Werte:

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

Derzeit gibt es jedoch nur für Cloud Storage-Buckets eine Auswahloberfläche. Andere Ressourcentypen werden als kostenlose Texteingabefelder angezeigt.

Secret-Parameter

Von Nutzern bereitgestellte Secret-Werte (z. B. API-Schlüssel) werden anders behandelt:

  • Secret-Werte werden mit Cloud Secret Manager gespeichert. Nur autorisierte Clients (z. B. eine installierte Instanz einer Erweiterung) können auf diese Werte zugreifen.
  • Wenn Nutzer aufgefordert werden, diese Werte anzugeben, wird ihre Eingabe nicht angezeigt.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Secret-Parameterfelder
type
String

secret

Gibt an, dass der Parameter ein geheimer Wert ist.

Cloud Functions-Ressourcen

In diesen Feldern werden die Cloud Functions deklariert, die in einer Erweiterung enthalten sind. Die Syntax der Ressourcendeklaration unterscheidet sich geringfügig zwischen Funktionen der 1. und der 2. Generation, die in einer Erweiterung nebeneinander existieren können.

Cloud Functions-Funktionen der 1. Generation

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
Ressourcenfelder
name
String
(erforderlich)

Nutzerfreundlicher Name für die exportierte Funktion.

Wenn Sie die Eigenschaft entryPoint nicht angeben (siehe unten), muss dieser Wert mit dem Namen der Funktion im Quellcode der Funktion übereinstimmen.

Der endgültige Name der bereitgestellten Funktion hat folgendes Format: ext-extension-instance-id-name.
type
String
(erforderlich) 		Für eine Funktionsressource der 1. Generation: firebaseextensions.v1beta.function
description
String
(erforderlich)

Eine kurze Beschreibung der Aufgabe, die die Funktion für die Erweiterung ausführt.
properties
(erforderlich)

Cloud Functions-Properties der 1. Generation Die wichtigsten Eigenschaften sind unten aufgeführt. Eine vollständige Liste finden Sie in der Referenz zu Cloud Functions.

Properties
location
(optional)

Speicherort, an dem die Funktion bereitgestellt werden soll. Standardeinstellung: us-central1
entryPoint
(optional) 		Name der exportierten Funktion im Quellcode Ihrer Funktion, nach der die Erweiterung suchen soll. Die Standardeinstellung ist der oben angegebene Wert name.
sourceDirectory
(optional)

Verzeichnis, das Ihre package.json im Stammverzeichnis enthält. Die Datei mit dem Quellcode Ihrer Funktion muss sich in diesem Verzeichnis befinden. Die Standardeinstellung ist functions.

Hinweis: Im Feld main von package.json wird die Datei für den Quellcode der Funktion angegeben (z. B. index.js).
timeout
(optional)

Die maximale Ausführungszeit der Funktion.

  • Standardwert: 60s
  • Maximalwert: 540s
availableMemoryMb
(optional)

Größe des für die Funktion verfügbaren Arbeitsspeichers in MB.

  • Standardwert: 256
  • Gültige Werte: 128, 256, 512, 1024 und 2048
runtime
(empfohlen)

Laufzeitumgebung für die Funktion.

  • Standardmäßig wird die neueste der Node.js-Versionen verwendet, die derzeit von Cloud Functions unterstützt wird.
  • Gültige Werte: nodejs14, nodejs16, nodejs18
httpsTrigger
oder
eventTrigger
oder
scheduleTrigger
oder
taskQueueTrigger
(einer dieser Funktionstriggertypen ist erforderlich) 		Unter Cloud Functions für eine Erweiterung schreiben finden Sie spezifische Informationen zu den einzelnen Triggertypen.

Cloud Functions-Funktionen der 2. Generation

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
Ressourcenfelder
name
String
(erforderlich)

Nutzerfreundlicher Name für die exportierte Funktion.

Wenn Sie die Eigenschaft entryPoint nicht angeben (siehe unten), muss dieser Wert mit dem Namen der Funktion im Quellcode der Funktion übereinstimmen.

Der endgültige Name der bereitgestellten Funktion hat folgendes Format: ext-extension-instance-id-name.
type
String
(erforderlich) 		Für eine Funktionsressource der 2. Generation: firebaseextensions.v1beta.v2function
description
String
(erforderlich)

Eine kurze Beschreibung der Aufgabe, die die Funktion für die Erweiterung ausführt.
properties
(erforderlich)

Cloud Functions-Properties der 2. Generation Die wichtigsten Attribute sind unten aufgeführt. Eine vollständige Liste finden Sie in der Cloud Functions-Referenz.

Properties
location
(optional)

Speicherort, an dem die Funktion bereitgestellt werden soll. Standardeinstellung ist us-central1
sourceDirectory
(optional)

Verzeichnis, das Ihre package.json im Stammverzeichnis enthält. Die Datei mit dem Quellcode Ihrer Funktion muss sich in diesem Verzeichnis befinden. Die Standardeinstellung ist functions.

Hinweis: Im Feld main von package.json wird die Datei für den Quellcode der Funktionen angegeben (z. B. index.js).

Außerdem gibt es drei Felder vom Objekttyp mit eigenen Eigenschaften:

buildConfig-Eigenschaften
buildConfig.runtime
(empfohlen)

Laufzeitumgebung für die Funktion.

  • Standardmäßig wird die neueste der Node.js-Versionen verwendet, die derzeit von Cloud Functions unterstützt wird.
  • Gültige Werte: nodejs14, nodejs16, nodejs18
buildConfig.entryPoint
(optional) 		Name der exportierten Funktion im Quellcode Ihrer Funktion, nach der die Erweiterung suchen soll. Standardmäßig ist der Wert name (siehe oben).
serviceConfig-Eigenschaften
serviceConfig.timeoutSeconds
(optional)

Die maximale Ausführungszeit der Funktion.

  • Standardwert: 60
  • Maximalwert: 540
serviceConfig.availableMemory
(optional) 		Die Größe des Arbeitsspeichers, der für eine Funktion verfügbar ist. Die Standardeinstellung ist 256M. Unterstützte Einheiten sind k, M, G, Mi und Gi. Wenn keine Einheit angegeben ist, wird der Wert als Byte interpretiert.
eventTrigger-Attribute
eventTrigger.eventType
(erforderlich) 		Die Art des Ereignisses, das erfasst werden soll. Informationen zu den für jedes Produkt verfügbaren Ereignistypen finden Sie unter Cloud Functions-Funktionen für eine Erweiterung schreiben.
eventTrigger.eventFilters
(optional) 		Filter, die die zu überwachenden Ereignisse weiter einschränken. So können Sie beispielsweise nur Ereignisse erfassen, die einem bestimmten Ressourcenmuster entsprechen. Informationen zum Filtern der einzelnen Ereignistypen finden Sie unter Cloud Functions-Funktionen für eine Erweiterung schreiben.
eventTrigger.channel
(optional) 		Der Name des Kanals, der mit dem Trigger verknüpft ist, im Format projects/{project}/locations/{location}/channels/{channel}. Wenn Sie diese Property weglassen, überwacht die Funktion Ereignisse auf dem Standardkanal des Projekts.
eventTrigger.triggerRegion
(optional) 		Der Trigger empfängt nur Ereignisse aus dieser Region. Es kann sich um dieselbe Region wie die Funktion, eine andere Region, eine Multi-Region oder die globale Region handeln. Wenn nicht angegeben, wird standardmäßig dieselbe Region wie die Funktion verwendet.

Lebenszyklus-Ereignisse

Mit Lebenszyklusereignissen können Sie Funktionen angeben, die ausgeführt werden, wenn ein Nutzer eine Instanz Ihrer Erweiterung installiert, aktualisiert oder konfiguriert. Weitere Informationen finden Sie unter Lifecycle-Ereignisse Ihrer Erweiterung verarbeiten.

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
Felder für Lebenszyklusereignisse
onInstall
(optional)

Gibt eine Funktion an, die ausgeführt wird, wenn ein Nutzer die Erweiterung installiert.

Funktionsspezifikation
function
String
(erforderlich)

Name der durch die Aufgabenwarteschlange ausgelösten Funktion, die das Ereignis verarbeitet.

Diese Funktion muss im Abschnitt resources deklariert und taskQueue definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt wird, während die Aufgabe ausgeführt wird.
onUpdate
(optional)

Gibt eine Funktion an, die ausgeführt wird, wenn ein Nutzer die Erweiterung aktualisiert.

Funktionsspezifikation
function
String
(erforderlich)

Name der durch die Aufgabenwarteschlange ausgelösten Funktion, die das Ereignis verarbeitet.

Diese Funktion muss im Abschnitt resources deklariert und taskQueue definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt wird, während die Aufgabe ausgeführt wird.
onConfigure
(optional)

Gibt eine Funktion an, die ausgeführt wird, wenn ein Nutzer die Erweiterung neu konfiguriert.

Funktionsspezifikation
function
String
(erforderlich)

Name der durch die Aufgabenwarteschlange ausgelösten Funktion, die das Ereignis verarbeitet.

Diese Funktion muss im Abschnitt resources deklariert und taskQueue definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt wird, während die Aufgabe ausgeführt wird.

Benutzerdefinierte Ereignisse (Eventarc)

Benutzerdefinierte Ereignisse sind Ereignisse, die Ihre Erweiterung ausgibt, damit Nutzer ihre eigene Logik in Ihre Erweiterung einfügen können. Weitere Informationen finden Sie im Abschnitt zu Eventarc unter Nutzer-Hooks zu einer Erweiterung hinzufügen.

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
Felder für benutzerdefinierte Ereignisse
type
String
(erforderlich) 		Die Typ-ID des Ereignisses. Die Kennung besteht aus drei bis vier durch Punkte getrennten Feldern: Die Felder „Publisher-ID“, „Erweiterungsname“ und „Ereignisname“ sind erforderlich, das Feld „Version“ wird empfohlen. Wählen Sie für jeden Ereignistyp, den Sie veröffentlichen, einen eindeutigen und beschreibenden Ereignisnamen aus.
description
String
(erforderlich) 		Beschreibung des Termins.