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

Un fichier manifeste d'extension est une liste d'instances d'extension et de leurs configurations. Le fichier manifeste vous permet de:

• 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 à votre projet de production)
• Déployer toutes vos extensions en même temps
• Tester le fonctionnement de vos extensions avec votre application à l'aide de Firebase Local Emulator Suite
• Valider la configuration de vos extensions dans un système de contrôle de version
• Inclure des extensions dans votre pipeline CI/CD

Un fichier manifeste d'extension comporte deux parties:

• La section extensions de votre firebase.json, qui est une mise en correspondance de l'ID d'instance avec 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}.appspot.com
  IMG_SIZES=100x100
  DELETE_ORIGINAL_FILE=false

Si vous ne souhaitez pas enregistrer de données de configuration pour 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'extension

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

• Gérer votre fichier manifeste d'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 votre fichier manifeste d'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. Dans 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 la configuration d'une extension 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 le Local Emulator Suite:

   • Pour exécuter la suite d'émulateurs de manière interactive, exécutez : 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

Maintenant, si des instances d'extension sont listées dans votre fichier manifeste, Local Emulator Suite téléchargera le code source de ces extensions dans ~/.cache/firebase/extensions. Une fois le téléchargement terminé, Local Emulator Suite démarre et vous pouvez déclencher l'une des fonctions déclenchées en arrière-plan des extensions, puis 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 à des API tierces et à des API Google non émulées. Consultez les instructions post-installation de chaque extension avant de la tester pour vous assurer que vous êtes au courant de 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 déployez avec un fichier manifeste d'extension, vous installez, mettez à jour et configurez toutes les instances d'extension du fichier manifeste dans un projet en même temps.

Pour déployer un fichier manifeste d'extension:

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 dans un projet autre que celui en cours, 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 les instances d'extension de votre projet de destination 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 le déploiement dans plusieurs projets différents: par exemple, un projet de préproduction et un projet de production. Dans ce cas, certaines valeurs de paramètres peuvent être différentes pour chaque projet. Les fichiers .env spécifiques au projet permettent de le faire:

• Placez les valeurs de paramètre qui diffèrent entre les projets dans extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID.
• Placez les valeurs de paramètres partagées dans extensions/EXTENSION_INSTANCE_ID.env.

Il peut arriver que vous souhaitiez 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. Insérez ces paramètres dans un fichier .local:

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