Gestire le configurazioni dei progetti con il manifest delle estensioni

Un manifesto delle estensioni è un elenco di istanze di estensioni e delle relative configurazioni. Con il manifesto puoi:

  • Condividere la configurazione delle estensioni con altri
  • Copiare la configurazione delle estensioni tra progetti diversi (ad esempio dal progetto di staging al progetto di produzione)
  • Eseguire il deployment di tutte le estensioni contemporaneamente
  • Testare il funzionamento delle estensioni con l'app utilizzando Firebase Local Emulator Suite
  • Eseguire il commit della configurazione delle estensioni nel controllo del codice sorgente
  • Includere le estensioni nella pipeline CI/CD

Un manifesto delle estensioni è composto da due parti:

  • La sezione extensions di firebase.json, che è una mappa dell'ID istanza al riferimento della versione dell'estensione. Ad esempio:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • File .env contenenti la configurazione di ogni istanza di estensione nella sottodirectory extensions/ della directory del progetto Firebase. Ad esempio, un'istanza di storage-resize-images potrebbe avere un file .env simile al seguente:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.firebasestorage.app
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Creare un manifesto delle estensioni

Esistono tre modi per creare un manifesto delle estensioni:

  • Gestire il manifesto delle estensioni con l'interfaccia a riga di comando di Firebase
  • Esportare la configurazione delle estensioni di un progetto
  • Modificare manualmente i file manifest

I primi due metodi sono spiegati di seguito.

Gestire il manifesto delle estensioni con l'interfaccia a riga di comando di Firebase

Puoi eseguire la maggior parte dei comandi ext: dell'interfaccia a riga di comando di Firebase con l'opzione --local per aggiornare il manifesto delle estensioni senza modificare effettivamente la configurazione attuale del progetto.

Ad esempio:

firebase ext:install --local firebase/firestore-bigquery-export

L'esecuzione del comando riportato sopra ti chiederà di configurare l'ultima versione dell'estensione firebase/firestore-bigquery-export e di salvare la configurazione nel manifesto, ma non eseguirà il deployment della configurazione nel progetto.

Ecco altri esempi di comandi che modificano il manifesto delle estensioni:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Esportare la configurazione delle estensioni di un progetto

Per salvare la configurazione delle estensioni attuale di un progetto nel manifesto:

  1. Se non l'hai ancora fatto, configura l'interfaccia a riga di comando di Firebase
  2. Da un prompt della shell, passa alla directory del progetto. La directory del progetto contiene il file firebase.json.
  3. Esegui il comando ext:export: 
    firebase ext:export

Il comando ext:export aggiungerà una sezione extensions al file firebase.json. Inoltre, il comando ext:export crea una directory extensions contenente un file .env per ogni istanza di estensione installata. Questi file contengono i parametri di configurazione per ogni istanza.

Testare una configurazione delle estensioni con il Firebase Local Emulator Suite

Dopo aver aggiunto alcune istanze di estensioni al manifesto delle estensioni, puoi testarle utilizzando Local Emulator Suite.

  1. Installa e configura Local Emulator Suite.

  2. Avvia Local Emulator Suite:

    • Per eseguire Local Emulator Suite in modo interattivo, esegui: firebase emulators:start
    • Per eseguire Emulator Suite ed eseguire uno script per il test, esegui: firebase emulators:exec my-test.sh

Ora, se nel manifesto sono elencate istanze di estensioni, il Local Emulator Suite scaricherà il codice sorgente di queste estensioni in ~/.cache/firebase/extensions. Una volta scaricate, Local Emulator Suite si avvierà e potrai attivare le funzioni attivate in background delle estensioni e connettere l'app a Emulator suite per testare la loro integrazione con l'app.

Eseguire il deployment di una configurazione delle estensioni in un progetto

Dopo aver aggiunto alcune istanze di estensioni al manifesto delle estensioni, puoi eseguirne il deployment in un progetto utilizzando l'interfaccia a riga di comando di Firebase. Quando esegui il deployment con un manifesto delle estensioni, installi, aggiorni e configuri contemporaneamente tutte le istanze di estensioni nel manifesto in un progetto.

Per eseguire il deployment di un manifesto delle estensioni:

  1. Da un prompt della shell, passa alla directory contenente la configurazione delle estensioni salvata. Si tratta della directory contenente firebase.json. Se hai appena eseguito ext:export, ti trovi già nella directory corretta.
  2. Esegui il comando deploy. Se vuoi eseguire il deployment delle estensioni in un progetto diverso da quello attuale, specifica anche --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Il comando deploy convaliderà la configurazione di ogni istanza, ti chiederà se vuoi eliminare le istanze di estensioni dal progetto di destinazione che non sono elencate in firebase.json e poi eseguirà il deployment di tutte le istanze di estensioni.

Configurazioni delle estensioni specifiche del progetto

Le configurazioni delle estensioni salvate possono essere utilizzate per il deployment in più progetti diversi, ad esempio un progetto di staging e un progetto di produzione. In questo caso, alcuni valori dei parametri potrebbero dover essere diversi per ogni progetto. I file .env specifici del progetto lo rendono possibile:

  • Inserisci i valori dei parametri che differiscono tra i progetti in extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID
  • Inserisci i valori dei parametri condivisi in extensions/EXTENSION_INSTANCE_ID.env.

A volte, potresti voler utilizzare un valore parametro diverso durante l'emulazione delle estensioni, ad esempio potresti voler fornire una chiave API di test anziché una di produzione. Inserisci questi parametri in un file .local:

  • Inserisci i parametri non segreti che vuoi utilizzare durante l'emulazione in extensions/EXTENSION_INSTANCE_ID.env.local
  • Inserisci i valori dei parametri segreti in extensions/EXTENSION_INSTANCE_ID.secret.local