Esta página foi traduzida pela API Cloud Translation.

Usar o emulador do Firestore localmente

A Google Cloud CLI fornece um emulador local na memória para o Firestore, que pode ser usado para testar o aplicativo. É possível usar o emulador com todas as bibliotecas de cliente do Firestore. Use o emulador apenas para testes locais.

Não use o emulador para implantações de produção. Como o emulador armazena dados apenas na memória, ele não mantém os dados nas execuções.

Instalar o emulador

Para instalar o emulador do Firestore, instale e atualize a CLI gcloud:

Instale a CLI da gcloud.
Atualize a instalação da CLI da gcloud para receber os recursos mais recentes:
```
gcloud components update
```

Executar o emulador

Execute o seguinte comando para iniciar o emulador:
```
gcloud emulators firestore start
```
O emulador imprime o host e o número da porta em que está sendo executado.

Por padrão, o emulador tenta usar 127.0.0.1:8080. Para vincular o emulador a um host e uma porta específicos, use a flag --host-port opcional, substituindo HOST e PORT:
```
gcloud emulators firestore start --host-port=HOST:PORT
```
Digite Control + C para interromper o emulador. O emulador também pode ser interrompido com um POST para /shutdown. Exemplo:
```
curl -d '' HOST:PORT/shutdown
```

Conectar-se ao emulador

A forma de conexão com o emulador depende do tipo de biblioteca de cliente, de servidor ou SDK para dispositivos móveis/Web.

Bibliotecas de cliente do servidor

Para conectar uma biblioteca de cliente do servidor do Firestore (C#, Go, Java, Node.js, PHP, Python e Ruby), defina a variável de ambiente FIRESTORE_EMULATOR_HOST. Quando essa variável de ambiente é definida, as bibliotecas de cliente do servidor se conectam automaticamente ao emulador.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

SDKs para Android, plataformas da Apple e Web

Os exemplos a seguir demonstram como conectar o Android, as plataformas da Apple e os SDKs da Web ao emulador do 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

Versão 9 para a Web

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

Versão 8 para a Web

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

O emulador do Firestore limpa o conteúdo do banco de dados quando é encerrado. Como o cache off-line do SDK do Firestore não é limpo automaticamente, desative a persistência local na configuração do emulador para evitar discrepâncias entre o banco de dados emulado e os caches locais. No SDK da Web, a persistência é desativada por padrão.

Limpar dados do emulador

O emulador do Firestore inclui um endpoint REST para excluir todos os dados atualmente no emulador. É possível usar esse endpoint para limpar dados entre testes sem encerrar o emulador.

Para excluir todos os dados no emulador, execute uma operação DELETE HTTP no endpoint a seguir, substituindo HOST e PORT pelo host e pela porta selecionados e substituindo PROJECT_ID pelo seu ID do projeto:

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

Ajuste o host e a porta se o emulador não usar 127.0.0.1:8080. O código precisa aguardar a confirmação REST de que a exclusão foi concluída ou falhou.

Você pode executar essa operação no shell usando curl:

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

Qual é a diferença entre o emulador do Firestore e a produção

O emulador do Firestore tenta replicar o comportamento do serviço de produção de maneira fiel, com algumas limitações notáveis.

Transações

O emulador não implementa todo o comportamento da transação encontrado na produção. Quando você está testando recursos que envolvem várias gravações simultâneas em um documento, o emulador pode demorar para concluir solicitações de gravação. Em alguns casos, os bloqueios podem levar até 30 segundos para serem liberados. Considere ajustar os tempos limites do teste de acordo, se necessário.

Índices

O emulador não rastreia índices compostos e, em vez disso, executa consultas válidas. Não deixe de testar o app com uma instância real do Firestore para determinar quais índices são necessários.

Limites

O emulador não impõe todos os limites aplicados na produção. Por exemplo, o emulador pode permitir transações que são rejeitadas por serem muito grandes pelo serviço de produção. Verifique se você conhece os limites documentados e se desenvolve o app para evitá-los de maneira proativa.