Connecter votre application à l'émulateur Cloud Storage for Firebase

Avant de connecter votre application à l'émulateur Cloud Storage for Firebase, assurez-vous de comprendre le workflow global de Firebase Local Emulator Suite, d'installer et de configurer Local Emulator Suite, et de consulter ses commandes CLI.

Choisir un projet Firebase

Firebase Local Emulator Suite émule des produits pour un seul projet Firebase.

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, exécutez firebase use dans votre répertoire de travail dans la CLI. Vous pouvez également transmettre l'option --project à chaque commande de l'émulateur.

Local Emulator Suite est compatible avec l'émulation de projets Firebase réels et de projets de démonstration.

Type de projet Fonctionnalités Utiliser avec des émulateurs
Situation réelle

Un projet Firebase réel est celui que vous avez créé et configuré (le plus souvent via la console Firebase).

Les projets réels disposent de ressources en ligne, comme des instances de base de données, des buckets de stockage, des fonctions ou toute autre ressource que vous configurez pour ce projet Firebase.

Lorsque vous travaillez avec de véritables projets Firebase, vous pouvez exécuter des émulateurs pour tous les produits compatibles ou certains d'entre eux.

Pour tous les produits que vous n'émulez pas, vos applications et votre code interagissent avec la ressource en direct (instance de base de données, bucket de stockage, fonction, etc.).

Démo

Un projet Firebase de démonstration ne comporte aucune configuration réelle de Firebase et aucune ressource en ligne. Pour accéder à ces projets, vous devez généralement suivre des ateliers de programmation ou d'autres tutoriels.

Les ID de projet des projets de démonstration portent le préfixe demo-.

Lorsque vous travaillez avec des projets Firebase de démonstration, vos applications et votre code n'interagissent qu'avec des émulateurs. Si votre application tente d'interagir avec une ressource pour laquelle aucun émulateur n'est en cours d'exécution, ce code échouera.

Dans la mesure du possible, nous vous recommandons d'utiliser des projets de démonstration. Voici quelques-uns de ses avantages :

  • Configuration plus simple, car vous pouvez exécuter les émulateurs sans avoir à créer un projet Firebase
  • Sécurité renforcée, car si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucune chance de modification, d'utilisation et de facturation des données.
  • Meilleure prise en charge hors connexion, car vous n'avez pas besoin d'accéder à Internet pour télécharger la configuration de votre SDK.

Instrumenter votre application pour qu'elle communique avec les émulateurs

Android, plates-formes Apple et SDK Web

Configurez votre configuration dans l'application ou vos classes de test pour interagir avec l'émulateur Cloud Storage for Firebase comme suit.

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val storage = Firebase.storage
storage.useEmulator("10.0.2.2", 9199)
EmulatorSuite.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseStorage storage = FirebaseStorage.getInstance();
storage.useEmulator("10.0.2.2", 9199);
EmulatorSuite.java
Swift
Storage.storage().useEmulator(withHost: "127.0.0.1", port: 9199)
ViewController.swift

Web

const { getStorage, connectStorageEmulator } = require("firebase/storage");

const storage = getStorage();
if (location.hostname === "localhost") {
  // Point to the Storage emulator running on localhost.
  connectStorageEmulator(storage, "127.0.0.1", 9199);
} 
emulator-suite.js

Web

var storage = firebase.storage();
if (location.hostname === "localhost") {
  // Point to the Storage emulator running on localhost.
  storage.useEmulator("127.0.0.1", 9199);
} 
emulator-suite.js

Aucune configuration supplémentaire n'est nécessaire pour tester les fonctions Cloud déclenchées par des événements Cloud Storage for Firebase à l'aide de l'émulateur. Lorsque les émulateurs Cloud Storage for Firebase et Cloud Functions sont tous deux en cours d'exécution, ils fonctionnent automatiquement ensemble.

Admin SDK s

Les Firebase Admin SDK se connectent automatiquement à l'émulateur Cloud Storage for Firebase lorsque la variable d'environnement FIREBASE_STORAGE_EMULATOR_HOST est définie:

export FIREBASE_STORAGE_EMULATOR_HOST="127.0.0.1:9199"

Notez que l'émulateur Cloud Functions est automatiquement conscient de l'émulateur Cloud Storage for Firebase. Vous pouvez donc ignorer cette étape lorsque vous testez les intégrations entre les émulateurs Cloud Functions et Cloud Storage for Firebase. La variable d'environnement sera automatiquement définie pour le SDK Admin dans Cloud Storage for Firebase.

Si vous souhaitez que votre code Admin SDK se connecte à un émulateur partagé exécuté dans un autre environnement, vous devez spécifier le même ID de projet que celui que vous avez défini à l'aide de la CLI Firebase. Vous pouvez transmettre directement un ID de projet à initializeApp ou définir la variable d'environnement GCLOUD_PROJECT.

SDK Admin Node.js
admin.initializeApp({ projectId: "your-project-id" });
Variable d'environnement
export GCLOUD_PROJECT="your-project-id"

Importer et exporter des données

Les émulateurs de base de données et Cloud Storage for Firebase vous permettent d'exporter des données à partir d'une instance d'émulateur en cours d'exécution. Définissez un ensemble de données de référence à utiliser dans vos tests unitaires ou vos workflows d'intégration continue, puis exportez-le pour le partager avec l'équipe.

firebase emulators:export ./dir

Lors des tests, au démarrage de l'émulateur, importez les données de référence.

firebase emulators:start --import=./dir

Vous pouvez demander à l'émulateur d'exporter des données à l'arrêt, en spécifiant un chemin d'exportation ou simplement en utilisant le chemin d'accès transmis à l'indicateur --import.

firebase emulators:start --import=./dir --export-on-exit

Ces options d'importation et d'exportation de données fonctionnent également avec la commande firebase emulators:exec. Pour en savoir plus, consultez la documentation de référence sur les commandes de l'émulateur.

Différences entre l'émulateur Cloud Storage for Firebase et la production

Pour tester les applications clientes, l'émulateur Cloud Storage for Firebase s'aligne presque parfaitement sur la production en ce qui concerne la surface de l'API Firebase. Toutes les commandes Firebase devraient fonctionner entre les SDK Firebase standards (plates-formes Web, Android et Apple).

Des limites existent pour les tests des applications côté serveur. Les SDK Admin Firebase utilisent la surface de l'API Google Cloud, et tous les points de terminaison de cette API ne sont pas émulés. En règle générale, tout ce qui peut être effectué à partir des SDK client (importer ou supprimer des fichiers, obtenir et définir des métadonnées) est également implémenté pour être utilisé à partir des SDK administrateur, mais ce n'est pas le cas pour tout le reste. Vous trouverez ci-dessous les principales exclusions.

Différences par rapport à Google Cloud Storage

Le produit Cloud Storage for Firebase, y compris l'émulateur Storage, fournit un sous-ensemble de fonctionnalités Google Cloud Storage (GCS) axées sur les objets de stockage, qui est très utile pour développer des applications Firebase. Cloud Storage for Firebase diffère de GCS sur les points suivants:

  • Cloud Storage for Firebase n'est actuellement pas compatible avec les API Bucket pour créer, lister, obtenir ou supprimer des buckets de stockage.
  • Dans l'API Google Cloud Storage Objects, les méthodes suivantes sont acceptées: copy, delete, get, insert, list, patch, rewrite et update.

Cloud IAM

La suite d'émulateurs Firebase ne tente pas de reproduire ni de respecter le comportement lié à l'IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies, mais dans les cas où IAM est normalement utilisé, par exemple pour définir le compte de service d'invocation de Cloud Functions et donc les autorisations, l'émulateur n'est pas configurable et utilisera le compte disponible dans le monde entier sur votre ordinateur de développement, comme si vous exécutiez directement un script local.

Notifications Pub/Sub

L'émulateur Cloud Storage for Firebase ne s'intègre pas à l'émulateur Cloud Pub/Sub et n'est donc pas compatible avec la création de canaux/notifications pour les modifications apportées aux objets de stockage. Nous vous recommandons d'utiliser directement les déclencheurs de stockage Cloud Functions.

Métadonnées au niveau du bucket

L'émulateur Cloud Storage for Firebase n'est pas compatible avec la configuration au niveau du bucket, y compris la classe de stockage, la configuration CORS au niveau du bucket, les libellés ou les règles de conservation. Firebase a l'intention d'améliorer cette compatibilité au fil du temps.

Et maintenant ?