Konfigurieren Sie Ihre Umgebung

Häufig benötigen Sie zusätzliche Konfigurationen für Ihre Funktionen, z. B. API-Schlüssel von Drittanbietern oder anpassbare Einstellungen. Das Firebase SDK for Cloud Functions bietet eine integrierte Umgebungskonfiguration, um das Speichern und Abrufen dieser Art von Daten für Ihr Projekt zu vereinfachen.

Sie können zwischen der dateibasierten Konfiguration von Umgebungsvariablen (empfohlen) oder der Laufzeitumgebungskonfiguration mit der Firebase-CLI und functions.config wählen. Beide Vorgehensweisen werden in diesem Leitfaden beschrieben.

Umgebungsvariablen

Cloud Functions for Firebase unterstützt das dotenv -Dateiformat zum Laden von Umgebungsvariablen, die in einer .env -Datei angegeben sind, in Ihre Anwendungslaufzeit. Nach der Bereitstellung können die Umgebungsvariablen über die Schnittstelle process.env gelesen werden.

Um Ihre Umgebung auf diese Weise zu konfigurieren, erstellen Sie eine .env -Datei in Ihrem Projekt, fügen Sie die gewünschten Variablen hinzu und stellen Sie Folgendes bereit:

  1. Erstellen Sie eine .env -Datei in Ihrem functions/ -Verzeichnis:

    # Directory layout:
    #   my-project/
    #     firebase.json
    #     functions/
    #       .env
    #       package.json
    #       index.js
    
  2. Öffnen Sie die .env -Datei zum Bearbeiten und fügen Sie die gewünschten Schlüssel hinzu. Zum Beispiel:

    PLANET=Earth
    AUDIENCE=Humans
    
  3. Stellen Sie Funktionen bereit und überprüfen Sie, ob Umgebungsvariablen geladen wurden:

    firebase deploy --only functions
    # ...
    # i functions: Loaded environment variables from .env.
    # ...
    

Sobald Ihre benutzerdefinierten Umgebungsvariablen bereitgestellt sind, 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}`);
});

Bereitstellen mehrerer Gruppen von Umgebungsvariablen

Wenn Sie einen alternativen Satz von Umgebungsvariablen für Ihre Firebase-Projekte benötigen (z. B. Staging vs. Produktion), erstellen Sie eine .env. <project or alias > file und schreiben Sie dort Ihre projektspezifischen Umgebungsvariablen. Die Umgebungsvariablen aus .env und projektspezifischen .env -Dateien (falls vorhanden) werden in alle bereitgestellten Funktionen eingeschlossen.

Ein Projekt könnte beispielsweise diese drei Dateien enthalten, die leicht unterschiedliche Werte für Entwicklung und Produktion enthalten:

.env .env.dev .env.prod
PLANET=Erde

PUBLIKUM=Menschen

PUBLIKUM=Entwicklermenschen PUBLIKUM = Prod Menschen

Angesichts der Werte in diesen separaten Dateien variiert der Satz von 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 keinen dieser Schlüssel in Ihren .env Dateien:

  • Alle Schlüssel beginnend mit X_GOOGLE_
  • Alle Tasten ab EXT_
  • Alle Schlüssel beginnend mit FIREBASE_
  • Beliebiger Schlüssel aus der folgenden Liste:
  • CLOUD_RUNTIME_CONFIG
  • EINSTIEGSPUNKT
  • GCP_PROJECT
  • GCLOUD_PROJEKT
  • GOOGLE_CLOUD_PROJECT
  • FUNCTION_TRIGGER_TYPE
  • FUNKTIONSNAME
  • FUNCTION_MEMORY_MB
  • FUNCTION_TIMEOUT_SEC
  • FUNKTION_IDENTITÄT
  • FUNCTION_REGION
  • FUNCTION_TARGET
  • FUNCTION_SIGNATURE_TYPE
  • K_SERVICE
  • K_REVISION
  • HAFEN
  • K_KONFIGURATION

Speichern Sie vertrauliche Konfigurationsinformationen und greifen Sie darauf zu

In .env Dateien gespeicherte Umgebungsvariablen können für die Funktionskonfiguration verwendet werden, aber Sie sollten sie nicht als sichere Methode zum Speichern vertraulicher Informationen wie Datenbankanmeldeinformationen oder API-Schlüssel betrachten. Dies ist besonders wichtig, wenn Sie Ihre .env Dateien in die Quellcodeverwaltung einchecken.

Damit Sie vertrauliche Konfigurationsinformationen speichern können, lässt sich Cloud Functions for Firebase in Google Cloud Secret Manager integrieren. Dieser verschlüsselte Dienst speichert Konfigurationswerte sicher und ermöglicht dennoch bei Bedarf einen einfachen Zugriff von Ihren Funktionen aus.

Erstellen und verwenden Sie ein Geheimnis

Verwenden Sie zum Erstellen eines Geheimnisses die Firebase-Befehlszeilenschnittstelle.

So erstellen und verwenden Sie ein Geheimnis:

  1. Führen Sie im Stammverzeichnis Ihres lokalen Projektverzeichnisses den folgenden Befehl aus:

    firebase functions:secrets:set SECRET_NAME

  2. Geben Sie einen Wert für SECRET_NAME ein.

    Die CLI gibt eine Erfolgsmeldung zurück und warnt Sie, dass Sie Funktionen bereitstellen müssen, damit die Änderung wirksam wird.

  3. Stellen Sie vor der Bereitstellung sicher, dass Ihr Funktionscode der Funktion den Zugriff auf das Geheimnis mithilfe des Parameters runWith :

    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
      });
  4. Cloud-Funktionen bereitstellen:

    firebase deploy --only functions

Jetzt können Sie wie auf jede andere Umgebungsvariable darauf zugreifen. Wenn umgekehrt eine andere Funktion, die das Geheimnis nicht in runWith , versucht, auf das Geheimnis zuzugreifen, erhält sie einen undefinierten 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
});

Sobald Ihre Funktion bereitgestellt ist, hat sie Zugriff auf den geheimen Wert. Nur Funktionen, die ausdrücklich ein Geheimnis in ihren runWith Parameter aufnehmen, haben Zugriff auf dieses Geheimnis als Umgebungsvariable. Auf diese Weise können Sie sicherstellen, dass geheime Werte nur dort verfügbar sind, wo sie benötigt werden, und das Risiko verringern, versehentlich ein Geheimnis preiszugeben.

Geheimnisse verwalten

Verwenden Sie die Firebase CLI, um Ihre Geheimnisse zu verwalten. Denken Sie bei der Verwaltung von Geheimnissen auf diese Weise daran, dass einige CLI-Änderungen erfordern, dass Sie zugehörige Funktionen ändern und/oder erneut bereitstellen. Speziell:

  • Immer wenn Sie einen neuen Wert für ein Geheimnis festlegen, müssen Sie alle Funktionen, die auf dieses Geheimnis verweisen, erneut bereitstellen, damit sie den neuesten Wert übernehmen.
  • Wenn Sie ein Geheimnis löschen, stellen Sie sicher, dass keine Ihrer bereitgestellten Funktionen auf dieses Geheimnis verweist. Funktionen, die einen gelöschten geheimen Wert verwenden, schlagen unbemerkt fehl.

Hier ist eine Zusammenfassung der Firebase CLI-Befehle für die geheime 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 access und destroy können Sie den optionalen Versionsparameter angeben, um eine bestimmte Version zu verwalten. Zum Beispiel:

functions:secrets:access SECRET_NAME[@VERSION]

Um weitere Informationen zu diesen Vorgängen zu erhalten, übergeben Sie -h mit dem Befehl, um die CLI-Hilfe anzuzeigen.

Wie Geheimnisse abgerechnet werden

Secret Manager erlaubt 6 aktive Secret- Versionen kostenlos. Das bedeutet, dass Sie in einem Firebase-Projekt 6 Secrets pro Monat kostenlos haben können.

Standardmäßig versucht die Firebase-Befehlszeilenschnittstelle, ungenutzte Secret-Versionen gegebenenfalls automatisch zu löschen, z. B. wenn Sie Funktionen mit einer neuen Version des Secrets bereitstellen. Außerdem können Sie ungenutzte Geheimnisse mit functions:secrets:destroy und functions:secrets:prune aktiv bereinigen.

Secret Manager erlaubt 10.000 nicht abgerechnete monatliche Zugriffsvorgänge auf ein Geheimnis. Funktionsinstanzen lesen bei jedem Kaltstart nur die Geheimnisse, die in ihrem runWith Parameter angegeben sind. Wenn Sie viele Funktionsinstanzen haben, die viele Geheimnisse lesen, kann Ihr Projekt diesen Freibetrag überschreiten, woraufhin Ihnen 0,03 USD pro 10.000 Zugriffsvorgänge in Rechnung gestellt werden.

Weitere Informationen finden Sie unter Preise für Secret Manager .

Emulator-Unterstützung

Die Umgebungskonfiguration mit dotenv ist darauf ausgelegt, mit einem lokalen Cloud Functions-Emulator zusammenzuarbeiten.

Wenn Sie einen lokalen Cloud Functions-Emulator verwenden, können Sie Umgebungsvariablen für Ihr Projekt überschreiben, indem Sie eine .env.local -Datei einrichten. Inhalte von .env.local Vorrang vor .env und der projektspezifischen .env -Datei.

Ein Projekt könnte beispielsweise diese drei Dateien enthalten, die leicht unterschiedliche Werte für Entwicklung und lokale Tests enthalten:

.env .env.dev .env.local
PLANET=Erde

PUBLIKUM=Menschen

PUBLIKUM=Entwicklermenschen PUBLIKUM=Lokale Menschen

Beim Start im lokalen Kontext lädt der Emulator die Umgebungsvariablen wie gezeigt:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Geheimnisse und Anmeldedaten im Cloud Functions-Emulator

Der Cloud Functions-Emulator unterstützt die Verwendung von Geheimnissen zum Speichern und Zugreifen auf vertrauliche Konfigurationsinformationen . Standardmäßig versucht der Emulator, mit den Standardanmeldeinformationen der Anwendung auf Ihre Produktionsgeheimnisse zuzugreifen. In bestimmten Situationen wie CI-Umgebungen kann der Emulator aufgrund von Berechtigungsbeschränkungen möglicherweise nicht auf geheime Werte zugreifen.

Ähnlich wie bei der Cloud Functions-Emulatorunterstützung für Umgebungsvariablen können Sie geheime Werte überschreiben, indem Sie eine .secret.local -Datei einrichten. Dies macht es Ihnen leicht, Ihre Funktionen lokal zu testen, insbesondere wenn Sie keinen Zugriff auf den geheimen Wert haben.

Migrieren von der Umgebungskonfiguration

Wenn Sie die Umgebungskonfiguration mit functions.config haben, können Sie Ihre vorhandene Konfiguration als Umgebungsvariablen (im dotenv -Format) migrieren. Die Firebase-CLI stellt einen Exportbefehl bereit, der die Konfiguration jedes Alias ​​oder Projekts, das in der .firebaserc -Datei Ihres Verzeichnisses aufgeführt ist (im Beispiel unten local , dev und prod ), als .env Dateien ausgibt.

Exportieren Sie zur Migration Ihre vorhandenen Umgebungskonfigurationen mit dem Befehl firebase functions:config:export :

firebase functions:config:export
i  Importing configs from projects: [project-0, project-1]
⚠  The following configs keys could not be exported as environment variables:

⚠  project-0 (dev):
    1foo.a => 1FOO\_A (Key 1FOO\_A must start with an uppercase ASCII letter or underscore, and then consist of uppercase ASCII letters, digits, and underscores.)

Enter a PREFIX to rename invalid environment variable keys: CONFIG\_
✔  Wrote functions/.env.prod
✔  Wrote functions/.env.dev
✔  Wrote functions/.env.local
✔  Wrote functions/.env

Beachten Sie, dass Sie in einigen Fällen aufgefordert werden, ein Präfix einzugeben, um exportierte Umgebungsvariablenschlüssel umzubenennen. Dies liegt daran, dass nicht alle Konfigurationen automatisch transformiert werden können, da sie möglicherweise ungültig sind oder eine reservierte Umgebungsvariable key sind .

Wir empfehlen, dass Sie den Inhalt der generierten .env Dateien sorgfältig prüfen, bevor Sie Ihre Funktionen bereitstellen oder die .env Dateien in die Quellcodeverwaltung einchecken. Wenn Werte vertraulich sind und nicht durchsickern sollen, entfernen Sie sie aus Ihren .env Dateien und speichern Sie sie stattdessen sicher in Secret Manager .

Sie müssen auch Ihren Funktionscode aktualisieren. Alle Funktionen, die functions.config verwenden, müssen jetzt stattdessen process.env verwenden, wie in Umgebungsvariablen gezeigt.

Umgebungskonfiguration

Bevor die Unterstützung von Umgebungsvariablen in firebase-functions v3.18.0 veröffentlicht wurde, war die Verwendung von functions.config() der empfohlene Ansatz für die Umgebungskonfiguration. Dieser Ansatz wird weiterhin unterstützt, aber wir empfehlen allen neuen Projekten, stattdessen Umgebungsvariablen zu verwenden, da sie einfacher zu verwenden sind und die Portabilität Ihres Codes verbessern.

Legen Sie die Umgebungskonfiguration mit der CLI fest

Um Umgebungsdaten zu speichern, können Sie den Befehl firebase functions:config:set in der Firebase-CLI verwenden. Jeder Schlüssel kann mit Punkten benannt werden, um zusammengehörige Konfigurationen zu gruppieren. Beachten Sie, dass in Schlüsseln nur Kleinbuchstaben akzeptiert werden ; Großbuchstaben sind nicht erlaubt.

Um beispielsweise die Client-ID und den API-Schlüssel für "Some Service" zu speichern, könnten Sie Folgendes ausführen:

firebase functions:config:set someservice.key="THE API KEY" someservice.id="THE CLIENT ID"

Rufen Sie die aktuelle Umgebungskonfiguration ab

Um zu überprüfen, was derzeit in der Umgebungskonfiguration für Ihr Projekt gespeichert ist, können Sie firebase functions:config:get verwenden. Es wird JSON in etwa so ausgegeben:

{
  "someservice": {
    "key":"THE API KEY",
    "id":"THE CLIENT ID"
  }
}

Diese Funktionalität basiert auf der Google Cloud Runtime Configuration API .

Verwenden Sie functions.config , um auf die Umgebungskonfiguration in einer Funktion zuzugreifen

Einige Konfigurationen werden automatisch unter dem reservierten firebase -Namespace bereitgestellt. Die Umgebungskonfiguration wird innerhalb Ihrer laufenden Funktion über functions.config() verfügbar gemacht. Um die obige Konfiguration zu verwenden, könnte Ihr Code so aussehen:

const functions = require('firebase-functions');
const request = require('request-promise');

exports.userCreated = functions.database.ref('/users/{id}').onWrite(event => {
  let email = event.data.child('email').val();

  return request({
    url: 'https://someservice.com/api/some/call',
    headers: {
      'X-Client-ID': functions.config().someservice.id,
      'Authorization': `Bearer ${functions.config().someservice.key}`
    },
    body: {email: email}
  });
});

Verwenden Sie die Umgebungskonfiguration, um ein Modul zu initialisieren

Einige Node-Module sind ohne Konfiguration bereit. Andere Module benötigen eine zusätzliche Konfiguration, um korrekt initialisiert zu werden. Wir empfehlen, diese Konfiguration in Umgebungskonfigurationsvariablen zu speichern, anstatt sie fest zu codieren. Dies hilft Ihnen, Ihren Code viel portabler zu halten, wodurch Sie Ihre Anwendung als Open Source öffnen oder einfach zwischen Produktions- und Staging-Versionen wechseln können.

Um beispielsweise das Slack Node SDK -Modul zu verwenden, könnten Sie Folgendes schreiben:

const functions = require('firebase-functions');
const IncomingWebhook = require('@slack/client').IncomingWebhook;
const webhook = new IncomingWebhook(functions.config().slack.url);

Legen Sie vor der Bereitstellung die Umgebungskonfigurationsvariable slack.url :

firebase functions:config:set slack.url=https://hooks.slack.com/services/XXX

Zusätzliche Umgebungsbefehle

  • firebase functions:config:unset key1 key2 entfernt die angegebenen Schlüssel aus der config
  • firebase functions:config:clone --from <fromProject> die Umgebung eines anderen Projekts in das derzeit aktive Projekt.

Automatisch gefüllte Umgebungsvariablen

Es gibt Umgebungsvariablen, die automatisch in der Funktionslaufzeit und in lokal emulierten Funktionen ausgefüllt werden. Dazu gehören diejenigen, die von Google Cloud ausgefüllt werden, sowie eine Firebase-spezifische Umgebungsvariable:

process.env.FIREBASE_CONFIG : Stellt die folgenden Firebase-Projektkonfigurationsinformationen bereit:

{
  databaseURL: 'https://databaseName.firebaseio.com',
  storageBucket: 'projectId.appspot.com',
  projectId: 'projectId'
}

Diese Konfiguration wird automatisch angewendet, wenn Sie das Firebase Admin SDK ohne Argumente initialisieren. Wenn Sie Funktionen in JavaScript schreiben, initialisieren Sie wie folgt:

const admin = require('firebase-admin');
admin.initializeApp();

Wenn Sie Funktionen in TypeScript schreiben, initialisieren Sie wie folgt:

import * as functions from 'firebase-functions';
import * as admin from 'firebase-admin';
import 'firebase-functions';
admin.initializeApp();

Wenn Sie das Admin SDK mit der Standardprojektkonfiguration unter Verwendung der Dienstkonto-Anmeldeinformationen initialisieren müssen, können Sie die Anmeldeinformationen aus einer Datei laden und sie wie folgt 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);