A Google Cloud CLI fornece um emulador local na memória para Firestore que pode ser usado para testar o Firestore no aplicativo no modo Datastore. É possível usar o emulador com todas as bibliotecas de cliente do modo Datastore. Use o emulador apenas para testes locais.
Usar o gcloud emulators firestore
com --database-mode=datastore-mode
para testar o comportamento do Firestore no modo Datastore.
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:
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 --database-mode=datastore-mode
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 --database-mode=datastore-mode --host-port=HOST:PORT
Use o atalho do teclado
Control + C
para interromper o emulador.
Conectar-se ao emulador
Para conectar uma biblioteca de cliente e um app ao emulador,
defina a variável de ambiente DATASTORE_EMULATOR_HOST
. Quando essa variável
de ambiente é definida, as bibliotecas de cliente se conectam automaticamente ao emulador.
export DATASTORE_EMULATOR_HOST="HOST:PORT"
Importar entidades para o emulador
O recurso de importação do emulador permite carregar entidades de um conjunto de arquivos de exportação da entidade no emulador. Os arquivos de exportação da entidade podem ser provenientes de uma exportação do banco de dados do modo Datastore ou de uma instância do emulador.
É possível importar entidades para o emulador de duas maneiras. A primeira é adicionar a
flag import-data
ao comando de início do emulador. O segundo método é
enviar uma solicitação de importação POST para o emulador. Você pode usar
curl ou uma ferramenta semelhante. Consulte as seguintes
exemplos.
Protocolo
curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \ -H 'Content-Type: application/json' \ -d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
localhost:8080
se o emulador usar uma porta diferente.Sinalização da CLI
gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY
em que:
[PROJECT_ID]
é o ID do projeto;[DATABASE]
é o caminho do banco de dados. Por exemplo, um projeto com banco de dados padrão ficaria assim:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
é o caminho para o arquivooverall_export_metadata
dos seus arquivos de exportação de entidade. Exemplo:{"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}
Exportar entidades no emulador
O recurso de exportação do emulador permite salvar entidades no emulador em um conjunto de arquivos de exportação da entidade. Em seguida, use uma operação de importação para carregar as entidades nos arquivos de exportação da entidade no banco de dados do modo Datastore ou em uma instância do emulador.
É possível exportar entidades do emulador de duas maneiras. A primeira é adicionar
Sinalize export-on-exit
para o comando de inicialização do emulador. O segundo método é
envie uma solicitação de exportação POST
ao emulador. Use
curl ou uma ferramenta semelhante. Consulte os exemplos
a seguir.
Protocolo
curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \ -H 'Content-Type: application/json' \ -d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
localhost:8080
se o emulador usar uma porta diferente.Sinalização da CLI
gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY
em que:
[PROJECT_ID]
é o ID do projeto;[DATABASE_PATH]
é o caminho do banco de dados. Por exemplo, um projeto com banco de dados padrão fica assim:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
especifica o diretório em que o emulador salvará os arquivos de exportação da entidade. Esse diretório não pode conter um conjunto de arquivos de exportação da entidade. Exemplo:{"export_directory":"/home/user/myexports/2024-03-26/"}
Manter dados no emulador
Por padrão, o emulador do Firestore não mantém dados no disco. Para manter os dados do emulador, execute o comando abaixo para usar flags de importação e exportação para carregar e salvar os dados nas instâncias do emulador:
gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY
Redefinir dados do emulador
O emulador do Firestore inclui um endpoint REST para redefinir todos os os dados no emulador. Você pode usar este endpoint para limpar os dados entre os testes sem encerrar o emulador.
Para redefinir todos os dados no emulador, execute uma operação POST
HTTP na
endpoint a seguir, substituindo HOST e PORT pelo
e a porta selecionadas e substituindo PROJECT_ID pelo seu
próprio ID do projeto:
http://HOST:PORT/reset
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 redefinição foi concluída ou falhou.
É possível executar essa operação no shell usando curl
:
$ curl -X POST "http://HOST:PORT/reset"
Qual é a diferença entre o emulador e a produção
O emulador tenta replicar fielmente o comportamento do serviço de produção com algumas limitações notáveis.
Simultaneidade e consistência
O emulador oferece suporte apenas à consistência forte e à simultaneidade pessimista. O emulador não oferece suporte à simultaneidade otimista e à consistência posterior. configurações.
Transações
O emulador não implementa todos os comportamentos de transação visto 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 qualquer válida. Não deixe de testar seu app em um modo Datastore real para determinar os índices 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. Você precisa conhecer limites documentados e que você projete seu app evitá-los proativamente.
A seguir
- Aprenda a trabalhar com entidades, propriedades e chaves.
- Saiba mais sobre consultas.