Esta página foi traduzida pela API Cloud Translation.

Usar o emulador do Firestore localmente

A Google Cloud CLI oferece 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 se conectar ao emulador depende do tipo de biblioteca de cliente, 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 está definida, as bibliotecas de cliente do servidor se conectam automaticamente ao emulador.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

SDKs do Android, da Apple e da Web

Os exemplos a seguir demonstram como conectar os SDKs do Android, das plataformas da Apple e 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 no modo nativo 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 desligar o emulador.

Para excluir todos os dados no emulador, execute uma operação HTTP DELETE no endpoint a seguir, substituindo HOST e PORT pelo host e pela porta selecionados e substituindo PROJECT_ID pelo ID do seu 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 deve 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 tenta imitar o comportamento da transação visto na produção. Ele usa uma abordagem de bloqueio simples e não tenta espelhar os vários modos de simultaneidade oferecidos no ambiente de 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. Pode levar até 30 segundos para o emulador liberar os bloqueios. Se for necessário ajustar os intervalos de tempo limite do teste, faça isso.

O emulador também não tenta imitar todos os limites de produção, como tempos limite e limites de tamanho, que envolvem transações. Se você testar recursos que dependem desses limites de produção, recomendamos usar um ambiente de produção em vez de um emulador.

Índices

O emulador não rastreia índices compostos. Em vez disso, ele 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.