Oft ist für Ihre Funktionen eine zusätzliche Konfiguration erforderlich, z. B. API-Schlüssel von Drittanbietern oder anpassbare Einstellungen. Das Firebase SDK für Cloud Functions bietet eine integrierte Umgebungskonfiguration, mit der Sie diese Art von Daten für Ihr Projekt ganz einfach speichern und abrufen können.
Sie haben die folgenden Optionen:
- Parametrisierte Konfiguration (für die meisten Szenarien empfohlen) Diese Option bietet eine stark typisierte Umgebungskonfiguration mit Parametern, die zur Bereitstellungszeit validiert werden. So werden Fehler vermieden und die Fehlersuche vereinfacht.
- Dateibasierte Konfiguration von Umgebungsvariablen Bei dieser Methode erstellen Sie manuell eine „dotenv“-Datei zum Laden von Umgebungsvariablen.
Für die meisten Anwendungsfälle wird die parametrisierte Konfiguration empfohlen. Bei dieser Methode sind Konfigurationswerte sowohl zur Laufzeit als auch zur Bereitstellungszeit verfügbar. Die Bereitstellung wird blockiert, wenn nicht alle Parameter einen gültigen Wert haben. Im Gegensatz dazu ist die Konfiguration mit Umgebungsvariablen zur Bereitstellungszeit nicht verfügbar.
Parametrisierte Konfiguration
Cloud Functions for Firebase bietet eine Schnittstelle zum deklarativen Definieren von Konfigurationsparametern in Ihrer Codebasis. Der Wert dieser Parameter ist sowohl bei der Funktionsbereitstellung, beim Festlegen von Bereitstellungs- und Laufzeitoptionen als auch bei der Ausführung verfügbar. Das bedeutet, dass die CLI die Bereitstellung blockiert, wenn nicht alle Parameter einen gültigen Wert haben.
So definieren Sie Parameter in Ihrem Code:
const functions = require('firebase-functions/v1');
const { defineInt, defineString } = require('firebase-functions/params');
// Define some parameters
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
const welcomeMessage = defineString('WELCOME_MESSAGE');
// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
res.send(`${welcomeMessage.value()}! I am a function.`);
}
);
Beim Bereitstellen einer Funktion mit parametrisierten Konfigurationsvariablen versucht die Firebase CLI zuerst, die Werte aus lokalen „.env“-Dateien zu laden. Wenn sie
in diesen Dateien nicht vorhanden sind und kein default festgelegt ist, werden Sie von der CLI während der Bereitstellung aufgefordert, die Werte anzugeben. Anschließend werden die Werte automatisch in einer
.env Datei mit dem Namen .env.<project_ID> im Verzeichnis functions/ gespeichert:
$ firebase deploy
i functions: preparing codebase default for deployment
? Enter a string value for ENVIRONMENT: prod
i functions: Writing new parameter values to disk: .env.projectId
…
$ firebase deploy
i functions: Loaded environment variables from .env.projectId
Je nach Entwicklungsablauf kann es sinnvoll sein, die generierte Datei .env.<project_ID> in die Versionsverwaltung aufzunehmen.
Parameter im globalen Gültigkeitsbereich verwenden
Während der Bereitstellung wird der Code Ihrer Funktionen geladen und geprüft, bevor Ihre Parameter tatsächliche Werte haben. Das bedeutet, dass das Abrufen von Parameterwerten im globalen Gültigkeitsbereich zu einem Bereitstellungsfehler führt. Wenn Sie einen Parameter verwenden möchten, um einen globalen Wert zu initialisieren, verwenden Sie den Initialisierungs-Callback onInit(). Dieser Callback wird ausgeführt, bevor Funktionen in der Produktion ausgeführt werden, aber nicht während der Bereitstellung. Daher ist er ein sicherer Ort, um auf den Wert eines Parameters zuzugreifen.
const { GoogleGenerativeAI } = require('@google/generative-ai');
const { defineSecret } = require('firebase-functions/params');
const { onInit } = require('firebase-functions/v1');
const apiKey = defineSecret('GOOGLE_API_KEY');
let genAI;
onInit(() => {
genAI = new GoogleGenerativeAI(apiKey.value());
})
CLI-Verhalten konfigurieren
Parameter können mit einem Options-Objekt konfiguriert werden, das steuert, wie die CLI nach Werten fragt. Im folgenden Beispiel werden Optionen festgelegt, um das Format einer Telefonnummer zu validieren, eine einfache Auswahloption bereitzustellen und eine Auswahloption automatisch aus dem Firebase-Projekt zu füllen:
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE', {default: 'Hello World',
description: 'The greeting that is returned to the caller of this function'});
const onlyPhoneNumbers = defineString('PHONE_NUMBER', {input: {text:
{validationRegex: /\d{3}-\d{3}-\d{4}/, validationErrorMessage: "Please enter
a phone number in the format XXX-YYY-ZZZZ"}}});
const selectedOption = defineString('PARITY', {input: {select: {options:
[{value: "odd"}, {value: "even"}]}}})
const storageBucket = defineString('BUCKET', {input: {resource: {type:
"storage.googleapis.com/Bucket"}}, description: "This will automatically
populate the selector field with the deploying Cloud Project’s
storage buckets"})
Parametertypen
Die parametrisierte Konfiguration bietet eine starke Typisierung für Parameterwerte und unterstützt auch Secrets aus Cloud Secret Manager. Folgende Typen werden unterstützt:
- Secret
- String
- Boolesch
- Ganzzahl
- Float
Informationen zu den Funktionen zum Definieren von Parametern finden Sie in der Referenz zum params Namespace.
Parameterwerte und -ausdrücke
Firebase wertet Ihre Parameter sowohl zur Bereitstellungszeit als auch während der Ausführung Ihrer Funktion aus. Aufgrund dieser beiden Umgebungen ist beim Vergleichen von Parameterwerten und bei der Verwendung zum Festlegen von Laufzeitoptionen für Ihre Funktionen besondere Vorsicht geboten.
Wenn Sie einen Parameter als Laufzeitoption an Ihre Funktion übergeben möchten, übergeben Sie ihn direkt:
const functions = require('firebase-functions/v1');
const { defineInt} = require('firebase-functions/params');
const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
//…
Wenn Sie außerdem einen Parameter vergleichen müssen, um die richtige Option auszuwählen, müssen Sie stattdessen integrierte Vergleichsoperatoren verwenden, anstatt den Wert zu prüfen:
const functions = require('firebase-functions/v1');
const { defineBool } = require('firebase-functions/params');
const environment = params.defineString(‘ENVIRONMENT’, {default: ‘dev’});
// use built-in comparators
const minInstancesConfig =environment.equals('PRODUCTION').thenElse(10, 1);
export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
(req, res) => {
//…
Auf Parameter und Parameterausdrücke, die nur zur Laufzeit verwendet werden, kann mit der Funktion value zugegriffen werden:
const functions = require('firebase-functions/v1');
const { defineString } = require('firebase-functions/params');
const welcomeMessage = defineString('WELCOME_MESSAGE');
// To use configured parameters inside the config for a function, provide them
// directly. To use them at runtime, call .value() on them.
export const helloWorld = functions.https.onRequest(
(req, res) => {
res.send(`${welcomeMessage.value()}! I am a function.`);
}
);
Integrierte Parameter
Das Cloud Functions SDK bietet drei vordefinierte Parameter, die über das Unterpaket firebase-functions/params verfügbar sind:
projectID: Das Cloud-Projekt, in dem die Funktion ausgeführt wird.databaseURL: Die URL der Realtime Database-Instanz, die mit der Funktion verknüpft ist (falls im Firebase-Projekt aktiviert).storageBucket: Der Cloud Storage-Bucket, der mit der Funktion verknüpft ist (falls im Firebase-Projekt aktiviert).
Diese funktionieren in jeder Hinsicht wie benutzerdefinierte Stringparameter. Da ihre Werte jedoch immer der Firebase CLI bekannt sind, werden Sie bei der Bereitstellung nicht aufgefordert, die Werte anzugeben, und sie werden auch nicht in .env-Dateien gespeichert.
Secret-Parameter
Parameter vom Typ Secret, die mit defineSecret() definiert werden, stellen String
parameter dar, deren Wert in Cloud Secret Manager gespeichert ist. Anstatt eine lokale .env-Datei zu prüfen und bei Bedarf einen neuen Wert in die Datei zu schreiben, wird bei Secret-Parametern geprüft, ob sie in Cloud Secret Manager vorhanden sind. Während der Bereitstellung werden Sie interaktiv aufgefordert, den Wert eines neuen Secrets anzugeben.
Auf diese Weise definierte Secret-Parameter müssen an einzelne Funktionen gebunden werden, die Zugriff darauf haben sollen:
const functions = require('firebase-functions/v1');
const { defineSecret } = require('firebase-functions/params');
const discordApiKey = defineSecret('DISCORD_API_KEY');
export const postToDiscord = functions.runWith({ secrets: [discordApiKey] }).https.onRequest(
(req, res) => {
const apiKey = discordApiKey.value();
//…
Umgebungsvariablen
Cloud Functions for Firebase unterstützt das
„dotenv“
Dateiformat zum Laden von Umgebungsvariablen, die in einer .env Datei angegeben sind, in die
Anwendungslaufzeit. Nach der Bereitstellung können die Umgebungsvariablen über die
process.env
-Schnittstelle gelesen werden.
So konfigurieren Sie Ihre Umgebung: Erstellen Sie eine .env-Datei in Ihrem Projekt, fügen Sie die gewünschten Variablen hinzu und stellen Sie sie bereit:
Erstellen Sie eine
.env-Datei im Verzeichnisfunctions/:# Directory layout: # my-project/ # firebase.json # functions/ # .env # package.json # index.jsÖffnen Sie die Datei
.envzur Bearbeitung und fügen Sie die gewünschten Schlüssel hinzu. Beispiel:PLANET=Earth AUDIENCE=HumansStellen Sie Funktionen bereit und prüfen Sie, ob die Umgebungsvariablen geladen wurden:
firebase deploy --only functions # ... # i functions: Loaded environment variables from .env. # ...
Nachdem Ihre benutzerdefinierten Umgebungsvariablen bereitgestellt wurden,
kann Ihr Funktionscode mit der
process.env
Syntax darauf zugreifen:
// Responds with "Hello Earth and Humans"
exports.hello = functions.https.onRequest((request, response) => {
response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});
Mehrere Sätze von Umgebungsvariablen bereitstellen
Wenn Sie einen alternativen Satz von Umgebungsvariablen für Ihre Firebase
Projekte benötigen (z. B. für die Staging- im Vergleich zur Produktionsumgebung), erstellen Sie eine
.env.<project or
alias> Datei und schreiben Sie dort die
projektspezifischen Umgebungsvariablen. Die Umgebungsvariablen aus .env- und projektspezifischen .env-Dateien (falls vorhanden) werden in alle bereitgestellten Funktionen aufgenommen.
Ein Projekt kann beispielsweise diese drei Dateien mit leicht unterschiedlichen Werten für die Entwicklung und Produktion enthalten:
.env
|
.env.dev
|
.env.prod
|
| PLANET=Earth
AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Prod Humans |
Angesichts der Werte in diesen separaten Dateien variiert der Satz der Umgebungsvariablen, die mit Ihren Funktionen bereitgestellt werden, je nach Zielprojekt:
$ firebase use dev
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.dev.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Dev Humans
$ firebase use prod
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.prod.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Prod Humans
Reservierte Umgebungsvariablen
Einige Umgebungsvariablenschlüssel sind für die interne Verwendung reserviert. Verwenden Sie keine dieser Schlüssel in Ihren .env-Dateien:
- Alle Schlüssel, die mit X_GOOGLE_ beginnen
- Alle Schlüssel, die mit EXT_ beginnen
- Alle Schlüssel, die mit FIREBASE_ beginnen
- Alle Schlüssel aus der folgenden Liste:
- CLOUD_RUNTIME_CONFIG
- ENTRY_POINT
- GCP_PROJECT
- GCLOUD_PROJECT
- GOOGLE_CLOUD_PROJECT
- FUNCTION_TRIGGER_TYPE
- FUNCTION_NAME
- FUNCTION_MEMORY_MB
- FUNCTION_TIMEOUT_SEC
- FUNCTION_IDENTITY
- FUNCTION_REGION
- FUNCTION_TARGET
- FUNCTION_SIGNATURE_TYPE
- K_SERVICE
- K_REVISION
- PORT
- K_CONFIGURATION
Vertrauliche Konfigurationsinformationen speichern und darauf zugreifen
Umgebungsvariablen, die in .env-Dateien gespeichert sind, können zur Funktionskonfiguration verwendet werden. Sie sollten sie jedoch nicht als sichere Möglichkeit zum Speichern vertraulicher Informationen wie Datenbankanmeldedaten oder API-Schlüssel betrachten. Das ist besonders wichtig, wenn Sie Ihre .env-Dateien in die Quellcodeverwaltung einchecken.
Um Ihnen beim Speichern vertraulicher Konfigurationsinformationen zu helfen, Cloud Functions for Firebase ist in Google Cloud Secret Manager integriert. Dieser verschlüsselte Dienst speichert Konfigurationswerte sicher und ermöglicht bei Bedarf einen einfachen Zugriff über Ihre Funktionen.
Secret erstellen und verwenden
Verwenden Sie die Firebase CLI, um ein Secret zu erstellen.
So erstellen und verwenden Sie ein Secret :
Führen Sie im Stammverzeichnis Ihres lokalen Projektverzeichnisses den folgenden Befehl aus:
firebase functions:secrets:set SECRET_NAME
Geben Sie einen Wert für SECRET_NAME ein.
Die CLI gibt eine Erfolgsmeldung aus und warnt Sie, dass Sie Funktionen bereitstellen müssen, damit die Änderung wirksam wird.
Prüfen Sie vor der Bereitstellung, ob der Code Ihrer Funktionen den Zugriff auf das Secret mit dem
runWithParameter zulässt:exports.processPayment = functions // Make the secret available to this function .runWith({ secrets: ["SECRET_NAME"] }) .onCall((data, context) => { const myBillingService = initializeBillingService( // reference the secret value process.env.SECRET_NAME ); // Process the payment });Cloud Functions bereitstellen:
firebase deploy --only functions
Jetzt können Sie wie bei jeder anderen Umgebungsvariable darauf zugreifen.
Wenn eine andere Funktion, die das Secret nicht in runWith angibt, versucht, auf das Secret zuzugreifen, erhält sie einen nicht definierten Wert:
exports.anotherEndpoint = functions.https.onRequest((request, response) => {
response.send(`The secret API key is ${process.env.SECRET_NAME}`);
// responds with "The secret API key is undefined" because the `runWith` parameter is missing
});
Nachdem Ihre Funktion bereitgestellt wurde, hat sie Zugriff auf den Secret-Wert. Nur
Funktionen, die ein Secret ausdrücklich in ihrem runWith Parameter angeben, haben als Umgebungsvariable Zugriff auf dieses Secret. So können Sie sicherstellen, dass Secret-Werte nur dort verfügbar sind, wo sie benötigt werden, und das Risiko einer versehentlichen Offenlegung eines Secrets wird verringert.
Secrets verwalten
Verwenden Sie die Firebase CLI, um Ihre Secrets zu verwalten. Beachten Sie dabei, dass einige CLI-Änderungen erfordern, dass Sie zugehörige Funktionen ändern und/oder neu bereitstellen. Zum Beispiel:
- Wenn Sie einen neuen Wert für ein Secret festlegen, müssen Sie alle Funktionen, die auf dieses Secret verweisen, neu bereitstellen, damit sie den neuesten Wert übernehmen.
- Wenn Sie ein Secret löschen, prüfen Sie, ob keine Ihrer bereitgestellten Funktionen auf dieses Secret verweist. Funktionen, die einen gelöschten Secret-Wert verwenden, schlagen ohne Fehlermeldung fehl.
Hier ist eine Zusammenfassung der Firebase CLI-Befehle für die Secret-Verwaltung:
# Change the value of an existing secret firebase functions:secrets:set SECRET_NAME # View the value of a secret functions:secrets:access SECRET_NAME # Destroy a secret functions:secrets:destroy SECRET_NAME # View all secret versions and their state functions:secrets:get SECRET_NAME # Automatically clean up all secrets that aren't referenced by any of your functions functions:secrets:prune
Für die Befehle access und destroy können Sie den optionalen Parameter `version` angeben, um eine bestimmte Version zu verwalten. Beispiel:
functions:secrets:access SECRET_NAME[@VERSION]
Weitere Informationen zu diesen Vorgängen erhalten Sie, indem Sie -h mit dem Befehl übergeben, um die CLI-Hilfe aufzurufen.
Abrechnung von Secrets
Secret Manager ermöglicht 6 aktive Secret Versionen kostenlos. Das bedeutet, dass Sie in einem Firebase-Projekt pro Monat 6 Secrets kostenlos verwenden können.
Standardmäßig versucht die Firebase CLI, nicht verwendete Secret
Versionen gegebenenfalls automatisch zu löschen, z. B. wenn Sie Funktionen mit einer neuen Version
des Secrets bereitstellen. Außerdem können Sie nicht verwendete Secrets aktiv mit functions:secrets:destroy und functions:secrets:prune bereinigen.
Secret Manager ermöglicht 10.000 nicht in Rechnung gestellte Zugriffe pro Monat auf ein
Secret. Funktionsinstanzen lesen nur die Secrets, die in ihrer Option secrets angegeben sind, bei jedem Kaltstart. Wenn viele Funktionsinstanzen viele Secrets lesen, kann Ihr Projekt dieses Kontingent überschreiten. In diesem Fall werden Ihnen 0,03 $ pro 10.000 Zugriffe in Rechnung gestellt.
Weitere Informationen finden Sie unter Secret Manager Preise.
Emulator-Unterstützung
Die Umgebungskonfiguration mit „dotenv“ ist für die Zusammenarbeit mit einem lokalen Cloud Functions Emulator konzipiert.
Wenn Sie einen lokalen Cloud Functions Emulator verwenden, können Sie Umgebung
variablen für Ihr Projekt überschreiben, indem Sie eine .env.local Datei einrichten. Der Inhalt von
.env.local hat Vorrang vor .env und der projektspezifischen .env-Datei.
Ein Projekt kann beispielsweise diese drei Dateien mit leicht unterschiedlichen Werten für die Entwicklung und lokale Tests enthalten:
.env
|
.env.dev
|
.env.local
|
| PLANET=Earth
AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Local Humans |
Wenn der Emulator im lokalen Kontext gestartet wird, werden die Umgebungsvariablen wie folgt geladen:
$ firebase emulators:start
i emulators: Starting emulators: functions
# Starts emulator with following environment variables:
# PLANET=Earth
# AUDIENCE=Local Humans
Secrets und Anmeldedaten im Cloud Functions Emulator
Der Cloud Functions Emulator unterstützt die Verwendung von Secrets zum Speichern und Abrufen vertraulicher Konfigurationsinformationen. Standardmäßig versucht der Emulator, mit den standardmäßigen Anmeldedaten der Anwendung auf Ihre Produktions-Secrets zuzugreifen. In bestimmten Situationen wie CI-Umgebungen kann der Emulator aufgrund von Berechtigungseinschränkungen möglicherweise nicht auf Secret-Werte zugreifen.
Ähnlich wie bei der Cloud Functions Emulatorunterstützung für Umgebungsvariablen können Sie
Secret-Werte überschreiben, indem Sie eine .secret.local Datei einrichten. So können Sie Ihre Funktionen ganz einfach lokal testen, insbesondere wenn Sie keinen Zugriff auf den Secret-Wert haben.
Von der Laufzeitkonfiguration migrieren
Die functions.config-API ist veraltet und wird im März 2027 außer Betrieb genommen.
Nach diesem Datum schlagen Bereitstellungen mit functions.config fehl.
Um Bereitstellungsfehler zu vermeiden, migrieren Sie Ihre Konfiguration mit der Firebase CLI zu Cloud Secret Manager. Dies wird dringend als effizienteste und sicherste Methode zum Migrieren Ihrer Konfiguration empfohlen.
Konfiguration mit der Firebase CLI exportieren
Verwenden Sie den Befehl
config export, um Ihre vorhandene Umgebungskonfiguration in ein neues Secret in Cloud Secret Manager zu exportieren:$ firebase functions:config:export i This command retrieves your Runtime Config values (accessed via functions.config()) and exports them as a Secret Manager secret. i Fetching your existing functions.config() from your project... ✔ Fetched your existing functions.config(). i Configuration to be exported: ⚠ This may contain sensitive data. Do not share this output. { ... } ✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG ✔ Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```Funktionscode aktualisieren, um Secrets zu binden
Wenn Sie die im neuen Secret in Cloud Secret Manager gespeicherte Konfiguration verwenden möchten, verwenden Sie die
defineJsonSecret-API in Ihrem Funktionsquellcode. Außerdem müssen Secrets an alle Funktionen gebunden sein, die sie benötigen.Vorher
const functions = require("firebase-functions/v1"); exports.myFunction = functions.https.onRequest((req, res) => { const apiKey = functions.config().someapi.key; // ... });Nachher
const { onRequest } = require("firebase-functions/v2/https"); const { defineJsonSecret } = require("firebase-functions/params"); const config = defineJsonSecret("RUNTIME_CONFIG"); exports.myFunction = onRequest( // Bind secret to your function { secrets: [config] }, (req, res) => { // Access secret values via .value() const apiKey = config.value().someapi.key; // ... });Funktionen bereitstellen
Stellen Sie Ihre aktualisierten Funktionen bereit, um die Änderungen zu übernehmen und die Secret-Berechtigungen zu binden.
firebase deploy --only functions:<your-function-name>
Automatisch eingefügte Umgebungsvariablen
Es gibt Umgebungsvariablen, die automatisch in der Funktionslaufzeit und in lokal emulierten Funktionen eingefügt werden. Dazu gehören die von Google Cloudeingefügten Variablen sowie eine Firebase-spezifische Umgebungsvariable:
process.env.FIREBASE_CONFIG: Enthält die folgenden Konfigurationsinformationen für das Firebase-Projekt:
{
databaseURL: 'https://DATABASE_NAME.firebaseio.com',
storageBucket: 'PROJECT_ID.firebasestorage.app ',
projectId: 'PROJECT_ID'
}
Beachten Sie, dass die Werte in Ihrer tatsächlichen Firebase-Konfiguration je nach den in Ihrem Projekt bereitgestellten Ressourcen variieren können.
Diese Konfiguration wird automatisch angewendet, wenn Sie das Firebase Admin SDK ohne Argumente initialisieren. Wenn Sie Funktionen in JavaScript schreiben, initialisieren Sie sie so:
const admin = require('firebase-admin');
admin.initializeApp();
Wenn Sie Funktionen in TypeScript schreiben, initialisieren Sie sie so:
import * as functions from 'firebase-functions/v1';
import * as admin from 'firebase-admin';
import 'firebase-functions/v1';
admin.initializeApp();
Wenn Sie das Admin SDK mit der Standardprojektkonfiguration mithilfe von Dienstkontoanmeldedaten initialisieren müssen, können Sie die Anmeldedaten aus einer Datei laden und sie so zu FIREBASE_CONFIG hinzufügen:
serviceAccount = require('./serviceAccount.json');
const adminConfig = JSON.parse(process.env.FIREBASE_CONFIG);
adminConfig.credential = admin.credential.cert(serviceAccount);
admin.initializeApp(adminConfig);