Gestire le configurazioni dei progetti con il manifest delle estensioni

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

• Condividi la configurazione delle estensioni con altre persone
• Copia la configurazione delle estensioni tra progetti diversi (ad esempio dal progetto di gestione temporanea al progetto di produzione)
• Esegui il deployment di tutte le estensioni contemporaneamente
• Testa il funzionamento delle estensioni con la tua app utilizzando Firebase Local Emulator Suite
• Esegui il commit della configurazione delle estensioni nel controllo del codice sorgente
• Includi le estensioni nella pipeline CI/CD

Un manifest 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 per ciascuna delle istanze delle estensioni, nella sottodirectory extensions/ della directory del progetto Firebase. Ad esempio, un'istanza di storage-resize-images potrebbe avere un file .env come il seguente:

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

Se non vuoi salvare i dati di configurazione per ogni istanza di estensione, puoi modificare il file firebase.json e rimuovere le voci non necessarie dalla sezione extensions.

Crea un manifest delle estensioni

Esistono tre modi per creare un manifest delle estensioni:

• Gestisci il manifest delle estensioni con l'interfaccia a riga di comando di Firebase
• Esporta la configurazione delle estensioni di un progetto
• Modifica manualmente i file manifest

I primi due metodi sono spiegati di seguito.

Gestisci il manifest 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 manifest delle estensioni senza modificare la configurazione attuale del progetto.

Ad esempio:

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

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

Ecco alcuni altri esempi di comandi che modificano il manifest 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

Esporta la configurazione delle estensioni di un progetto

Per salvare nel manifest la configurazione attuale delle estensioni di un progetto, segui questi passaggi:

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.

Testa una configurazione delle estensioni con Firebase Local Emulator Suite

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

1. Installa e configura Local Emulator Suite.

2. Avvia Local Emulator Suite:

   • Per eseguire la Suite di emulatori in modo interattivo, esegui: firebase emulators:start
   • Per eseguire la suite di emulatori ed eseguire uno script di test, esegui: firebase emulators:exec my-test.sh

Ora, se nel manifest sono elencate istanze di estensioni, Local Emulator Suite scaricherà il codice sorgente di queste estensioni in ~/.cache/firebase/extensions. Una volta scaricati, l'Local Emulator Suite verrà avviato e potrai attivare qualsiasi funzione attivata in background delle estensioni e connettere la tua app alla suite di emulatori per testare la loro integrazione con la tua app.

Le istanze di estensioni emulate possono potenzialmente effettuare chiamate in tempo reale ad API di terze parti e ad API di Google non emulate. Esamina le istruzioni post-installazione di ogni estensione prima di eseguire il test per assicurarti di essere a conoscenza di eventuali chiamate esterne che effettua.

Esegui il deployment di una configurazione delle estensioni in un progetto

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

Per eseguire il deployment di un manifest delle estensioni:

1. Da un prompt della shell, passa alla directory che contiene la configurazione delle estensioni salvata. (Questa è la directory che contiene 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 corrente, specifica anche --project=:

   firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Il comando deploy convaliderà ogni configurazione di istanza, ti chiederà se vuoi eliminare dal progetto di destinazione eventuali istanze di estensione non elencate in firebase.json, quindi eseguirà il deployment di tutte le istanze di estensione.

Configurazioni delle estensioni specifiche per il progetto

Le configurazioni delle estensioni salvate possono essere utilizzate per il deployment in più progetti diversi, ad esempio un progetto di gestione temporanea 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 tue 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 secret in extensions/EXTENSION_INSTANCE_ID.secret.local