Parameter in der Erweiterung einrichten und verwenden

Parameter sind der Mechanismus, mit dem ein Nutzer jede installierte Instanz einer Erweiterung anpassen kann. Parameter sind wie die Umgebungsvariablen für eine Erweiterung. Die Werte für Parameter können entweder automatisch ausgefüllt (von Firebase nach der Installation bereitgestellt) oder nutzerkonfiguriert (vom Nutzer während der Installation angegeben) werden.

Sie können in Ihrem Funktionsquellcode, Ihrer extension.yaml-Datei und Ihrer POSTINSTALL.md-Datei auf diese Parameter verweisen. So referenzieren Sie einen Parameter namens PARAMETER_NAME:

  • Verwenden Sie im Quellcode Ihrer Funktionen das params-Modul (z. B. params.defineInt("PARAMETER_NAME")) oder process.env.PARAMETER_NAME.

  • Verwenden Sie in extension.yaml und POSTINSTALL.md ${param:PARAMETER_NAME}.

    Nach der Installation werden in der Firebase-Konsole die Inhalte der Datei POSTINSTALL.md angezeigt und alle Parameterverweise mit den tatsächlichen Werten für die installierte Instanz gefüllt.

Automatisch ausgefüllte Parameter

Jede installierte Instanz einer Erweiterung hat automatisch Zugriff auf mehrere Standardparameter, die von Firebase automatisch ausgefüllt werden (siehe Tabelle unten). Diese Parameterwerte sind entweder die Standardwerte für das Firebase-Projekt (z. B. der Standard-Storage-Bucket) oder sie sind extensionspezifisch (z. B. die Instanz-ID der Erweiterung).

Alle automatisch eingefügten Parameterwerte sind unveränderlich. Sie werden zum Zeitpunkt der Projekterstellung oder Erweiterungsinstallation festgelegt.

Auch wenn Firebase diese Parameterwerte für die Erweiterung automatisch ausfüllt, werden die zugehörigen Produkte für den Nutzer während der Installation nicht automatisch bereitgestellt. Der Nutzer, der die Erweiterung installiert, muss die zugehörigen und anwendbaren Produkte vor der Installation in seinem Projekt aktivieren. Wenn Ihre Erweiterung beispielsweise Cloud Firestore umfasst, muss der Nutzer Cloud Firestore in seinem Projekt einrichten. Wir empfehlen Ihnen, Ihre Nutzer in der PREINSTALL.md-Datei über diese Anforderungen zu informieren.

Referenz für automatisch ausgefüllte Parameter Beschreibung Parameterwert (von Firebase bereitgestellt)
Parameter mit Standardwerten aus dem Firebase-Projekt
PROJECT_ID Eindeutige Kennung für das Firebase-Projekt, in dem die Erweiterung installiert ist

Verallgemeinertes Format:
project-id

Beispielwert:
project-123

DATABASE_URL Die URL der Standard-Realtime Database-Instanz des Firebase-Projekts

Allgemeines Format:
https://project-id-default-rtdb.firebaseio.com
(US-Instanzen)
oder
https://project-id-default-rtdb.region-code.firebasedatabase.app
(Nicht-US-Instanzen)

Beispielwert:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Der Standardname der Realtime Database-Instanz des Firebase-Projekts

Normalerweise entspricht dieser Wert der Projekt-ID oder endet mit -default-rtdb.

Verallgemeinertes Format:
project-id

Beispielwert:
project-123

STORAGE_BUCKET Der Name des Standard-Cloud Storage-Buckets des Firebase-Projekts

Verallgemeinertes Format:
PROJECT_ID.firebasestorage.app

Beispielwert:
project-123.firebasestorage.app

Parameter mit Standardwert aus der Erweiterungsinstallation
EXT_INSTANCE_ID

Eindeutige Kennung für die installierte Erweiterungsinstanz

Dieser Wert wird aus dem Feld name generiert, das in der Datei extension.yaml angegeben ist.

Verallgemeinertes Format für die erste installierte Instanz (wird automatisch von Firebase zugewiesen; kann während der Installation nicht vom Nutzer geändert werden):
name-from-extension.yaml

Beispielwert:
my-awesome-extension


Allgemeines Format für die zweite und alle weiteren installierten Instanzen (wird automatisch von Firebase zugewiesen; kann während der Installation vom Nutzer geändert werden):
name-from-extension.yaml-4-digit-alphanumeric-hash

Beispielwert:
my-awesome-extension-6m31

Vom Nutzer konfigurierte Parameter

Wenn Sie es einem Nutzer ermöglichen möchten, jede installierte Instanz einer Erweiterung anzupassen, können Sie ihn bitten, während der Installation Parameterwerte anzugeben. Wenn Sie diese Werte anfordern möchten, richten Sie die Prompts im Abschnitt params Ihrer extension.yaml-Datei ein.

Unten sehen Sie ein Beispiel für einen params-Abschnitt, gefolgt von einer Tabelle mit allen verfügbaren Parameterfeldern.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

Verwenden Sie im Abschnitt params Ihrer Datei extension.yaml die folgenden Felder, um einen vom Nutzer konfigurierten Parameter zu definieren:

Feld Typ Beschreibung
param
(erforderlich) 		String Name des Parameters
label
(erforderlich) 		String

Kurze Beschreibung des Parameters

Wird dem Nutzer angezeigt, wenn er nach dem Wert des Parameters gefragt wird.

description
(optional) 		String

Ausführliche Beschreibung des Parameters

Wird dem Nutzer angezeigt, wenn er nach dem Wert des Parameters gefragt wird.

Unterstützt Markdown

type
(optional) 		String

Eingabemechanismus, mit dem der Nutzer den Wert des Parameters festlegt (z. B. Text direkt eingeben oder aus einer Drop-down-Liste auswählen)

Gültige Werte sind:

  • string: Ermöglicht die Eingabe von Freiformtext (gemäß den Einschränkungen durch Ihre validationRegex)
  • select: Ermöglicht die Auswahl eines Eintrags aus einer vordefinierten Liste von Optionen. Wenn Sie diesen Wert angeben, müssen Sie auch das Feld options definieren.
  • multiSelect: Ermöglicht die Auswahl eines oder mehrerer Einträge aus einer vordefinierten Liste von Optionen. Wenn Sie diesen Wert angeben, müssen Sie auch das Feld options definieren.
  • selectResource: Ermöglicht die Auswahl eines bestimmten Typs von Firebase-Ressource (z. B. eines Cloud Storage-Buckets) aus dem Projekt des Nutzers.

    Wenn Sie einen Parameter dieses Typs angeben, wird Nutzern in der Installations-UI ein benutzerfreundlicheres Auswahl-Widget angezeigt. Verwenden Sie daher nach Möglichkeit selectResource-Parameter.

    Wenn Sie diesen Wert angeben, müssen Sie auch das Feld resourceType definieren.

  • secret: Ermöglicht das Speichern sensibler Strings wie API-Schlüssel für Drittanbieterdienste. Diese Werte werden in Cloud Secret Manager gespeichert.

    Cloud Secret Manager ist ein kostenpflichtiger Dienst, dessen Nutzung zu Gebühren für Nutzer führen kann, die Ihre Erweiterung installieren. Wenn Sie den Parametertyp secret verwenden, müssen Sie in Ihrer PREINSTALL-Datei dokumentieren, dass Ihre Erweiterung Cloud Secret Manager verwendet.

Wenn dieses Feld weggelassen wird, wird standardmäßig der Parameter type mit dem Wert string verwendet.

options
(erforderlich, wenn der Parameter type select oder multiSelect ist) 		list

Liste der Werte, aus denen der Nutzer auswählen kann

Fügen Sie die Felder label und value in das Feld options ein:

  • label (String): Kurze Beschreibung der auswählbaren Option.
  • value (String): Der tatsächliche Wert der auswählbaren Option.

Das Feld value ist für das Feld options erforderlich.
Wenn label weggelassen wird, wird standardmäßig value angezeigt.
resourceType
(erforderlich, wenn der Parameter type selectResource ist) 		String

Der Typ der Firebase-Ressource, die der Nutzer auswählen soll. Derzeit unterstützen nur Cloud Storage-Buckets Ressourcenauswahlen:

Ressourcentyp Typ-ID
Cloud Storage Bucket storage.googleapis.com/Bucket

Unbekannte resourceType-Werte werden ignoriert und in der Benutzeroberfläche wird der Parameter als string-Eingabefeld für Freiformtext gerendert.
example
(optional) 		String

Beispielwert für den Parameter
validationRegex
(optional)
(gilt nur, wenn der Parameter type gleich string ist) 		String

Regulärer Ausdruck zur Validierung des vom Nutzer konfigurierten Werts des Parameters

Reguläre Ausdrücke werden mit der Go-Bibliothek RE2 kompiliert.

Weitere Informationen zur Validierung finden Sie unten unter Validierung und Fehlermeldungen.

validationErrorMessage
(optional) 		String

Fehlermeldung, die angezeigt werden soll, wenn validationRegex fehlschlägt

Weitere Informationen zu Fehlermeldungen finden Sie unten unter Validierung und Fehlermeldungen.

default
(optional) 		String

Standardwert für den Parameter, wenn der Nutzer den Wert des Parameters leer lässt

Falls zutreffend, können Sie einen automatisch eingefügten Parameter für den Wert default angeben (ein Beispiel finden Sie im Parameter IMG_BUCKET der Erweiterung „Bildgröße ändern“).

required
(optional) 		boolean

Gibt an, ob der Nutzer einen leeren String senden kann, wenn er nach dem Wert des Parameters gefragt wird.

Wenn required weggelassen wird, ist der Standardwert true (d. h. ein erforderlicher Parameter).

immutable
(optional) 		boolean

Gibt an, ob der Nutzer den Wert des Parameters nach der Installation ändern kann, z. B. wenn er die Erweiterung neu konfiguriert.

Wenn immutable weggelassen wird, wird standardmäßig false verwendet.

Hinweis:Wenn Sie einen „location“-Parameter> für die bereitgestellten Funktionen Ihrer Erweiterung definieren, sollten Sie dieses immutable-Feld in das zugehörige „param“-Objekt einfügen.

Validierung und Fehlermeldungen für nutzerkonfigurierte Werte

Wenn Sie einen Parameter mit dem type von string einrichten, müssen Sie eine entsprechende Regex-Validierung über das Feld validationRegex des Parameters definieren.

Außerdem ist für viele Erweiterungen ein häufig angeforderter Parameterwert ein Datenbankpfad oder ein Cloud Storage-Bucket. Beachten Sie, dass der Extensions-Dienst während der Installation, Neukonfiguration oder Aktualisierung die folgenden Punkte zum Zeitpunkt der Eingabe des Parameterwerts nicht validiert:

  • Ob die angegebene Datenbank oder der Cloud Storage-Bucket im Firebase-Projekt des Nutzers eingerichtet ist
  • Gibt an, ob der angegebene Datenbankpfad in der Datenbank des Nutzers vorhanden ist.

Wenn die Erweiterung jedoch ihre Ressourcen bereitstellt, wird in der Firebase-Konsole oder der Firebase-Befehlszeile eine Fehlermeldung angezeigt, wenn die referenzierte Datenbank oder der Cloud Storage-Bucket noch nicht im Projekt eingerichtet ist.

Wir empfehlen dringend, Nutzer in der Datei PREINSTALL über diese Anforderungen zu informieren, damit Ihre Erweiterung bei der Installation erfolgreich installiert wird und wie erwartet funktioniert.

Systemparameter

Systemparameter steuern die grundlegende Konfiguration der Ressourcen einer Erweiterung. Da sie zur Steuerung der Ressourcenkonfiguration vorgesehen sind, sind sie nicht als Umgebungsvariablen in Ihrem Funktionscode verfügbar.

Normalerweise müssen Sie für diese Parameter in extension.yaml nichts deklarieren. Sie werden automatisch für jede Erweiterungsinstanz definiert und Nutzer haben die Möglichkeit, beim Installieren Ihrer Erweiterung benutzerdefinierte Werte festzulegen.

Wenn Ihre Erweiterung jedoch spezielle Ressourcenanforderungen hat, können Sie in extension.yaml spezifische Werte auf Ressourcenebene festlegen. Diese Konfigurationseinstellungen pro Ressource überschreiben die einstellungsweiten Einstellungen der Erweiterungsinstanz des Nutzers. Beispiel:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

Folgende Systemparameter sind verfügbar:

Name Label (von Menschen lesbar) Entsprechendes Feld in properties Beschreibung
firebaseextensions.v1beta.function/location Standort location In welcher Region sollten Cloud Functions bereitgestellt werden?
firebaseextensions.v1beta.function/memory Funktionsspeicher memory Wie viele Megabyte Arbeitsspeicher sollen jeder Funktion zugewiesen werden?
firebaseextensions.v1beta.function/timeoutSeconds Zeitlimit für Funktion timeout Wie viele Sekunden sollten Funktionen ausgeführt werden, bevor das Zeitlimit überschritten wird?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Ausgehender VPC-Connector-Traffic vpcConnectorEgressSettings Steuert ausgehenden Traffic, wenn ein VPC-Connector konfiguriert ist
firebaseextensions.v1beta.function/vpcConnector VPC-Connector vpcConnector Verbindet Cloud Functions mit dem angegebenen VPC-Connector.
firebaseextensions.v1beta.function/minInstances Mindestanzahl von Funktionsinstanzen minInstances Die Mindestanzahl von Instanzen dieser Funktion, die gleichzeitig ausgeführt werden sollen
firebaseextensions.v1beta.function/maxInstances Maximale Anzahl von Funktionsinstanzen maxInstances Die maximale Anzahl von Instanzen dieser Funktion, die gleichzeitig ausgeführt werden können
firebaseextensions.v1beta.function/ingressSettings Einstellungen für eingehenden Traffic ingressSettings Steuert, von wo eingehender Traffic akzeptiert wird
firebaseextensions.v1beta.function/labels Labels labels Labels, die auf alle Ressourcen in der Erweiterung angewendet werden sollen