Referenz für extension.yaml

Die Spezifikationsdatei Ihrer Erweiterung (extension.yaml) enthält die Metadaten der Erweiterung, deklariert die von der Erweiterung erstellten Ressourcen sowie die von der Erweiterung benötigten APIs und Zugriffe und definiert alle von der Erweiterung bereitgestellten nutzerkonfigurierten Parameter.

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

Allgemeine und identifizierende 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/
Einfache Felder
name
String
(erforderlich)

Kennung für die Erweiterung.

Darf nur Kleinbuchstaben, Ziffern und Bindestriche enthalten; maximal 40 Zeichen.

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

version
String
(erforderlich)

Version der Erweiterung.

Muss der semantischen Versionsverwaltung 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 werden.
billingRequired
boolean
(optional)

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

Immer auf true gesetzt.
displayName
String
(optional)

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

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

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

Diese Datei muss ein quadratisches PNG-Bild mit einer Größe zwischen 512 × 512 und 1.024 × 1.024 Pixel sein. Speichern Sie die Datei im selben Verzeichnis wie extension.yaml. Sie können kein Unterverzeichnis angeben.

Beachten Sie beim Entwerfen eines Symbols für Ihre Erweiterung die folgenden Richtlinien:

  • Wählen Sie Hintergrund- und Artwork-Farben aus, die für Ihre Marke geeignet sind.
  • Verwenden Sie nur zwei Farben für Ihr Symbol. Mehrere Farben können Ihr Symbol visuell überladen wirken lassen.
  • Aus demselben Grund sollten Sie keine Verläufe in Ihrem Symbol verwenden. Verläufe sind bei kleinen Größen schwer zu erkennen und machen das Symbol visuell komplex.
  • Verwenden Sie einfache, einzigartige Bilder, die die Funktionalität Ihrer Erweiterung vermitteln.
  • Wenn Ihr Unternehmen mehrere Erweiterungen entwickelt, verwenden Sie nicht Ihr Logo als Symbol. Nutzer haben Schwierigkeiten, Ihre Erweiterungen zu unterscheiden.
  • Das Artwork sollte grafisch und auffällig sein. Verwenden Sie keine filigranen oder aufwendigen Grafiken, die bei kleineren Größen nicht gut gerendert werden.
  • Die Beschreibung darf keine Wörter enthalten, die erklären, was Ihre Erweiterung tut. Text ist bei kleineren Größen oft unleserlich.
tags
Liste von Strings
(optional) 		Tags, damit Nutzer Ihre Erweiterung leichter finden. Die folgenden Tags werden Kategorien im Extensions Hub zugeordnet: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
String
(optional) 		Öffentliche URL, über die auf das Erweiterungsverzeichnis zugegriffen werden kann.
releaseNotesUrl
String
(optional) 		Öffentliche URL, über die auf die Versionshinweise für die Erweiterung zugegriffen werden kann.
author
ein Autorobjekt
(optional)

Der primäre Autor und Ansprechpartner für die Erweiterung.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Autorenfelder
authorName
String
(erforderlich)

Name des Autors.

Kann eine Person, ein Unternehmen, eine Organisation usw. sein.
email
String
(optional) 		E-Mail-Adresse des Autors.
url
String
(optional) 		Öffentliche URL, über die auf Informationen zum Autor zugegriffen werden kann.
contributors
Liste der Autorobjekte
(optional)

Alle zusätzlichen Mitwirkenden für die 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.

Kann eine Person, ein Unternehmen, eine Organisation usw. sein.
email
String
(optional) 		E-Mail-Adresse des Autors.
url
String
(optional) 		Öffentliche URL, über die auf Informationen zum Autor zugegriffen werden kann.

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) 		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. Dem für die Erweiterung bereitgestellten Dienstkonto werden diese Rollen zugewiesen.

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 die Funktion der Erweiterung erforderlich ist

Muss eine der unterstützten Rollen sein.

reason
String
(erforderlich) 		Kurze Beschreibung, warum die Erweiterung den durch diese Rolle gewährten Zugriff benötigt
resource
String
(optional)

Beschränken Sie den Bereich 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 Nicht-Firebase- und Nicht-Google-Dienste angegeben, die von der Erweiterung verwendet werden (in der Regel REST APIs). Die Firebase Extensions-Plattform 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 die Funktion der Erweiterung erforderlich ist
pricingUri
String
(erforderlich) 		URI zu Preisinformationen für den Dienst

Von Nutzern konfigurierbare Parameter

In diesen Feldern werden die Parameter definiert, 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 nach dem Wert des Parameters gefragt wird.
description
String
(optional)

Ausführliche Beschreibung des Parameters. Wird dem Nutzer angezeigt, wenn er nach dem Wert des Parameters gefragt 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 senden kann, wenn er nach dem Wert des Parameters gefragt wird. Die Standardeinstellung ist true.
immutable
boolean
(optional)

Gibt an, ob der Nutzer den Wert des Parameters 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 Ihrer 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 sie werden in der Benutzeroberfläche anders dargestellt. Weitere Informationen finden Sie in den folgenden Abschnitten.

Auswählbare Parameter und Parameter mit Mehrfachauswahl

Bei auswählbaren und mehrfach auswählbaren Parametern werden Nutzer aufgefordert, aus einer Liste vordefinierter 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
Parameterfelder mit mehreren Auswahlmöglichkeiten
type
string

select oder multiSelect

Gibt an, dass der Parameter ein Wert (select) oder mehrere Werte (multiSelect) sein kann, die aus einer Reihe vordefinierter Optionen ausgewählt werden.
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. Das ist der Wert, den Sie erhalten, 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

Bei auswählbaren Ressourcenparametern werden Nutzer aufgefordert, eine Ressource (z. B. eine Datenbankinstanz oder einen Speicher-Bucket) 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
Ressourcenparameterfelder
type
string

selectresource

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

Der Typ der Ressource, die der Nutzer auswählen soll.

Zulässige Werte:

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

Derzeit haben jedoch nur Cloud Storage-Buckets eine Auswahl-UI. Andere Ressourcentypen werden als Freiform-Texteingabefelder dargestellt.

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
Felder für geheime Parameter
type
string

secret

Gibt an, dass der Parameter ein Secret-Wert ist.

Cloud Functions-Ressourcen

In diesen Feldern werden die in einer Erweiterung enthaltenen Cloud Functions deklariert. Die Syntax für die Ressourcendeklaration sieht bei Funktionen der 1. und 2. Generation, die in einer Erweiterung vorhanden sein können, etwas anders aus.

Cloud Functions (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 entryPoint-Eigenschaft nicht angeben (siehe unten), muss dieser Wert mit dem Namen der Funktion im Quellcode Ihrer Funktionen übereinstimmen.

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

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

Eigenschaften von Cloud Functions (1. 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. Die Standardeinstellung ist us-central1.
entryPoint
(optional) 		Name der exportierten Funktion in Ihrem Funktionsquellcode, nach der die Erweiterung suchen soll. Der Standardwert ist der Wert von name oben.
sourceDirectory
(optional)

Verzeichnis, das Ihr package.json im Stammverzeichnis enthält. Die Datei für den Quellcode Ihrer Funktionen muss sich in diesem Verzeichnis befinden. Die Standardeinstellung ist functions.

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

Die maximale Ausführungszeit der Funktion.

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

Die Menge an Speicherplatz in MB, die für die Funktion verfügbar ist.

  • 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 werden.
  • Gültige Werte: nodejs14, nodejs16, nodejs18
httpsTrigger
oder
eventTrigger
oder
scheduleTrigger
oder
taskQueueTrigger
(einer dieser Funktionstriggertypen ist erforderlich) 		Spezifische Informationen zu den einzelnen Triggertypen finden Sie unter Cloud Functions für eine Erweiterung schreiben.

Cloud Functions (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 entryPoint-Eigenschaft nicht angeben (siehe unten), muss dieser Wert mit dem Namen der Funktion im Quellcode Ihrer Funktionen übereinstimmen.

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

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

Eigenschaften von Cloud Functions 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. Die Standardeinstellung ist us-central1.
sourceDirectory
(optional)

Verzeichnis, das Ihr package.json im Stammverzeichnis enthält. Die Datei für den Quellcode Ihrer Funktionen muss sich in diesem Verzeichnis befinden. Die Standardeinstellung ist functions.

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

Außerdem gibt es drei Felder für Objekttypen 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 werden.
  • Gültige Werte: nodejs14, nodejs16, nodejs18
buildConfig.entryPoint
(optional) 		Name der exportierten Funktion in Ihrem Funktionsquellcode, nach der die Erweiterung suchen soll. Der Standardwert ist der Wert von name oben.
serviceConfig-Eigenschaften
serviceConfig.timeoutSeconds
(optional)

Die maximale Ausführungszeit der Funktion.

  • Standardwert: 60
  • Maximalwert: 540
serviceConfig.availableMemory
(optional) 		Die Menge an Arbeitsspeicher, die für eine Funktion verfügbar ist. Die Standardeinstellung ist 256M. Unterstützte Einheiten sind k, M, G, Mi, Gi. Wenn keine Einheit angegeben ist, wird der Wert als Byte interpretiert.
eventTrigger-Eigenschaften
eventTrigger.eventType
(erforderlich) 		Die Art des Ereignisses, das erfasst werden soll. Informationen zu den für die einzelnen Produkte verfügbaren Ereignistypen finden Sie unter Cloud Functions für eine Erweiterung schreiben.
eventTrigger.eventFilters
(optional) 		Filter, die die zu erfassenden Ereignisse weiter einschränken. Sie können beispielsweise nur auf Ereignisse reagieren, die einem bestimmten Ressourcenmuster entsprechen. Informationen zum Filtern der einzelnen Ereignistypen finden Sie unter Cloud Functions für eine Erweiterung schreiben.
eventTrigger.channel
(optional) 		Der Name des Kanals, der dem Trigger zugeordnet ist, im Format projects/{project}/locations/{location}/channels/{channel}. Wenn Sie diese Eigenschaft weglassen, werden Ereignisse im Standardchannel des Projekts überwacht.
eventTrigger.triggerRegion
(optional) 		Der Trigger empfängt nur Ereignisse, die in dieser Region ausgelöst werden. Sie kann dieselbe Region wie die Funktion, eine andere Region, mehrere Regionen oder die globale Region sein. Wenn keine Angabe erfolgt, wird standardmäßig dieselbe Region wie für 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 Lebenszyklusereignisse der 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 werden und taskQueue definiert haben.
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 werden und taskQueue definiert haben.
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 werden und taskQueue definiert haben.
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 von Ihrer Erweiterung ausgegeben werden, damit Nutzer ihre eigene Logik in Ihre Erweiterung einfügen können. Weitere Informationen finden Sie im Abschnitt zu Eventarc unter User-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 Typkennung des Ereignisses. Erstellen Sie die Kennung 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 veröffentlichten Ereignistyp einen eindeutigen und aussagekräftigen Ereignisnamen aus.
description
String
(erforderlich) 		Beschreibung des Termins.