Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como exportar e importar dados

É possível usar o serviço gerenciado de importação e exportação do Firestore para recuperar a exclusão acidental de dados e os exportar para o processamento off-line. É possível exportar todos os documentos ou apenas coleções específicas. Da mesma forma, é possível importar todos os dados de uma exportação ou apenas coleções específicas. Os dados exportados de um banco de dados do Firestore podem ser importados para outro banco de dados do Firestore. É possível também carregar exportações do Firestore no BigQuery.

Veja nesta página como exportar e importar documentos do Firestore usando o serviço gerenciado de importação e exportação e o Cloud Storage. O serviço gerenciado de importação e exportação do Firestore está disponível por meio da ferramenta de linha de comando gcloud e da Firestore API (REST, RPC).

Antes de começar

Antes de usar o serviço gerenciado de importação e exportação, é necessário concluir as tarefas a seguir:

  1. Ative o faturamento para o projeto do Google Cloud. Somente projetos do Google Cloud com faturamento ativado podem usar a funcionalidade de exportação e importação.
  2. Crie um bucket do Cloud Storage para seu projeto em um local próximo ao local do banco de dados do Firestore. Não é possível usar um bucket de pagamentos do solicitante para operações de exportação e importação.
  3. Verifique se sua conta tem as permissões necessárias para o Firestore e o Cloud Storage. Se você for o proprietário do projeto, sua conta já terá as permissões necessárias. Caso contrário, as funções a seguir concederão as permissões necessárias para operações de exportação e importação, além do acesso ao Cloud Storage:

    • Papéis do Firestore: (em inglês) Owner, Cloud Datastore Owner ou Cloud Datastore Import Export Admin
    • Papéis do Cloud Storage: Owner ou Storage Admin

Permissões da conta de serviço padrão

Cada projeto do Google Cloud cria automaticamente uma conta de serviço padrão chamada PROJECT_ID@appspot.gserviceaccount.com. As operações de exportação e importação usam essa conta de serviço para autorizar operações do Cloud Storage.

A conta de serviço padrão do seu projeto requer acesso ao bucket do Cloud Storage usado em uma operação de exportação ou importação. Se o bucket do Cloud Storage estiver no mesmo projeto que o banco de dados do Firestore, a conta de serviço padrão terá acesso ao bucket por padrão.

Se o bucket do Cloud Storage estiver em outro projeto, será necessário permitir que a conta de serviço padrão acesse o bucket.

A conta de serviço precisa do papel Storage Admin para que o bucket do Cloud Storage seja usado para a operação de exportação ou importação.

Ao desativar ou excluir sua conta de serviço padrão do App Engine, seu aplicativo do App Engine perderá o acesso ao banco de dados do Firestore. Se você desativou sua conta de serviço do App Engine, poderá reativá-la. Consulte este link para ver como fazer isso. Se você excluiu sua conta de serviço do App Engine nos últimos 30 dias, poderá restaurá-la. Consulte Como cancelar a exclusão de uma conta de serviço.

Configurar gcloud para seu projeto

É possível iniciar operações de importação e exportação por meio do Console do Google Cloud ou da ferramenta de linha de comando gcloud. Para usar gcloud, configure a ferramenta de linha de comando e conecte-se ao seu projeto de uma das seguintes maneiras:

Exportar dados

Uma operação de exportação copia documentos no seu banco de dados para um conjunto de arquivos em um bucket do Cloud Storage. É importante ressaltar que uma exportação não é um snapshot exato do banco de dados registrado no horário de início da exportação. Uma exportação pode incluir alterações feitas enquanto a operação estava em execução.

Exportar todos os documentos

Console do Google Cloud

  1. Acesse a página Importar/exportar do Firestore no Console do Google Cloud.

    Acessar a página "Importar/Exportar"

  2. Clique em Exportar.

  3. Clique na opção Exportar todo o banco de dados.

  4. Abaixo de Escolher destino, insira o nome de um bucket do Cloud Storage ou use o botão Procurar para selecionar um bucket.

  5. Clique em Exportar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página exibe uma mensagem de erro.

gcloud

Use o comando firestore export para exportar todos os documentos do banco de dados, substituindo [BUCKET_NAME] pelo nome do bucket do Cloud Storage. Adicione a sinalização --async para evitar que a ferramenta gcloud fique aguardando a conclusão da operação.

gcloud firestore export gs://[BUCKET_NAME]

Para organizar suas exportações, adicione um prefixo de arquivo após o nome do bucket, por exemplo, BUCKET_NAME/my-exports-folder/export-name. Se você não fornecer um prefixo de arquivo, o serviço de exportação gerenciado criará um com base no carimbo de data e hora atual.

Após iniciar uma operação de exportação, o fechamento do terminal não cancelará a operação. Saiba como cancelar uma operação.

Exportar coleções específicas

Console do Google Cloud

  1. Acesse a página Importar/exportar do Firestore no Console do Google Cloud.

    Acessar a página "Importar/Exportar"

  2. Clique em Exportar.

  3. Clique na opção Exportar um ou mais grupos de coleções. Use o menu suspenso para selecionar um ou mais grupos de coleções.

  4. Abaixo de Escolher destino, insira o nome de um bucket do Cloud Storage ou use o botão Procurar para selecionar um bucket.

  5. Clique em Exportar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página exibe uma mensagem de erro.

gcloud

Para exportar grupos de coletas específicos, use a sinalização --collection-ids. A operação exporta apenas os grupos de coleções com os IDs de conjuntos fornecidos. O grupo de coleções inclui todas as coleções e subcoleções (em qualquer caminho) com o ID especificado.

gcloud firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

Importar dados

Com os arquivos de exportação no Cloud Storage, é possível importar documentos nesses arquivos de volta para seu projeto ou para outro projeto. Veja as informações a seguir sobre operações de importação:

  • Quando você importa dados, os índices necessários são atualizados usando as definições de índice atuais do seu banco de dados. Uma exportação não contém definições de índice.

  • As importações não atribuem novos códigos de documentos. Elas usam os códigos capturados no momento da exportação. O código de um documento é reservado durante o processo de importação de um documento para evitar colisões de código. Se já existir um documento com o mesmo código, a importação substituirá o documento existente.

  • Se uma entidade em seu banco de dados não for afetada por uma importação, ela permanecerá no banco de dados após esse processo.

  • As operações de importação não acionam o Cloud Functions. Os listeners de snapshots recebem atualizações relacionadas às operações de importação.

Importar todos os documentos de uma exportação

Console do Google Cloud

  1. Acesse a página Importar/exportar do Firestore no Console do Google Cloud.

    Acessar a página "Importar/Exportar"

  2. Clique em Importar.

  3. No campo Nome do arquivo, insira o nome do arquivo .overall_export_metadata de uma operação de exportação concluída. Use o botão Procurar para ajudar a selecionar o arquivo.

  4. Clique em Importar.

O console retorna à página Importar/Exportar. Se a operação for iniciada com êxito, a página adicionará uma entrada à página de importações e exportações recentes. Em caso de falha, a página exibe uma mensagem de erro.

gcloud

Use o comando firestore import para importar documentos de uma operação de exportação anterior.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

em que [BUCKET_NAME] e [EXPORT_PREFIX] indicam o local dos arquivos de exportação. Exemplo:

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

É possível confirmar o local de seus arquivos de exportação no navegador do Cloud Storage, no Console do Google Cloud:

Abra o navegador do Cloud Storage

Após iniciar uma operação de importação, o fechamento do terminal não cancelará a operação. Saiba como cancelar uma operação.

Importar coleções específicas

Console do Google Cloud

Não é possível selecionar coleções específicas no console. Use gcloud.

gcloud

Para importar grupos de coletas específicos de um conjunto de arquivos de exportação, use a sinalização --collection-ids. A operação importa somente os grupos de coleções com os IDs fornecidos. O grupo de coleções inclui todas as coleções e subcoleções (em qualquer caminho) com o ID especificado.

Somente uma exportação de grupos de coleções específicas é compatível com a importação desses grupos. Não é possível importar coleções específicas de uma exportação de todos os documentos.

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

Como gerenciar operações de exportação e importação

Após iniciar uma operação de exportação ou importação, o Firestore atribui um nome exclusivo à operação. Use esse nome para excluir, cancelar ou verificar a operação.

Os nomes das operações são prefixados com projects/[PROJECT_ID]/databases/(default)/operations/, por exemplo:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

No entanto, é possível omitir o prefixo ao especificar um nome de operação para os comandos describe, cancel e delete.

Listar todas as operações de exportação e importação

Console do Google Cloud

É possível visualizar uma lista de operações recentes de exportação e importação na página Importar/Exportar do Firestore do Console do Google Cloud.

Acessar a página "Importar/Exportar"

gcloud

Use o comando operations list para ver todas as operações de exportação e importação em execução e as que foram concluídas recentemente:

gcloud firestore operations list

Verificar o status da operação

Console do Google Cloud

É possível visualizar o status de uma operação de exportação ou importação recente na página Importar/Exportar do Firestore do Console do Google Cloud.

Acessar a página "Importar/Exportar"

gcloud

Use o comando operations describe para mostrar o status de uma operação de exportação ou importação.

gcloud firestore operations describe [OPERATION_NAME]

Estimar o tempo de conclusão

Uma solicitação para o status de uma operação de longa duração retorna as métricas workEstimated e workCompleted. Cada uma dessas métricas é retornada no número de bytes e no número de entidades:

  • workEstimated mostra o número total estimado de bytes e documentos que uma operação processará.

  • workCompleted mostra o número de bytes e documentos processados até o momento. Após a conclusão da operação, o valor mostrará o número total de bytes e documentos que foram realmente processados, o que pode ser maior do que o valor de workEstimated.

Divida workCompleted por workEstimated para ter uma estimativa aproximada do andamento. A estimativa pode ser imprecisa, porque ela depende da coleção de estatísticas em atraso.

Cancelar uma operação

Console do Google Cloud

É possível cancelar uma operação de exportação ou importação em execução na página Importar/Exportar do Firestore no Console do Google Cloud.

Acessar a página "Importar/Exportar"

Na tabela Importações e exportações recentes, as operações em execução incluem o botão Cancelar na coluna Concluído. Clique no botão Cancelar para interromper a operação. O botão muda para uma mensagem Cancelando e para Cancelado quando a operação é completamente interrompida.

gcloud

Use o comando operations cancel para interromper uma operação em andamento:

gcloud firestore operations cancel [OPERATION_NAME]

Se você cancelar uma operação em execução, ela não será desfeita. Uma operação de exportação cancelada deixará os documentos já exportados no Cloud Storage, e uma operação de importação cancelada manterá as atualizações já feitas no seu banco de dados. Não é possível importar uma exportação parcialmente concluída.

Excluir uma operação

Use o comando gcloud firestore operations delete para remover uma operação da lista de operações recentes. Esse comando não excluirá arquivos de exportação do Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Faturamento e preços para operações de exportação e importação

Você precisa ativar o faturamento para o projeto do Google Cloud antes de usar o serviço gerenciado de exportação e importação. Essas operações são cobradas por leituras e gravações de documentos de acordo com as taxas listadas na página Preços do Firestore.

Os custos das operações de exportação e importação não contam para seu limite de gastos. Essas operações não vão acionar os alertas de orçamento do Google Cloud até serem concluídas. Da mesma forma, as leituras e gravações executadas durante uma operação de exportação ou importação são aplicadas na sua cota diária apenas após a conclusão. As operações de exportação e importação não afetarão o uso mostrado na seção de uso do console.

Como visualizar os custos de exportação e importação

As operações de exportação e importação aplicam o rótulo goog-firestoremanaged:exportimport às operações faturadas. Na página de relatórios do Cloud Billing, é possível usar esse rótulo para visualizar os custos relacionados às operações de importação e exportação:

Acesse o rótulo goog-firestoremanaged no menu de filtros.

Registros de auditoria

O Firestore grava registros de auditoria de atividade do administrador para os registros de auditoria do Cloud. Os registros de auditoria de atividade do administrador incluem operações de exportação, operações de importação e operações de indexação. Para ver os registros de auditoria de atividade do administrador do seu banco de dados do Firestore, consulte Como visualizar registros de auditoria.

Os registros de auditoria de atividade do administrador do Firestore aparecem nos tipos de recurso Cloud Datastore Database e Cloud Datastore Index. Embora os tipos de recursos usem o nome Cloud Datastore, as entradas de registro individuais contêm um identificador do Firestore. O Firestore registra as seguintes operações:

Categoria de registro de auditoria Operações do Firestore
Atividade do administrador FirestoreAdmin.CreateIndex
FirestoreAdmin.DeleteIndex
FirestoreAdmin.ExportDocuments
FirestoreAdmin.GetField
FirestoreAdmin.GetIndex
FirestoreAdmin.ImportDocuments
FirestoreAdmin.ListFields
FirestoreAdmin.ListIndexes
FirestoreAdmin.UpdateField

Exporte para o BigQuery

É possível carregar os dados de uma exportação do Firestore para o BigQuery, mas somente se você tiver especificado um filtro collection-ids. Consulte Como carregar dados de exportações do Firestore.

Limite de colunas do BigQuery

O BigQuery impõe um limite de 10 mil colunas por tabela. As operações de exportação do Firestore geram um esquema de tabela do BigQuery para cada grupo de coleções. Nesse esquema, cada nome de campo exclusivo dentro de um grupo de coleções se torna uma coluna de esquema.

Se o esquema do BigQuery de um grupo de coleções ultrapassar 10.000 colunas, a operação de exportação do Firestore tentará permanecer abaixo do limite de colunas tratando campos de mapa como bytes. Se essa conversão resultar em menos de 10 mil colunas, será possível carregar os dados no BigQuery, mas não consultar os subcampos dentro dos campos do mapa. Se o número de colunas ainda exceder 10 mil, a operação de exportação não vai gerar um esquema do BigQuery para o grupo de coleções, e não será possível carregar seus dados no BigQuery.

Formato de exportação e arquivos de metadados

A saída de uma exportação gerenciada usa o formato de registro LevelDB.

Arquivos de metadados

Uma operação de exportação cria um arquivo de metadados para cada grupo de coleções especificado por você. Os arquivos de metadados geralmente são denominados ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Os arquivos de metadados são buffers de protocolo e é possível decodificá-los com o compilador de protocolo protoc. Por exemplo, é possível decodificar um arquivo de metadados para determinar os grupos de coleção que os arquivos de exportação contêm:

protoc --decode_raw < export0.export_metadata