Configura il tuo ambiente

Spesso è necessaria una configurazione aggiuntiva per le funzioni, ad esempio chiavi API di terze parti o impostazioni regolabili. L'SDK Firebase per Cloud Functions offre una configurazione dell'ambiente integrata per archiviare e recuperare facilmente questo tipo di dati per il tuo progetto.

Puoi scegliere tra le seguenti opzioni:

• Configurazione con parametri (consigliata per la maggior parte degli scenari). In questo modo viene fornita una configurazione dell'ambiente fortemente tipizzata con parametri convalidati al momento del deployment, il che impedisce errori e semplifica il debug.
• Configurazione basata su file delle variabili di ambiente. Con questo approccio, crei manualmente un file dotenv per il caricamento delle variabili di ambiente.

Per la maggior parte dei casi d'uso, è consigliata la configurazione con parametri. Questo approccio rende disponibili i valori di configurazione sia in fase di runtime che di deployment e quest'ultimo viene bloccato a meno che tutti i parametri non abbiano un valore valido. Al contrario, la configurazione con variabili di ambiente non è disponibile al momento del deployment.

Configurazione con parametri

Cloud Functions for Firebase fornisce un'interfaccia per definire i parametri di configurazione in modo dichiarativo all'interno della base di codice. Il valore di questi parametri è disponibile sia durante il deployment della funzione, quando vengono impostate le opzioni di deployment e di runtime, sia durante l'esecuzione. Ciò significa che la CLI bloccherà il deployment a meno che tutti i parametri non abbiano un valore valido.

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!')

Quando esegui il deployment di una funzione con variabili di configurazione parametrizzate, l'interfaccia a riga di comando di Firebase tenta innanzitutto di caricarne i valori dai file .env locali. Se non sono presenti in questi file e non è impostato default, la CLI chiederà i valori durante il deployment e li salverà automaticamente in un file .env denominato .env.<project_ID> nella directory 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

A seconda del flusso di lavoro di sviluppo, potrebbe essere utile aggiungere al controllo della versione il file .env.<project_ID> generato.

Utilizzo dei parametri a livello globale

Durante il deployment, il codice delle funzioni viene caricato e controllato prima che i parametri abbiano valori effettivi. Ciò significa che il recupero dei valori dei parametri durante il ambito globale comporta un errore di deployment. Se vuoi utilizzare un parametro per inizializzare un valore globale, utilizza il callback di inizializzazioneonInit(). Questo callback viene eseguito prima dell'esecuzione di qualsiasi funzione in produzione, ma non viene chiamato durante il deployment, pertanto è un luogo sicuro per accedere al valore di un parametro.

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)

Se utilizzi parametri di tipo Secret, tieni presente che sono disponibili solo nel processo delle funzioni che hanno vincolato il segreto. Se un segreto è associato solo in alcune funzioni, controlla se secret.value() è falsy prima di utilizzarlo.

Configurare il comportamento della CLI

I parametri possono essere configurati con un oggetto Options che controlla la modalità di richiesta dei valori da parte della CLI. L'esempio seguente imposta le opzioni per convalidare il formato di un numero di telefono, per fornire un'opzione di selezione semplice e per compilare automaticamente un'opzione di selezione dal progetto 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",
)

Tipi di parametri

La configurazione con parametri fornisce un tipo sicuro per i valori dei parametri e supporta anche i secret di Cloud Secret Manager. I tipi supportati sono:

• Secret
• Stringa
• Booleano
• Numero intero
• In virgola mobile
• Elenco (Node.js)

Valori e espressioni dei parametri

Firebase valuta i parametri sia al momento del deployment sia durante l'esecuzione della funzione. A causa di questi ambienti doppi, è necessario prestare particolare attenzione quando si confrontano i valori dei parametri e quando li si utilizza per impostare le opzioni di runtime per le funzioni.

Per passare un parametro alla funzione come opzione di runtime, passalo direttamente:

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):
    ...

Inoltre, se devi eseguire un confronto con un parametro per sapere quale opzione scegliere, dovrai utilizzare i comparatori integrati anziché controllare il valore:

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):
    ...

I parametri e le espressioni parametro utilizzati solo in fase di esecuzione possono essere accessi con la relativa funzione 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!')

Parametri integrati

L'SDK Cloud Functions offre tre parametri predefiniti, disponibili nel sottopacchetto firebase-functions/params:

Questi parametri funzionano come parametri di stringa definiti dall'utente sotto tutti gli aspetti, tranne per il fatto che, poiché i relativi valori sono sempre noti a Firebase CLI, non verrà mai richiesto di specificarli durante il deployment né verranno salvati nei file .env.

Parametri secret

I parametri di tipo Secret, definiti utilizzando defineSecret(), rappresentano parametri di stringa con un valore archiviato in Cloud Secret Manager. Invece di confrontarlo con un file .env locale e scrivere un nuovo valore nel file se manca, i parametri secret verificano l'esistenza in Cloud Secret Manager e richiedono in modo interattivo il valore di un nuovo secret durante il deployment.

I parametri secret definiti in questo modo devono essere associati a singole funzioni che devono avere accesso a questi parametri:

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

Poiché i valori dei secret sono nascosti fino all'esecuzione della funzione, non puoi utilizzarli durante la configurazione della funzione.

Variabili di ambiente

Cloud Functions for Firebase supporta il formato file dotenv per il caricamento delle variabili di ambiente specificate in un file .env nel runtime dell'applicazione. Una volta dipistate, le variabili di ambiente possono essere lette tramite l'interfaccia process.env (nei progetti basati su Node.js) o os.environ (nei progetti basati su Python).

Per configurare l'ambiente in questo modo, crea un file .env nel progetto, aggiungi le variabili desiderate ed esegui il deployment di:

1. Crea un file .env nella directory functions/:

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

2. Apri il file .env per modificarlo e aggiungi le chiavi che ti interessano. Ad esempio:

   PLANET=Earth
   AUDIENCE=Humans
   

3. Esegui il deployment delle funzioni e verifica che le variabili di ambiente siano state caricate:

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

Una volta implementate le variabili di ambiente personalizzate, il codice della funzione può accedervi:

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

Eseguire il deployment di più insiemi di variabili di ambiente

Se hai bisogno di un insieme alternativo di variabili di ambiente per i progetti Firebase (ad esempio gestione temporanea o produzione), crea un file .env.<project or alias> in cui scrivi le variabili di ambiente specifiche del progetto. Le variabili di ambiente dei file .env e .env specifici del progetto (se esistenti) verranno incluse in tutte le funzioni di cui è stato eseguito il deployment.

Ad esempio, un progetto potrebbe includere questi tre file contenenti valori leggermente diversi per lo sviluppo e la produzione:

Dati i valori in questi file separati, l'insieme di variabili di ambiente impiegate con le funzioni varierà a seconda del progetto di destinazione:

$ 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

Variabili di ambiente riservate

Alcune chiavi delle variabili di ambiente sono riservate per uso interno. Non utilizzare nessuna di queste chiavi nei file .env:

• Tutte le chiavi che iniziano con X_GOOGLE_
• Tutte le chiavi che iniziano con EXT_
• Tutte le chiavi che iniziano con FIREBASE_
• Qualsiasi chiave del seguente elenco:
• CLOUD_RUNTIME_CONFIG
• ENTRY_POINT
• PROGETTO_Google Cloud
• PROGETTO GCLOUD
• PROGETTO_CLOUD_CLOUD
• FUNCTION_TRIGGER_TYPE
• NOME_FUNZIONE
• FUNCTION_MEMORY_MB
• FUNCTION_TIMEOUT_SEC
• FUNCTION_IDENTITY
• FUNCTION_REGION
• FUNCTION_TARGET
• FUNCTION_SIGNATURE_TYPE
• K_SERVICE
• REVISIONE_K
• PORTA
• K_CONFIGURATION

Archiviare e accedere a informazioni di configurazione sensibili

Le variabili di ambiente memorizzate nei file .env possono essere utilizzate per la configurazione delle funzioni, ma non devono essere considerate un modo sicuro per archiviare informazioni sensibili come credenziali di database o chiavi API. Ciò è particolarmente importante se verifichi il controllo del codice sorgente per i file .env.

Per aiutarti a memorizzare informazioni di configurazione sensibili, Cloud Functions for Firebase si integra con Google Cloud Secret Manager. Questo servizio criptato memorizza i valori di configurazione in modo sicuro, consentendo al contempo un facile accesso dalle funzioni, se necessario.

Creare e utilizzare un secret

Per creare un secret, utilizza l'interfaccia a riga di comando Firebase.

Per creare e utilizzare un secret:

1. Dalla directory principale del progetto locale, esegui il seguente comando:

   firebase functions:secrets:set SECRET_NAME

2. Inserisci un valore per SECRET_NAME.

   L'interfaccia a riga di comando restituisce un messaggio di successo e ti avvisa che devi eseguire il deployment delle funzioni per applicare la modifica.

3. Prima di eseguire il deployment, assicurati che il codice delle funzioni consenta alla funzione di accedere al secret utilizzando il parametro 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. Esegui il deployment di Cloud Functions:

   firebase deploy --only functions

   Ora potrai accedervi come qualsiasi altra variabile di ambiente. Al contrario, se un'altra funzione che non specifica il segreto in runWith tenta di accedervi, riceve un valore non definito:

   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.
   

Una volta dipiattaforma, la funzione avrà accesso al valore della chiave segreta. Solo le funzioni che includono specificamente un secret nel parametro runWith avranno accesso a quel secret come variabile di ambiente. In questo modo puoi assicurarti che i valori dei secret siano disponibili solo dove sono necessari, riducendo il rischio di divulgare accidentalmente un secret.

Gestione dei secret

Utilizza l'interfaccia a riga di comando Firebase per gestire i tuoi secret. Quando gestisci i secret in questo modo, tieni presente che alcune modifiche all'interfaccia a riga di comando richiedono di modificare e/o eseguire nuovamente il deployment delle funzioni associate. Nello specifico:

• Ogni volta che imposti un nuovo valore per un secret, devi eseguire nuovamente il deployment di tutte le funzioni che fanno riferimento a quel secret affinché acquisiscano il valore più recente.
• Se elimini un secret, assicurati che nessuna delle funzioni di cui è stato eseguito il deployment faccia riferimento a quel secret. Le funzioni che utilizzano un valore segreto che è stato eliminato non genereranno alcun errore.

Ecco un riepilogo dei comandi dell'interfaccia a riga di comando Firebase per la gestione dei secret:

# 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

Per i comandi access e destroy, puoi fornire il parametro facoltativo version per gestire una determinata versione. Ad esempio:

functions:secrets:access SECRET_NAME[@VERSION]

Per maggiori informazioni su queste operazioni, passa -h con il comando per visualizzare la guida dell'interfaccia a riga di comando.

Modalità di fatturazione dei secret

Secret Manager consente 6 versioni di secret attive senza costi. Ciò significa che puoi avere 6 secret al mese in un progetto Firebase senza costi.

Per impostazione predefinita, l'interfaccia a riga di comando Firebase tenta di eliminare automaticamente le versioni del secret inutilizzate ove appropriato, ad esempio quando esegui il deployment delle funzioni con una nuova versione del secret. Inoltre, puoi eseguire attivamente la pulizia dei secret inutilizzati utilizzando functions:secrets:destroy e functions:secrets:prune.

Secret Manager consente 10.000 operazioni di accesso mensili non fatturate su un secret. Le istanze di funzione leggono solo i secret specificati nel parametro runWith ogni volta che vengono avviate a freddo. Se hai molte istanze di funzione che leggono molti secret, il tuo progetto potrebbe superare questo limite e ti verranno addebitati 0,03 $ogni 10.000 operazioni di accesso.

Per ulteriori informazioni, consulta la sezione Prezzi di Secret Manager.

Supporto dell'emulatore

La configurazione dell'ambiente con dotenv è progettata per interoperare con un Cloud Functions emulatore locale.

Quando utilizzi un emulatore Cloud Functions locale, puoi eseguire l'override delle variabili di ambiente per il tuo progetto configurando un file .env.local. I contenuti di .env.local hanno la precedenza su .env e sul file .env specifico del progetto.

Ad esempio, un progetto potrebbe includere questi tre file contenenti valori leggermente diversi per lo sviluppo e i test locali:

Quando viene avviato nel contesto locale, l'emulatore carica le variabili di ambiente come mostrato di seguito:

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

Credenziali e dati segreti nell'emulatore Cloud Functions

L'emulatore Cloud Functions supporta l'utilizzo di secret per archiviare e accedere a informazioni di configurazione sensibili. Per impostazione predefinita, l'emulatore tenta di accedere ai secret di produzione utilizzando le credenziali predefinite dell'applicazione. In determinate situazioni, come gli ambienti CI, l'emulatore potrebbe non riuscire ad accedere ai valori secret a causa di restrizioni sulle autorizzazioni.

Analogamente al supporto dell'emulatore Cloud Functions per le variabili di ambiente, puoi eseguire l'override dei valori dei secret impostando un file .secret.local. In questo modo, puoi testare facilmente le funzioni localmente, soprattutto se non hai accesso al valore del secret.

Migrazione dalla configurazione dell'ambiente

Se utilizzi la configurazione dell'ambiente con functions.config, puoi eseguire la migrazione della configurazione esistente come variabili di ambiente (in formato dotenv). L'interfaccia a riga di comando Firebase fornisce un comando di esportazione che genera la configurazione di ogni alias o progetto elencato nel file .firebaserc della directory (nell'esempio seguente, local, dev e prod) come file .env.

Per eseguire la migrazione, esporta le configurazioni dell'ambiente esistenti utilizzando il comando 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

Tieni presente che, in alcuni casi, ti verrà chiesto di inserire un prefisso per rinominare le chiavi delle variabili di ambiente esportate. Questo perché non tutte le configurazioni possono essere trasformate automaticamente, poiché potrebbero non essere valide o potrebbero essere una chiave di variabile di ambiente prenotata.

Ti consigliamo di esaminare attentamente i contenuti dei file .env generati prima di eseguire il deployment delle funzioni o di controllare i file .env nel controllo del codice sorgente. Se alcuni valori sono sensibili e non devono essere divulgati, rimuovili dai file .env e archiviali in modo sicuro in Secret Manager.

Dovrai anche aggiornare il codice delle funzioni. Tutte le funzioni che utilizzano functions.config ora dovranno utilizzare process.env, come mostrato in Voci di ambiente.