Referenz für extension.yaml

Die Spezifikationsdatei (extension.yaml) Ihrer Erweiterung enthält die Metadaten der Erweiterung, deklariert die von der Erweiterung erstellten Ressourcen sowie die von der Erweiterung benötigten APIs und Zugriffsrechte und definiert alle von der Erweiterung bereitgestellten, vom Nutzer 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. Maximal 40 Zeichen.

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

version
String
(erforderlich)

Version der Erweiterung.

Muss der semver-Versionsverwaltung folgen (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
Boolesch
(optional)

Gibt an, ob für die von der Erweiterung verwendeten Dienste ein kostenpflichtiges Firebase-Rechnungskonto erforderlich ist.

Immer auf true gesetzt.
displayName
String
(optional)

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

Maximal 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 in extensions.dev und der Firebase-Konsole verwendet werden soll.

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

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

  • Wähle Hintergrund- und Artwork-Farben aus, die zu deiner Marke passen.
  • Verwenden Sie nur zwei Farben für Ihr Symbol. Mehrere Farben können dazu führen, dass Ihr Symbol visuell überladen wirkt.
  • Aus demselben Grund sollten Sie in Ihrem Symbol keine Farbverläufe verwenden. Farbverlä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 Ihr Logo nicht als Symbol. Nutzer werden Schwierigkeiten haben, zwischen Ihren Erweiterungen zu unterscheiden.
  • Das Bild soll grafisch und auffällig sein. Verwenden Sie keine filigranen oder aufwendigen Grafiken, die bei kleineren Größen nicht gut dargestellt werden.
  • Verwenden Sie keine Wörter, die erklären, was Ihre Erweiterung tut. Text ist bei kleineren Größen oft unleserlich.
tags
Liste von Strings
(optional) 		Tags, mit denen Nutzer Ihre Erweiterung leichter finden können. Die folgenden Tags sind 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, unter der die Versionshinweise für die Erweiterung aufgerufen werden können.
author
Ein „author“-Objekt
(optional)

Hauptautor 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, unter der Informationen zum Autor abgerufen werden können.
contributors
Liste der Autorenobjekte
(optional)

Zusätzliche Autoren, die an der Erweiterung mitgewirkt haben.

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, 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 die Erweiterung verwendet. 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 der jeweiligen 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 Ausführung der Erweiterung erforderlich ist

Muss eine der unterstützten Rollen sein

reason
String
(erforderlich) 		Kurze Beschreibung, warum die Erweiterung den Zugriff benötigt, der durch diese Rolle gewährt wird
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 die Erweiterung verwendet (normalerweise REST APIs). Die Firebase Extensions-Plattform bietet keine Möglichkeit, diese Dienste automatisch zu aktivieren oder zu autorisieren.

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 Erweiterung erforderlich ist
pricingUri
String
(erforderlich) 		URI zu Preisinformationen für den Dienst

Vom Nutzer konfigurierbare Parameter

In diesen Feldern werden die Parameter definiert, die die Erweiterung für Nutzer zur Konfiguration bereitstellt.

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 verweisen Sie im Code auf den Parameterwert.
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 werden soll, wenn die Regex-Validierung fehlschlägt.
required
Boolesch
(optional) 		Definiert, ob der Nutzer einen leeren String senden kann, wenn er zur Eingabe des Parameterwerts aufgefordert wird. Die Standardeinstellung ist true.
immutable
Boolesch
(optional)

Legt fest, 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 eine andere UI-Darstellung. Weitere Informationen finden Sie in den folgenden Abschnitten.

Auswählbare und mehrfach auswählbare Parameter

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 für Multiple-Choice-Fragen
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 die Standardeinstellung value.

Auswählbare Ressourcenparameter

Bei auswählbaren Ressourcenparametern werden Nutzer aufgefordert, 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
Ressourcenparameterfelder
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 Auswahl-UI. Andere Ressourcentypen werden als Eingabefelder für beliebigen Text dargestellt.

Secret-Parameter

Vom Nutzer 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 Secret-Wert ist

Cloud Functions-Ressourcen

In diesen Feldern werden die Cloud Functions-Funktionen deklariert, die in einer Erweiterung enthalten sind. Die Syntax für die Ressourcendeklaration unterscheidet sich geringfügig zwischen Funktionen der 1. und 2. Generation, die in einer Erweiterung gleichzeitig vorhanden sein 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 das Attribut entryPoint 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)

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

Properties
location
(optional)

Standort, an dem die Funktion bereitgestellt werden soll. Die Standardeinstellung ist us-central1.
entryPoint
(optional) 		Name der exportierten Funktion im Quellcode Ihrer Funktionen, nach der die Erweiterung suchen soll. Der Standardwert ist der Wert von name (siehe oben).
sourceDirectory
(optional)

Verzeichnis, das Ihre 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: Das Feld main von package.json gibt die Datei für den Quellcode Ihrer Funktionen an (z. B. index.js).
timeout
(optional)

Die maximale Ausführungszeit der Funktion.

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

Für die Funktion verfügbarer Arbeitsspeicher in MB.

  • Standardwert: 256
  • Zulässige Werte: 128, 256, 512, 1024 und 2048
runtime
(empfohlen)

Laufzeitumgebung für die Funktion.
httpsTrigger
oder
eventTrigger
oder
scheduleTrigger
oder
taskQueueTrigger
(einer dieser Funktionstriggertypen ist erforderlich) 		Spezifische Informationen zu den einzelnen Triggertypen finden Sie unter Cloud Functions-Funktionen für eine Erweiterung schreiben.

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 das Attribut entryPoint 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)

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

Properties
location
(optional)

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

Verzeichnis, das Ihre 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: Das Feld main von package.json gibt die Datei für den Quellcode Ihrer Funktionen an (z. B. index.js).

Außerdem gibt es drei Felder vom Typ „Objekt“ mit eigenen Attributen:

buildConfig-Attribute
buildConfig.runtime
(empfohlen)

Laufzeitumgebung für die Funktion.
buildConfig.entryPoint
(optional) 		Name der exportierten Funktion im Quellcode Ihrer Funktionen, nach der die Erweiterung suchen soll. Der Standardwert ist der Wert von name (siehe oben).
serviceConfig-Attribute
serviceConfig.timeoutSeconds
(optional)

Die maximale Ausführungszeit der Funktion.

  • Standardwert: 60
  • Maximalwert: 540
serviceConfig.availableMemory
(optional) 		Die Größe des für eine Funktion verfügbaren Arbeitsspeichers. 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. Eine Liste der für die einzelnen Produkte verfügbaren Ereignistypen finden Sie unter Cloud Functions-Funktionen für eine Erweiterung schreiben.
eventTrigger.eventFilters
(optional) 		Filter, mit denen die zu erfassenden Ereignisse weiter eingeschränkt werden. Sie können beispielsweise nur Ereignisse überwachen, 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 dieses Attribut weglassen, überwacht die Funktion Ereignisse im Standardkanal des Projekts.
eventTrigger.triggerRegion
(optional) 		Der Trigger empfängt nur Ereignisse, die aus dieser Region stammen. Es kann dieselbe Region wie die Funktion, eine andere Region, eine multiregionale Region oder die globale Region sein. Wenn keine Angabe erfolgt, wird standardmäßig dieselbe Region wie die Funktion verwendet.

Lifecycle-Events

Mit Lebenszyklus-Ereignissen 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-Events 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 Lifecycle-Events
onInstall
(optional)

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

Funktionsspezifikation
function
String
(erforderlich)

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

Diese Funktion muss im Abschnitt resources deklariert werden und taskQueue muss definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt werden soll, 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 von der Aufgabenwarteschlange ausgelösten Funktion, die das Ereignis verarbeitet.

Diese Funktion muss im Abschnitt resources deklariert werden und taskQueue muss definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt werden soll, 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 von der Aufgabenwarteschlange ausgelösten Funktion, die das Ereignis verarbeitet.

Diese Funktion muss im Abschnitt resources deklariert werden und taskQueue muss definiert sein.
processingMessage
String
(erforderlich) 		Nachricht, die in der Firebase Console angezeigt werden soll, 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 „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
Benutzerdefinierte Ereignisfelder
type
String
(erforderlich) 		Die Typkennung des Ereignisses. Erstellen Sie die Kennung aus drei bis vier durch Punkte getrennten Feldern: Die Felder für die Publisher-ID, den Erweiterungsnamen und den Ereignisnamen sind erforderlich. Das Version-Feld wird empfohlen. Wählen Sie für jeden Ereignistyp, den Sie veröffentlichen, einen eindeutigen und aussagekräftigen Ereignisnamen aus.
description
String
(erforderlich) 		Beschreibung des Termins.