Gérer les configurations de projet avec le fichier manifeste des extensions

Un fichier manifeste d'extensions est une liste d'instances d'extensions et de leurs configurations. Le fichier manifeste vous permet d'effectuer les opérations suivantes :

• Partager la configuration de vos extensions avec d'autres utilisateurs
• Copier la configuration de vos extensions entre différents projets (par exemple, de votre projet de préproduction vers votre projet de production)
• Déployer toutes vos extensions en même temps
• Testez le fonctionnement de vos extensions avec votre application à l'aide de Firebase Local Emulator Suite.
• Valider la configuration de vos extensions dans le contrôle de code source
• Inclure des extensions dans votre pipeline CI/CD

Un fichier manifeste d'extensions comporte deux parties :

• La section extensions de votre firebase.json, qui est un mappage de l'ID d'instance à la référence de la version de l'extension. Exemple :

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

• Fichiers .env contenant la configuration de chacune de vos instances d'extension, dans le sous-répertoire extensions/ du répertoire de votre projet Firebase. Par exemple, une instance de storage-resize-images peut avoir un fichier .env comme suit :

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

Si vous ne souhaitez pas enregistrer les données de configuration de chaque instance d'extension, vous pouvez modifier le fichier firebase.json et supprimer les entrées inutiles de la section extensions.

Créer un fichier manifeste d'extensions

Il existe trois façons de créer un fichier manifeste d'extensions :

• Gérer le fichier manifeste de vos extensions avec la CLI Firebase
• Exporter la configuration des extensions d'un projet
• Modifier manuellement les fichiers manifestes

Les deux premières méthodes sont expliquées ci-dessous.

Gérer le fichier manifeste de vos extensions avec la CLI Firebase

Vous pouvez exécuter la plupart des commandes ext: de la CLI Firebase avec l'option --local pour mettre à jour le fichier manifeste des extensions sans modifier la configuration actuelle du projet.

Exemple :

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

L'exécution de la commande ci-dessus vous invite à configurer la dernière version de l'extension firebase/firestore-bigquery-export et à enregistrer la configuration dans le fichier manifeste, mais elle ne déploie pas la configuration dans votre projet.

Voici d'autres exemples de commandes qui modifient le fichier manifeste des extensions :

# 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

Exporter la configuration des extensions d'un projet

Pour enregistrer la configuration actuelle des extensions d'un projet dans le fichier manifeste, procédez comme suit :

1. Si vous ne l'avez pas déjà fait, configurez la CLI Firebase.
2. À partir d'une invite de shell, accédez au répertoire du projet. (Le répertoire de votre projet contient le fichier firebase.json).
3. Exécutez la commande ext:export :

   firebase ext:export

La commande ext:export ajoute une section extensions au fichier firebase.json. De plus, la commande ext:export crée un répertoire extensions contenant un fichier .env pour chaque instance d'extension que vous avez installée. Ces fichiers contiennent les paramètres de configuration de chaque instance.

Tester une configuration d'extensions avec Firebase Local Emulator Suite

Une fois que vous avez ajouté des instances d'extension à votre fichier manifeste d'extensions, vous pouvez les tester à l'aide de Local Emulator Suite.

1. Installez et configurez Local Emulator Suite.

2. Démarrez Local Emulator Suite :

   • Pour exécuter la suite d'émulateurs de manière interactive, exécutez la commande suivante : firebase emulators:start
   • Pour exécuter la suite d'émulateurs et un script de test, exécutez la commande suivante : firebase emulators:exec my-test.sh

Si des instances d'extension sont listées dans votre fichier manifeste, la commande Local Emulator Suite télécharge le code source de ces extensions dans ~/.cache/firebase/extensions. Une fois le téléchargement terminé, Local Emulator Suite démarre. Vous pouvez alors déclencher n'importe quelle fonction d'arrière-plan des extensions et connecter votre application à la suite d'émulateurs pour tester leur intégration à votre application.

Les instances d'extension émulées peuvent potentiellement effectuer des appels en direct vers des API tierces et des API Google non émulées. Avant de tester une extension, lisez ses instructions post-installation pour vous assurer que vous connaissez tous les appels externes qu'elle effectue.

Déployer une configuration d'extensions dans un projet

Une fois que vous avez ajouté des instances d'extension à votre fichier manifeste d'extension, vous pouvez le déployer dans un projet à l'aide de la CLI Firebase. Lorsque vous effectuez un déploiement avec un fichier manifeste d'extensions, vous installez, mettez à jour et configurez toutes les instances d'extension du fichier manifeste dans un projet en une seule fois.

Pour déployer un fichier manifeste d'extensions :

1. À partir d'une invite de shell, accédez au répertoire contenant la configuration des extensions enregistrées. (Il s'agit du répertoire contenant firebase.json. Si vous venez d'exécuter ext:export, vous êtes déjà dans le bon répertoire.)
2. Exécutez la commande deploy. Si vous souhaitez déployer les extensions sur un projet autre que le projet actuel, spécifiez également --project= :

   firebase deploy --only extensions –-project=YOUR_PROJECT_ID

La commande deploy valide chaque configuration d'instance, vous demande si vous souhaitez supprimer de votre projet de destination les instances d'extension qui ne figurent pas dans firebase.json, puis déploie toutes vos instances d'extension.

Configurations d'extension spécifiques au projet

Les configurations d'extensions enregistrées peuvent être utilisées pour effectuer un déploiement sur plusieurs projets différents, par exemple un projet de préproduction et un projet de production. Dans ce cas, certaines valeurs de paramètre peuvent être différentes pour chaque projet. Les fichiers .env spécifiques au projet permettent d'effectuer les opérations suivantes :

• Placez les valeurs de paramètre qui diffèrent d'un projet à l'autre dans extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
• Placez les valeurs de paramètres partagées dans extensions/EXTENSION_INSTANCE_ID.env.

Parfois, vous pouvez vouloir utiliser une valeur de paramètre différente lors de l'émulation de vos extensions. Par exemple, vous pouvez fournir une clé API de test au lieu d'une clé de production. Placez ces paramètres dans un fichier .local :

• Placez les paramètres non secrets que vous souhaitez utiliser lors de l'émulation dans extensions/EXTENSION_INSTANCE_ID.env.local.
• Placer les valeurs de paramètres secrets dans extensions/EXTENSION_INSTANCE_ID.secret.local