Cette page a été traduite par l'API Cloud Translation.

Utiliser l'émulateur Firestore en local

La 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 les tests locaux.

N'utilisez pas l'émulateur pour les déploiements de production. Étant donné que l'émulateur stocke les données uniquement 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 :

Installez la CLI gcloud.
Mettez à jour votre installation de gcloud CLI pour bénéficier des dernières fonctionnalités :
```
gcloud components update
```

Exécuter l'émulateur

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 127.0.0.1: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
```
Saisissez Control + C pour arrêter l'émulateur. L'émulateur peut également être arrêté avec une requête POST envoyée à /shutdown. Exemple :
```
curl -d '' HOST:PORT/shutdown
```

Se connecter à l'émulateur

La façon dont vous vous connectez à l'émulateur dépend du type de bibliothèque cliente, de bibliothèque cliente de serveur ou de SDK pour 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"

SDK Android, Apple et Web

Les exemples suivants montrent comment connecter les SDK Android, Apple Platforms et Web à 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);EmulatorSuite.java

Swift

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settingsViewController.swift

Version Web 9

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

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);fs_emulator_connect.js

Version Web 8

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

L'émulateur Firestore en mode natif efface le contenu de la base de données lorsqu'il est 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 actuellement présentes dans 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 127.0.0.1:8080. Votre code doit attendre la confirmation REST que la suppression a réussi ou échoué.

Vous pouvez effectuer cette opération à partir du shell à 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 reproduire fidèlement le comportement du service de production, avec quelques limites notables.

Transactions

L'émulateur ne tente pas d'imiter le comportement des transactions observé en production. Il utilise une approche de verrouillage simple et ne tente pas de refléter les différents modes de simultanéité proposés dans l'environnement de production.

Lorsque vous testez des fonctionnalités impliquant plusieurs écritures simultanées dans un même document, l'émulateur peut mettre du temps à traiter les requêtes d'écriture. L'émulateur peut mettre jusqu'à 30 secondes pour libérer les verrous. Si vous devez ajuster les intervalles de délai avant expiration des tests, faites-le.

L'émulateur ne tente pas non plus d'imiter toutes les limites de production, telles que les délais d'attente et les limites de taille, qui impliquent des transactions. Si vous testez des fonctionnalités qui dépendent de ces limites de production, nous vous recommandons d'utiliser un environnement de production plutôt qu'un émulateur.

Index

L'émulateur ne suit pas les index composites et exécute plutôt toute requête valide. Veillez à tester votre application sur une véritable instance Firestore 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 des transactions qui seraient refusées comme étant trop importantes par le service de production. Assurez-vous de connaître les limites documentées et de concevoir votre application de manière à les éviter de manière proactive.