Configurer votre environnement


Souvent, vous aurez besoin d'une configuration supplémentaire pour vos fonctions, comme des clés API tierces ou des paramètres ajustables. Le SDK Firebase pour Cloud Functions propose une configuration d'environnement intégrée pour faciliter le stockage et la récupération type de données pour votre projet.

Vous avez le choix entre les options suivantes :

  • Configuration paramétrée (recommandée pour la plupart des scénarios) Cela fournit une configuration d'environnement fortement typée avec des paramètres validés au moment du déploiement, ce qui évite les erreurs et simplifie le débogage.
  • Configuration basée sur les fichiers des variables d'environnement. Avec cette approche, vous créez manuellement un fichier dotenv pour charger les variables d'environnement.

Dans la plupart des cas d'utilisation, il est recommandé d'utiliser une configuration paramétrée. Cette approche rend les valeurs de configuration disponibles à la fois au moment de l'exécution et du déploiement. Le déploiement est bloqué, sauf si tous les paramètres ont une valeur valide. Inversement, la configuration avec des variables d'environnement n'est pas disponible au moment du déploiement en temps réel.

Configuration paramétrée

Cloud Functions for Firebase fournit une interface permettant de définir la configuration de manière déclarative dans votre codebase. La valeur de ces paramètres est disponibles aussi bien pendant le déploiement de la fonction que lors de la définition et pendant l'exécution. Cela signifie que la CLI bloque le déploiement sauf si tous les paramètres ont une valeur valide.

Pour définir des paramètres dans votre code, suivez ce modèle :

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.`);
  }
);

Lorsque vous déployez une fonction avec des variables de configuration paramétrées, la CLI Firebase tente d'abord de charger leurs valeurs à partir de fichiers .env locaux. Si elles ne sont pas présentes dans ces fichiers et qu'aucun default n'est défini, la CLI demande les valeurs lors du déploiement, puis les enregistre automatiquement dans un fichier .env nommé .env.<project_ID> dans votre répertoire functions/ :

$ 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

Selon votre workflow de développement, il peut être utile d'ajouter le fichier .env.<project_ID> généré au contrôle des versions.

Utiliser des paramètres dans un champ d'application global

Lors du déploiement, le code de vos fonctions est chargé et inspecté avant que vos paramètres n'aient des valeurs réelles. Cela signifie que l'extraction des valeurs de paramètre au niveau de la portée globale entraîne un échec de déploiement. Si vous souhaitez utiliser un paramètre pour initialiser une valeur globale, utilisez le rappel d'initialisation onInit(). Ce rappel s'exécute avant toute exécution de toute fonction en production, mais il est lors du déploiement. Il s'agit donc d'un emplacement sûr pour accéder à l'objet .

  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());
  })

Configurer le comportement de la CLI

Les paramètres peuvent être configurés avec un objet Options qui contrôle la façon dont la CLI vous invitera à saisir des valeurs. L'exemple suivant définit des options pour valider le format d'un numéro de téléphone, fournir une option de sélection simple et renseigner automatiquement une option de sélection à partir du projet Firebase :

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"})

Types de paramètre

La configuration paramétrée fournit un typage strict pour les valeurs de paramètre et est également compatible avec les secrets de Cloud Secret Manager. Les types compatibles sont les suivants :

  • Secret
  • Chaîne
  • Booléen
  • Integer
  • Float

Valeurs et expressions de paramètre

Firebase évalue vos paramètres au moment du déploiement et pendant l'exécution de votre fonction. En raison de ces deux environnements, vous devez prendre des précautions particulières comparer les valeurs de paramètres et, si vous les utilisez pour définir des options d'exécution pour votre fonctions.

Pour transmettre un paramètre à votre fonction en tant qu'option d'exécution, transmettez-le directement :

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) => {
    //…

De plus, si vous devez effectuer une comparaison par rapport à un paramètre vous devez utiliser des comparateurs intégrés au lieu en vérifiant la valeur:

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) => {
    //…

Les paramètres et les expressions de paramètres qui ne sont utilisés qu'au moment de l'exécution peuvent être accessibles via leur fonction value :

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.`);
  }
);

Paramètres intégrés

Le SDK Cloud Functions propose trois paramètres prédéfinis, disponibles Sous-package firebase-functions/params:

  • projectID : projet Cloud dans lequel la fonction est exécutée.
  • databaseURL : URL de l'instance Realtime Database associée à la fonction (si elle est activée dans le projet Firebase).
  • storageBucket : bucket Cloud Storage associé à la fonction (s'il est activé dans le projet Firebase).

Ils fonctionnent comme des paramètres de chaîne définis par l'utilisateur à tous égards, sauf que, comme leurs valeurs sont toujours connues de la CLI Firebase, elles ne seront jamais demandées lors du déploiement ni enregistrées dans des fichiers .env.

Paramètres secrets

Les paramètres de type Secret, définis à l'aide de defineSecret(), représentent une chaîne dont la valeur est stockée dans Cloud Secret Manager. Au lieu de en effectuant une vérification par rapport à un fichier .env local et en écrivant une nouvelle valeur dans le fichier si manquants, les paramètres de secret sont vérifiés pour s'assurer qu'ils existent dans Cloud Secret Manager ; et invite de manière interactive la valeur d'un nouveau secret pendant le déploiement.

Les paramètres secrets définis de cette manière doivent être liés aux fonctions individuelles qui doivent y accéder :

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();
    //…

Comme les valeurs des secrets sont masquées jusqu'à l'exécution de la fonction, vous ne pouvez pas les utiliser lors de la configuration de votre fonction.

Variables d'environnement

Cloud Functions for Firebase est compatible avec le format de fichier dotenv pour charger les variables d'environnement spécifiées dans un fichier .env dans l'environnement d'exécution de votre application. Une fois déployées, les variables d'environnement peuvent être lues process.env de commande.

Pour configurer votre environnement de cette manière, créez un fichier .env dans votre projet : Ajoutez les variables souhaitées et déployez:

  1. Créez un fichier .env dans votre répertoire functions/:

    # Directory layout:
#   my-project/
#     firebase.json
#     functions/
#       .env
#       package.json
#       index.js

  2. Ouvrez le fichier .env pour le modifier, puis ajoutez les clés souhaitées. Exemple :

    PLANET=Earth
AUDIENCE=Humans

  3. Déployez des fonctions et vérifiez que les variables d'environnement ont bien été chargées:

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

Une fois vos variables d'environnement personnalisées déployées, votre code de fonction peut y accéder process.env syntaxe:

// Responds with "Hello Earth and Humans"
exports.hello = functions.https.onRequest((request, response) => {
  response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});

Déployer plusieurs ensembles de variables d'environnement

Si vous avez besoin d'un autre ensemble de variables d'environnement pour vos projets Firebase (par exemple, en préproduction ou en production), créez un fichier .env.<project or alias> et y écrivez vos variables d'environnement spécifiques au projet. Les variables d'environnement .env et les fichiers .env spécifiques au projet (le cas échéant) seront inclus dans toutes les fonctions déployées.

Par exemple, un projet peut inclure ces trois fichiers contenant des valeurs légèrement différentes pour le développement et la production :

.env .env.dev .env.prod
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Prod Humans

Compte tenu des valeurs de ces fichiers distincts, l'ensemble des variables d'environnement déployées avec vos fonctions varie en fonction de votre projet cible :

$ 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

Variables d'environnement réservées

Certaines clés de variable d'environnement sont réservées à un usage interne. N'utilisez aucune de ces clés dans vos fichiers .env :

  • Toutes les clés commençant par X_GOOGLE_
  • Toutes les clés à partir de EXT_
  • Toutes les clés commençant par FIREBASE_
  • N'importe quelle clé de la liste suivante:
  • CLOUD_RUNTIME_CONFIG
  • ENTRY_POINT
  • GCP_PROJECT
  • PROJET_GCLOUD
  • PROJET_GOOGLE_CLOUD
  • FUNCTION_TRIGGER_TYPE (TYPE DE DÉCLENCHEUR DE FONCTIONNALITÉ)
  • NOM_FONCTIONNALITÉ
  • FUNCTION_MEMORY_MB
  • FUNCTION_TIMEOUT_SEC
  • IDENTITÉ_FONCTIONNALITÉ
  • FUNCTION_REGION
  • FONCTION_TARGET
  • FUNCTION_SIGNATURE_TYPE
  • K_SERVICE
  • REVISION
  • PORT
  • K_CONFIGURATION

Stocker et accéder à des informations de configuration sensibles

Les variables d'environnement stockées dans des fichiers .env peuvent être utilisées pour la configuration des fonctions, mais vous ne devez pas les considérer comme un moyen sécurisé de stocker des informations sensibles telles que des identifiants de base de données ou des clés API. Ceci est particulièrement important si vous archivez vos fichiers .env dans un système de contrôle de code source.

Pour vous aider à stocker des informations de configuration sensibles, Cloud Functions for Firebase s'intègre à Google Cloud Secret Manager. Ce service chiffré stocke les valeurs de configuration de manière sécurisée, tout en permettant un accès facile à partir de vos fonctions si nécessaire.

Créer et utiliser un secret

Pour créer un secret, utilisez la CLI Firebase.

Pour créer et utiliser un secret :

  1. À partir de la racine du répertoire local de votre projet, exécutez la commande suivante: 

    firebase functions:secrets:set SECRET_NAME

  2. Saisissez une valeur pour SECRET_NAME.

    La CLI renvoie un message de réussite et vous avertit que vous devez déployer des fonctions pour que la modification soit prise en compte.

  3. Avant le déploiement, assurez-vous que le code de votre fonction lui permet d'accéder au secret à l'aide du paramètre 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. Déployez Cloud Functions:

    firebase deploy --only functions

Vous pouvez maintenant y accéder comme n'importe quelle autre variable d'environnement. À l'inverse, si une autre fonction qui ne spécifie pas le secret dans runWith tente d'y accéder, elle reçoit une valeur non définie :

  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
  });

Une fois votre fonction déployée, elle aura accès à la valeur du secret. Seulement les fonctions qui incluent spécifiquement un secret dans leur paramètre runWith vous n'aurez pas accès à ce secret en tant que variable d'environnement. Cela vous permet de vous assurer que les valeurs secrètes ne sont disponibles que là où elles sont nécessaires, ce qui réduit le risque de fuite accidentelle d'un secret.

Gérer les secrets

Utilisez la CLI Firebase pour gérer vos secrets. Tout en gérant les secrets de cette façon, Gardez à l'esprit que certaines modifications de la CLI nécessitent une modification et/ou un redéploiement des fonctions associées. Plus précisément :

  • Chaque fois que vous définissez une nouvelle valeur pour un secret, vous devez redéployer toutes des fonctions qui font référence ce secret pour qu'ils récupèrent la dernière valeur.
  • Si vous supprimez un secret, assurez-vous qu'aucune de vos fonctions déployées qui fait référence à ce secret. Les fonctions qui utilisent une valeur secrète supprimée échouent de manière silencieuse.

Voici un résumé des commandes CLI Firebase pour la gestion des secrets:

# 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

Pour les commandes access et destroy, vous pouvez fournir la version facultative pour gérer une version particulière. Exemple :

functions:secrets:access SECRET_NAME[@VERSION]

Pour en savoir plus sur ces opérations, transmettez -h avec la commande à consultez l'aide de la CLI.

Facturation des secrets

Secret Manager autorise six secrets actifs versions sans frais. Cela signifie que vous pouvez avoir 6 secrets par mois dans un projet sans frais.

Par défaut, la CLI Firebase tente de détruire automatiquement les versions de secret inutilisées, le cas échéant, par exemple lorsque vous déployez des fonctions avec une nouvelle version du secret. Vous pouvez également nettoyer activement les secrets inutilisés à l'aide de functions:secrets:destroy et functions:secrets:prune.

Secret Manager autorise 10 000 opérations d'accès mensuelles non facturées sur un secret. Les instances de fonction ne lisent que les secrets spécifiés dans leur paramètre runWith à chaque démarrage à froid. Si vous avez de nombreuses instances de fonction lisant de nombreux secrets, votre projet peut dépasser cette allocation. Dans ce cas, vous serez facturé 0,03 $ pour 10 000 opérations d'accès.

Pour en savoir plus, consultez Tarifs Secret Manager.

Prise en charge des émulateurs

La configuration de l'environnement avec dotenv est conçue pour interagir avec un émulateur Cloud Functions local.

Lorsque vous utilisez un émulateur Cloud Functions local, vous pouvez remplacer les variables d'environnement de votre projet en configurant un fichier .env.local. Contenu de .env.local sont prioritaires sur .env et sur le fichier .env spécifique au projet.

Par exemple, un projet peut inclure ces trois fichiers contenant des valeurs légèrement différentes pour le développement et les tests locaux :

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Ingénieurs en développement AUDIENCE=Local Humans

Lorsqu'il est démarré en contexte local, l'émulateur charge l'environnement comme indiqué ci-dessous:

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

Secrets et identifiants dans l'émulateur Cloud Functions

L'émulateur Cloud Functions prend en charge l'utilisation de secrets pour stocker des informations de configuration sensibles et y accéder. Par défaut, l'émulateur tente d'accéder à vos secrets de production à l'aide de identifiants par défaut de l'application. Dans certains cas, comme les environnements de CI, l'émulateur peut ne pas réussir à accéder aux valeurs secrètes en raison de restrictions d'autorisation.

Comme pour la prise en charge des variables d'environnement par l'émulateur Cloud Functions, vous pouvez remplacer les valeurs des secrets en configurant un fichier .secret.local. Vous pouvez ainsi tester facilement vos fonctions localement, en particulier si vous n'avez pas accès à la valeur secrète.

Migrer depuis la configuration de l'environnement

Si vous avez utilisé la configuration d'environnement avec functions.config, vous pouvez migrer votre configuration existante en tant que variables d'environnement (au format dotenv). La CLI Firebase fournit une commande d'exportation qui génère la configuration de chaque alias ou projet listé dans le fichier .firebaserc de votre répertoire (dans l'exemple ci-dessous, local, dev et prod) sous forme de fichiers .env.

Pour migrer, exportez vos configurations d'environnement existantes à l'aide de la commande 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

Notez que, dans certains cas, vous serez invité à saisir un préfixe pour renommer les clés de variable d'environnement exportées. En effet, toutes les configurations ne peuvent pas être transformées automatiquement, car elles peuvent être non valides ou s'agir d'une clé de variable d'environnement réservée.

Nous vous recommandons de vérifier attentivement le contenu des fichiers .env générés avant de déployer vos fonctions ou de vérifier les fichiers .env dans le contrôle des sources. Si certaines valeurs sont sensibles et ne doivent pas être divulguées, supprimez-les de vos fichiers .env et stockez-les de manière sécurisée dans Secret Manager à la place.

Vous devez également mettre à jour le code de vos fonctions. Toutes les fonctions qui utilisent functions.config doit désormais utiliser process.env à la place, comme indiqué dans Passez à la 2e génération.

Configuration de l'environnement

Définir la configuration de l'environnement avec la CLI

Pour stocker des données d'environnement, vous pouvez utiliser la commande firebase functions:config:set dans la CLI Firebase. Chaque clé peut être associée à un espace de noms à l'aide de points pour regrouper les configurations associées. N'oubliez pas que seuls les caractères minuscules sont acceptés dans les clés. Les caractères majuscules ne sont pas autorisés.

Par exemple, pour stocker l'ID client et la clé API de "Un service", vous pouvez exécuter :

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

Récupérer la configuration actuelle de l'environnement

Pour inspecter ce qui est actuellement stocké dans la configuration de l'environnement de votre projet, vous pouvez utiliser firebase functions:config:get. La sortie JSON ressemblera à ceci :

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

Cette fonctionnalité repose sur l'API Runtime Configuration Google Cloud.

Utiliser functions.config pour accéder à la configuration de l'environnement dans une fonction

Certaines configurations sont automatiquement fournies dans l'espace de noms firebase réservé. La configuration de l'environnement est disponible dans votre environnement via functions.config(). Pour utiliser la configuration ci-dessus, votre code peut se présenter comme suit :

const functions = require('firebase-functions/v1');
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}
  });
});

Utiliser la configuration de l'environnement pour initialiser un module

Certains modules Node sont prêts sans configuration. D'autres modules nécessitent une configuration supplémentaire pour s'initialiser correctement. Nous vous recommandons de stocker cette configuration dans des variables de configuration d'environnement plutôt que de la coder en dur. Cela vous aide votre code est beaucoup plus portable, ce qui vous permet d'Open Source application, ou basculer facilement entre les versions de production et de préproduction.

Par exemple, pour utiliser le module du SDK Slack Node, vous pouvez écrire ce qui suit :

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

Avant le déploiement, définissez la variable de configuration d'environnement slack.url:

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

Commandes d'environnement supplémentaires

  • firebase functions:config:unset key1 key2 supprime les clés spécifiées de la configuration.
  • firebase functions:config:clone --from <fromProject> clone l'environnement d'un autre projet dans le projet actuellement actif.

Variables d'environnement renseignées automatiquement

Des variables d'environnement sont automatiquement renseignées dans l'environnement d'exécution des fonctions et dans les fonctions émulées localement. Il s'agit notamment de celles renseignées par Google Cloud, ainsi que d'une variable d'environnement spécifique à Firebase :

process.env.FIREBASE_CONFIG: fournit les informations suivantes sur la configuration du projet Firebase:

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

Cette configuration est appliquée automatiquement lorsque vous initialisez le SDK Admin Firebase sans arguments. Si vous écrivez des fonctions en JavaScript, procédez comme suit :

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

Si vous écrivez des fonctions en TypeScript, initialisez comme suit:

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

Si vous devez initialiser le SDK Admin avec la configuration de projet par défaut à l'aide des identifiants du compte de service, vous pouvez les charger ajoutez-les à FIREBASE_CONFIG comme ceci:

serviceAccount = require('./serviceAccount.json');

const adminConfig = JSON.parse(process.env.FIREBASE_CONFIG);
adminConfig.credential = admin.credential.cert(serviceAccount);
admin.initializeApp(adminConfig);