Parameter in der Erweiterung einrichten und verwenden

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

Auf diese Parameter können Sie im Funktionsquellcode, Ihre extension.yaml-Datei und Ihre POSTINSTALL.md -Datei. Hier ist die Syntax für den Verweis auf einen Parameter namens PARAMETER_NAME:

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

  • Verwende innerhalb von extension.yaml und POSTINSTALL.md ${param:PARAMETER_NAME}.

    Nach der Installation zeigt die Firebase-Konsole den Inhalt der POSTINSTALL.md und gibt alle Parameterverweise mit dem Parameter tatsächlich-Werte für die installierte Instanz.

Automatisch ausgefüllte Parameter

Jede installierte Instanz einer Erweiterung hat automatisch Zugriff auf mehrere standardmäßig von Firebase automatisch ausgefüllte Parameter (siehe Tabelle) unten). Diese Parameterwerte sind entweder die Standardwerte für das Firebase- wie der Storage-Bucket default, oder sie sind erweiterungsspezifisch (z. B. Instanz-ID der Erweiterung).

Alle automatisch ausgefüllten Parameterwerte sind unveränderlich. Sie werden auf den Zeitpunkt festgelegt, oder Erweiterungen installieren.

Obwohl Firebase diese Parameterwerte für die Erweiterung automatisch eingibt, Firebase stellt die verknüpften Produkte für den Nutzer während Installation. Der Nutzer, der die Erweiterung installiert, muss die zugehörige und die entsprechenden Produkte in ihrem Projekt vor der Installation. Wenn beispielsweise Ihre Erweiterung Cloud Firestore enthält, muss der Nutzer Cloud Firestore in ihrem Projekt arbeiten. Wir empfehlen Ihnen, Ihre Nutzer über diese Anforderungen in die PREINSTALL.md Datei.

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

Generalisiertes Format:
project-id

Beispielwert:
project-123

DATABASE_URL Die standardmäßige Realtime Database-Instanz-URL des Firebase-Projekts

Generalisiertes Format:
https://project-id-default-rtdb.firebaseio.com
(in den USA)
oder
https://project-id-default-rtdb.region-code.firebasedatabase.app
(außerhalb der USA)

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

DATABASE_INSTANCE

Der standardmäßige Realtime Database-Instanzname des Firebase-Projekts

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

Generalisiertes Format:
project-id

Beispielwert:
project-123

STORAGE_BUCKET Der Standardname des Cloud Storage-Buckets des Firebase-Projekts

Generalisiertes Format:
project-id.appspot.com

Beispielwert:
project-123.appspot.com

Parameter mit Standardwert aus der Installation der Erweiterung
EXT_INSTANCE_ID

Eindeutige Kennung für die installierte Erweiterungs-Instanz

Dieser Wert wird aus dem in der Datei extension.yaml angegebenen Feld name generiert.

Generalisiertes Format für die erste installierte Instanz (automatisch zugewiesen) durch Firebase, nicht während der Installation vom Nutzer geändert werden dürfen):
name-from-extension.yaml

Beispielwert:
my-awesome-extension


Verallgemeinertes Format für die zweite und höher installierte Instanz (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

Um einem Nutzer zu ermöglichen, die installierten Instanzen einer Erweiterung individuell anzupassen, haben Sie folgende Möglichkeiten: den Nutzer während der Installation auffordern, Parameterwerte anzugeben. So fordern Sie diese an: -Werte festlegen, richten Sie die Prompts im Abschnitt params Ihrer extension.yaml ein -Datei.

Hier ist ein Beispiel für einen params-Abschnitt, gefolgt von einer Tabelle, in der alle verfügbaren Parameter-Feldern.

# 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 der Datei extension.yaml die folgenden Felder, um einen benutzerdefinierten 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 zur Eingabe des Parameters Wert

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, der festlegt, wie der Wert des Parameters durch den Nutzer festgelegt wird (für (z. B. Text direkt eingeben oder aus der Drop-down-Liste auswählen)

Gültige Werte sind:

  • string: ermöglicht die Eingabe von Freitext (durch Ihr validationRegex)
  • select: ermöglicht die Auswahl eines Eintrags aus einer vordefinierte Liste von Optionen. Bei Angabe dieses Werts müssen Sie auch die options definieren ein.
  • multiSelect: ermöglicht die Auswahl eines oder mehrerer Einträge aus einer vordefinierten Liste von Optionen. Bei Angabe dieses Werts müssen Sie auch die options definieren ein.
  • selectResource: ermöglicht die Auswahl eines bestimmten Typ der Firebase-Ressource (z. B. ein Cloud Storage-Bucket) aus dem Projekt des Nutzers.

    Wenn Sie einen Parameter dieses Typs angeben, erhalten Nutzer eine stärkere nutzerfreundliches Auswahl-Widget auf der Installations-UI dafür selectResource-Parameter verwenden, wenn möglich.

    Wenn Sie diesen Wert angeben, müssen Sie auch die resourceType ein.

  • secret: Ermöglicht das Speichern sensibler Strings, z. B. API-Schlüssel für Dienste von Drittanbietern. Diese Werte werden gespeichert in Cloud Secret Manager:

    Cloud Secret Manager ist ein kostenpflichtiger Dienst, dessen Nutzung für Nutzer, die Ihre Erweiterung installieren, zu Kosten führen kann. Wenn Sie den Parametertyp secret haben, dokumentieren Sie ihn Deine Vorinstallation Datei, dass Ihre Erweiterung Cloud Secret Manager verwendet.

Wenn dieses Feld weggelassen wird, wird standardmäßig type verwendet. von string.

options
(erforderlich bei Parameter type) ist select oder multiSelect) 		list

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

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

  • label (string): kurze Beschreibung des auswählbare Option
  • value (String): Der tatsächliche Wert der auswählbaren Option.

Das Feld value ist für options erforderlich ein.
Wenn label weggelassen wird, wird standardmäßig die Listenoption value
resourceType
(erforderlich bei Parameter type) ist selectResource) 		String

Der Typ der Firebase-Ressource, die der Nutzer auswählen soll. Derzeit werden nur Cloud Storage-Buckets mit Ressourcenelektoren unterstützt:

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

Unbekannte resourceType-Werte werden ignoriert und die UI wird ignoriert. rendert den Parameter als Eingabe für string im freien Format ein.
example
(optional) 		String

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

Regex-String zur Validierung des vom Nutzer konfigurierten Werts des Parameters

Regex wird mit der Go-Bibliothek „RE2“ kompiliert.

Weitere Informationen zur Überprüfung finden Sie unten unter Bestätigung und Fehlermeldungen.

validationErrorMessage
(optional) 		String

Fehlermeldung, die angezeigt wird, wenn der validationRegex Fehlgeschlagen

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

default
(optional) 		String

Standardwert für den Parameter, wenn der Nutzer die Einstellung Kein Wert

Bei Bedarf können Sie automatisch ausgefüllter Parameterwert für den Wert default. Ein Beispiel finden Sie im IMG_BUCKET des Parameters Erweiterung Bildgröße anpassen)

required
(optional) 		boolean

Legt fest, ob der Nutzer einen leeren String senden kann, wenn er zur Eingabe des Parameterwerts aufgefordert

Wenn required weggelassen wird, wird der Wert standardmäßig auf true gesetzt (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 der folgende Wert verwendet: false.

Hinweis:Wenn Sie eine „Standort“ Parameter für die bereitgestellten Funktionen der Erweiterung, sollten Sie das Feld immutable in den Parameter -Objekt enthält.

Validierung und Fehlermeldungen für vom Nutzer konfigurierte Werte

Wenn Sie einen Parameter mit dem type von string einrichten, müssen Sie Regex-Validierung über die Parameter validationRegex.

Bei vielen Erweiterungen ist ein häufig angeforderter Parameterwert Pfad oder Cloud Storage-Bucket. Beachten Sie, dass während der Installation, Neukonfiguration oder aktualisiert wird, validiert der Extensions-Dienst Folgendes nicht am Zeitpunkt des Parameterwerteintrags:

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

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

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

Systemparameter

Systemparameter steuern die grundlegende Konfiguration der Ressourcen einer Erweiterung. Da mit ihnen die Ressourcenkonfiguration gesteuert werden soll, Sie sind im Funktionscode nicht als Umgebungsvariablen zugänglich.

Normalerweise müssen Sie für diese Parameter in extension.yaml Sie werden automatisch für jede Erweiterungsinstanz definiert, und Nutzer haben die Möglichkeit, benutzerdefinierte Werte festzulegen, wenn sie Ihre App installieren. .

Wenn Ihre Erweiterung jedoch spezielle Ressourcenanforderungen hat, Sie können in extension.yaml spezifische Werte auf Ressourcenebene festlegen. Diese ressourcenspezifischen Konfigurationseinstellungen überschreiben die Erweiterung des Nutzers instanzweiten Einstellungen. 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 (für Menschen geeignet) Entsprechendes Feld in properties Beschreibung
firebaseextensions.v1beta.function/location Standort location In welcher Region soll Cloud Functions bereitgestellt werden?
firebaseextensions.v1beta.function/memory Funktionsspeicher memory Wie viele Megabyte Arbeitsspeicher sollten jeder Funktion zugewiesen werden?
firebaseextensions.v1beta.function/timeoutSeconds Zeitlimit für Funktion timeout Wie viele Sekunden sollten Funktionen ausgeführt werden, bevor eine Zeitüberschreitung auftritt?
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 soll
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