Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Émuler Firestore localement

Google Cloud CLI fournit un émulateur local en mémoire pour Firestore que vous pouvez utiliser pour tester votre application. Vous pouvez utiliser l'émulateur avec toutes les bibliothèques clientes Firestore. Vous ne devez utiliser l'émulateur que pour des tests locaux.

N'utilisez pas l'émulateur pour les déploiements de production. Étant donné que l'émulateur ne stocke que les données en mémoire, il ne les conserve pas lors des exécutions.

Installer l'émulateur

Pour installer l'émulateur Firestore, installez et mettez à jour gcloud CLI:

  1. Installer gcloud CLI.

  2. Mettez à jour votre installation de gcloud CLI pour obtenir les dernières fonctionnalités:

    gcloud components update
    

Exécuter l'émulateur

  1. Exécutez la commande suivante pour démarrer l'émulateur :

    gcloud emulators firestore start
    

    L'émulateur imprime l'hôte et le numéro de port sur lequel il s'exécute.

    Par défaut, l'émulateur tente d'utiliser localhost:8080. Pour lier l'émulateur à un hôte et à un port spécifiques, utilisez l'option facultative --host-port en remplaçant HOST et PORT:

    gcloud emulators firestore start --host-port=HOST:PORT
    
  2. Saisissez Control + C pour arrêter l'émulateur.

Se connecter à l'émulateur

La manière dont vous vous connectez à l'émulateur dépend du type de bibliothèque cliente, de la bibliothèque cliente du serveur ou du SDK mobile/Web.

Bibliothèques clientes de serveur

Pour connecter une bibliothèque cliente du serveur Firestore (C#, Go, Java, Node.js, PHP, Python et Ruby), définissez la variable d'environnement FIRESTORE_EMULATOR_HOST. Lorsque cette variable d'environnement est définie, les bibliothèques clientes du serveur se connectent automatiquement à l'émulateur.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

Android, plates-formes Apple et SDK Web

Les exemples suivants montrent comment connecter les plates-formes Android, Apple et Web sur l'émulateur Firestore:

Android
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
Swift
let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Version Web 9

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);

Version Web 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("localhost", 8080);
}

L'émulateur Firestore efface le contenu de la base de données à l'arrêt. Étant donné que le cache hors connexion du SDK Firestore n'est pas effacé automatiquement, vous pouvez désactiver la persistance locale dans la configuration de votre émulateur pour éviter les écarts entre la base de données émulée et les caches locaux. Dans le SDK Web, la persistance est désactivée par défaut.

Effacer les données de l'émulateur

L'émulateur Firestore inclut un point de terminaison REST permettant de supprimer toutes les données de l'émulateur. Vous pouvez utiliser ce point de terminaison pour effacer les données entre les tests sans arrêter l'émulateur.

Pour supprimer toutes les données de l'émulateur, effectuez une opération HTTP DELETE sur le point de terminaison suivant, en remplaçant HOST et PORT par l'hôte et le port que vous avez sélectionnés, et en remplaçant PROJECT_ID par votre propre ID de projet:

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

Ajustez l'hôte et le port si l'émulateur n'utilise pas localhost:8080. Votre code doit attendre la confirmation REST que la suppression est terminée ou a échoué.

Vous pouvez effectuer cette opération à partir de l'interface système à l'aide de curl :

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

Différences entre l'émulateur Firestore et la production

L'émulateur Firestore tente de répliquer fidèlement le comportement du service de production, avec certaines limitations notables.

Transactions

L'émulateur n'implémente pas tous les comportements de transaction observés en production. Lorsque vous testez des caractéristiques impliquant plusieurs écritures simultanées dans un document, l'émulateur peut prendre du temps pour effectuer des requêtes d'écriture. Dans certains cas, le déverrouillage peut prendre jusqu'à 30 secondes. Si nécessaire, envisagez d'ajuster les délais avant expiration des tests en conséquence.

Index

L'émulateur n'effectue pas le suivi des index composites et exécute plutôt toute requête valide. Veillez à tester votre application sur une instance Firestore réelle pour déterminer les index dont vous avez besoin.

Limites

L'émulateur n'applique pas toutes les limites appliquées en production. Par exemple, l'émulateur peut autoriser les transactions qui seraient rejetées comme trop volumineuses par le service de production. Assurez-vous que vous connaissez les limites documentées et que vous concevez votre application pour les éviter de manière proactive.