Configurer votre environnement

Vous aurez souvent besoin d'une configuration supplémentaire pour vos fonctions, comme des clés API tierces ou des paramètres réglables. Le SDK Firebase pour Cloud Functions offre une configuration d'environnement intégrée pour faciliter le stockage et la récupération de ce 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 des variables d'environnement basée sur des fichiers. Avec cette approche, vous créez manuellement un fichier dotenv pour charger les variables d'environnement.

Pour la plupart des cas d'utilisation, nous vous recommandons d'utiliser une configuration paramétrée. Cette approche permet de rendre 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. À l'inverse, la configuration avec des variables d'environnement n'est pas disponible au moment du déploiement.

Configuration paramétrée

Cloud Functions for Firebase fournit une interface permettant de définir des paramètres de configuration de manière déclarative dans votre code. La valeur de ces paramètres est disponible à la fois lors du déploiement de la fonction, lorsque vous définissez les options de déploiement et d'exécution, et lors de l'exécution. Cela signifie que la CLI bloquera le déploiement, sauf si tous les paramètres ont une valeur valide.

const { onRequest } = require('firebase-functions/v2/https');
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 = onRequest(
  { minInstances: minInstancesConfig },
(req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

from firebase_functions import https_fn
from firebase_functions.params import IntParam, StringParam

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")
WELCOME_MESSAGE = StringParam("WELCOME_MESSAGE")

# To use configured parameters inside the config for a function, provide them
# directly. To use them at runtime, call .value() on them.
@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    return https_fn.Response(f'{WELCOME_MESSAGE.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 des fichiers .env locaux. S'ils ne sont pas présents dans ces fichiers et qu'aucun default n'est défini, la CLI vous demandera les valeurs lors du déploiement, puis les enregistrera 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

En fonction de 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 le champ d'application global

Lors du déploiement, le code de vos fonctions est chargé et inspecté avant que vos paramètres aient des valeurs réelles. Cela signifie que la récupération des valeurs de paramètres dans le champ d'application global entraîne un échec du déploiement. Dans les cas où vous souhaitez utiliser un paramètre pour initialiser une valeur globale, utilisez le rappel d'initialisation onInit(). Ce rappel s'exécute avant toute fonction en production, mais n'est pas appelé lors du déploiement. Il s'agit donc d'un endroit sûr pour accéder à la valeur d'un paramètre.

const { GoogleGenerativeAI } = require('@google/generative-ai');
const { defineSecret } = require('firebase-functions/params');
const { onInit } = require('firebase-functions/v2/core');

const apiKey = defineSecret('GOOGLE_API_KEY');

let genAI;
onInit(() => {
  genAI = new GoogleGenerativeAI(apiKey.value());
})

from firebase_functions.core import init
from firebase_functions.params import StringParam, PROJECT_ID
import firebase_admin
import vertexai

location = StringParam("LOCATION")

x = "hello"

@init
def initialize():
  # Note: to write back to a global, you'll need to use the "global" keyword
  # to avoid creating a new local with the same name.
  global x
  x = "world"
  firebase_admin.initialize_app()
  vertexai.init(PROJECT_ID.value, location.value)

Si vous utilisez des paramètres de type Secret, notez qu'ils ne sont disponibles que dans le processus des fonctions qui ont lié le secret. Si un secret n'est lié que dans certaines fonctions, vérifiez si secret.value() est faux avant de l'utiliser.

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 demandera des valeurs. L'exemple suivant définit des options permettant de valider le format d'un numéro de téléphone, de fournir une option de sélection simple et de remplir 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: params.select(["odd", "even"])});

const memory = defineInt("MEMORY", {
  description: "How much memory do you need?",
  input: params.select({ "micro": 256, "chonky": 2048 }),
});

const extensions = defineList("EXTENSIONS", {
  description: "Which file types should be processed?",
  input: params.multiSelect(["jpg", "tiff", "png", "webp"]),
});

const storageBucket = defineString('BUCKET', {
  description: "This will automatically
populate the selector field with the deploying Cloud Project’s
storage buckets",
  input: params.PICK_STORAGE_BUCKET,
});

from firebase_functions.params import (
    StringParam,
    ListParam,
    TextInput,
    SelectInput,
    SelectOptions,
    ResourceInput,
    ResourceType,
)

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")

WELCOME_MESSAGE = StringParam(
    "WELCOME_MESSAGE",
    default="Hello World",
    description="The greeting that is returned to the caller of this function",
)

ONLY_PHONE_NUMBERS = StringParam(
    "PHONE_NUMBER",
    input=TextInput(
        validation_regex="\d{3}-\d{3}-\d{4}",
        validation_error_message="Please enter a phone number in the format XXX-YYY-XXX",
    ),
)

SELECT_OPTION = StringParam(
    "PARITY",
    input=SelectInput([SelectOptions(value="odd"), SelectOptions(value="even")]),
)

STORAGE_BUCKET = StringParam(
    "BUCKET",
    input=ResourceInput(type=ResourceType.STORAGE_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 fort pour les valeurs de paramètres et est également compatible avec les secrets de Cloud Secret Manager. Voici les types acceptés :

• Secret
• Chaîne
• Booléen
• Integer
• Float
• Liste (Node.js)

Valeurs et expressions de paramètres

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 être particulièrement vigilant lorsque vous comparez des valeurs de paramètres et lorsque vous les utilisez pour définir des options d'exécution pour vos fonctions.

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

const { onRequest } = require('firebase-functions/v2/https');
const { defineInt } = require('firebase-functions/params');
const minInstancesConfig = defineInt('HELLO\_WORLD\_MININSTANCES');

export const helloWorld = onRequest(
  { minInstances: minInstancesConfig },
  (req, res) => {
    //…

from firebase_functions import https_fn
from firebase_functions.params import IntParam

MIN_INSTANCES = IntParam("HELLO_WORLD_MIN_INSTANCES")

@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    ...

De plus, si vous devez effectuer une comparaison avec un paramètre pour savoir quelle option choisir, vous devrez utiliser des comparateurs intégrés au lieu de vérifier la valeur :

const { onRequest } = require('firebase-functions/v2/https');
const environment = params.defineString(‘ENVIRONMENT’, {default: 'dev'});

// use built-in comparators
const minInstancesConfig = environment.equals('PRODUCTION').thenElse(10, 1);
export const helloWorld = onRequest(
  { minInstances: minInstancesConfig },
  (req, res) => {
    //…

from firebase_functions import https_fn
from firebase_functions.params import IntParam, StringParam

ENVIRONMENT = StringParam("ENVIRONMENT", default="dev")
MIN_INSTANCES = ENVIRONMENT.equals("PRODUCTION").then(10, 0)

@https_fn.on_request(min_instances=MIN_INSTANCES)
def hello_world(req):
    ...

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

const { onRequest } = require('firebase-functions/v2/https');
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 = onRequest(
(req, res) => {
    res.send(`${welcomeMessage.value()}! I am a function.`);
  }
);

from firebase_functions import https_fn
from firebase_functions.params import StringParam

WELCOME_MESSAGE = StringParam("WELCOME_MESSAGE")

@https_fn.on_request()
def hello_world(req):
    return https_fn.Response(f'{WELCOME_MESSAGE.value()}! I am a function!')

Paramètres intégrés

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

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

Paramètres secrets

Les paramètres de type Secret, définis à l'aide de defineSecret(), représentent des paramètres de chaîne dont la valeur est stockée dans Cloud Secret Manager. Au lieu de vérifier l'existence d'un fichier .env local et d'écrire une nouvelle valeur dans le fichier si elle est manquante, les paramètres secrets vérifient l'existence d'un secret dans Cloud Secret Manager et demandent de manière interactive la valeur d'un nouveau secret lors du déploiement.

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

const { onRequest } = require('firebase-functions/v2/https');
const { defineSecret } = require('firebase-functions/params');
const discordApiKey = defineSecret('DISCORD_API_KEY');

export const postToDiscord = onRequest(
  { secrets: [discordApiKey] },
  (req, res) => {
  const apiKey = discordApiKey.value();
    //…

from firebase_functions import https_fn
from firebase_functions.params import SecretParam

DISCORD_API_KEY = SecretParam('DISCORD_API_KEY')

@https_fn.on_request(secrets=[DISCORD_API_KEY])
def post_to_discord(req):
    api_key = DISCORD_API_KEY.value

Étant donné que 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 via l'interface process.env (dans les projets basés sur Node.js) ou os.environ (dans les projets basés sur Python).

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 et ajoutez les clés souhaitées. Exemple :

   PLANET=Earth
   AUDIENCE=Humans
   

3. Déployez les fonctions et vérifiez que les variables d'environnement ont é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, le code de votre fonction peut y accéder :

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

import os

@https_fn.on_request()
def hello(req):
    return https_fn.Response(
        f"Hello {os.environ.get('PLANET')} and {os.environ.get('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, pour la mise en scène par rapport à la production), créez un fichier .env.<project or alias> et écrivez-y vos variables d'environnement spécifiques à votre projet. Les variables d'environnement des fichiers .env et .env spécifiques au projet (le cas échéant) seront incluses 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 :

Étant donné les valeurs de ces fichiers distincts, l'ensemble des variables d'environnement déployées avec vos fonctions variera 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 variables d'environnement sont réservées à une utilisation 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 commençant par EXT_
• Toutes les clés commençant par FIREBASE_
• N'importe quelle touche de la liste suivante :
• 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

Stocker et accéder aux informations de configuration sensibles

Les variables d'environnement stockées dans les 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 les identifiants de bases de données ou les clés API. Cela est particulièrement important si vous archivez vos fichiers .env dans le 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 à 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 de votre projet local, exécutez la commande suivante :

   firebase functions:secrets:set SECRET_NAME

2. Saisissez une valeur pour SECRET_NAME.

   La CLI affiche un message de réussite et vous avertit que vous devez déployer les fonctions pour que la modification prenne effet.

3. Avant de déployer votre fonction, assurez-vous que son code lui permet d'accéder au secret à l'aide du paramètre runWith :

   Node.js

   const { onRequest } = require('firebase-functions/v2/https');
   
   exports.processPayment = onRequest(
     { secrets: ["SECRET_NAME"] },
     (req, res) => {
       const myBillingService = initializeBillingService(
         // reference the secret value
         process.env.SECRET_NAME
       );
       // Process the payment
     }
   );

   Python

   import os
   from firebase_functions import https_fn
   
   @https_fn.on_request(secrets=["SECRET_NAME"])
   def process_payment(req):
       myBillingService = initialize_billing(key=os.environ.get('SECRET_NAME'))
       # Process the payment
       ...
   

4. Déployer Cloud Functions :

   firebase deploy --only functions

   Vous pourrez désormais 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 indéfinie :

   Node.js

   exports.anotherEndpoint = 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
   });
   

   Python

   @https_fn.on_request()
   def another_endpoint(req):
       return https_fn.Response(f"The secret API key is {os.environ.get("SECRET_NAME")}")
       # Responds with "The secret API key is None" because the `secrets` parameter is missing.
   

Une fois votre fonction déployée, elle aura accès à la valeur du secret. Seules les fonctions qui incluent spécifiquement un secret dans leur paramètre runWith auront 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. Lorsque vous gérez des secrets de cette manière, n'oubliez pas que certaines modifications de la CLI nécessitent de modifier et/ou de redéployer les fonctions associées. Plus précisément :

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

Voici un récapitulatif des commandes de la 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 le paramètre de version facultatif pour gérer une version spécifique. Exemple :

functions:secrets:access SECRET_NAME[@VERSION]

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

Facturation des secrets

Secret Manager permet d'avoir six versions de secrets actives sans frais. Cela signifie que vous pouvez avoir six secrets par mois dans un projet Firebase sans frais.

Par défaut, la CLI Firebase tente de détruire automatiquement les versions de secrets inutilisées, le cas échéant, par exemple lorsque vous déployez des fonctions avec une nouvelle version du secret. Vous pouvez également supprimer 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 de nombreuses instances de fonction lisent de nombreux secrets, votre projet peut dépasser ce quota.Dans ce cas, 0,03 $vous seront facturés pour 10 000 opérations d'accès.

Pour en savoir plus, consultez la page Tarifs Secret Manager.

Prise en charge des émulateurs

La configuration de l'environnement avec dotenv est conçue pour fonctionner 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. Le contenu de .env.local est prioritaire 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 :

Lorsqu'il est démarré dans le contexte local, l'émulateur charge les variables d'environnement comme indiqué :

  $ 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 permet d'utiliser des secrets pour stocker des informations de configuration sensibles et y accéder. Par défaut, l'émulateur tentera d'accéder à vos secrets de production à l'aide des identifiants par défaut de l'application. Dans certaines situations, comme les environnements d'intégration continue, l'émulateur peut ne pas pouvoir 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. Cela vous permet de tester facilement vos fonctions localement, en particulier si vous n'avez pas accès à la valeur du secret.

Migrer depuis la configuration de l'environnement

Si vous avez utilisé la configuration de l'environnement avec functions.config, vous devez migrer votre configuration existante en tant que variables d'environnement (au format dotenv) avant la fin de l'année 2025, date à laquelle functions.config sera abandonné. Après décembre 2025, les nouveaux déploiements avec functions.config échoueront.

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 la configuration de votre environnement existant à 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 variables d'environnement exportées. En effet, toutes les configurations ne peuvent pas être transformées automatiquement, car elles peuvent être non valides ou être une clé de variable d'environnement réservée.

Nous vous recommandons d'examiner attentivement le contenu des fichiers .env générés avant de déployer vos fonctions ou d'archiver les fichiers .env dans le contrôle de code source. Si des 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.

Vous devrez également mettre à jour le code de vos fonctions. Toutes les fonctions qui utilisent functions.config devront désormais utiliser process.env, comme indiqué dans Variables d'environnement.