Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Exportar e importar dados

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

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

Antes de você começar

Antes de poder usar o serviço gerenciado de exportação e importação, você deve concluir as seguintes tarefas:

  1. Ative o faturamento do seu 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 Cloud Firestore . Você não pode 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 Cloud Firestore e Cloud Storage. Se você for o proprietário do projeto, sua conta terá as permissões necessárias. Caso contrário, os seguintes papéis concedem as permissões necessárias para operações de exportação e importação e para acesso ao Cloud Storage:

    • Papéis do Cloud Firestore: Owner , proprietário do Cloud Datastore Owner ou Cloud Datastore Import Export Admin do Cloud Datastore
    • Papéis do Cloud Storage: Owner ou Storage Admin de armazenamento

Permissões de 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 as 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 intervalo do Cloud Storage estiver no mesmo projeto que o banco de dados do Cloud Firestore, a conta de serviço padrão terá acesso ao intervalo por padrão .

Se o bucket do Cloud Storage estiver em outro projeto, você deverá conceder à conta de serviço padrão acesso ao bucket do Cloud Storage.

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

Se você 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 Cloud Firestore. Se você desativou sua conta de serviço do App Engine, poderá reativá-la. Consulte como ativar uma conta de serviço . Se você excluiu sua conta de serviço do App Engine nos últimos 30 dias, você pode restaurá-la. Consulte como recuperar uma conta de serviço .

Configurar o gcloud para seu projeto

Você pode iniciar operações de importação e exportação por meio do Console do Google Cloud Platform 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 em seu banco de dados para um conjunto de arquivos em um bucket do Cloud Storage. Observe que uma exportação não é um instantâneo exato do banco de dados obtido na hora de início da exportação. Uma exportação pode incluir alterações feitas durante a execução da operação.

Exportar todos os documentos

Console do Google Cloud

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

    Vá para a página Importar/Exportar

  2. Clique em Exportar .

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

  4. Abaixo de Choose Destination , insira o nome de um bucket do Cloud Storage ou use o botão Browse 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 de exportação do firestore export para exportar todos os documentos em seu banco de dados, substituindo [BUCKET_NAME] pelo nome do seu bucket do Cloud Storage. Adicione a sinalização --async para evitar que a ferramenta gcloud aguarde a conclusão da operação.

gcloud firestore export gs://[BUCKET_NAME]

Você pode organizar suas exportações adicionando 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 gerenciada criará um com base no carimbo de data/hora atual.

Depois de iniciar uma operação de exportação, fechar o terminal não cancela a operação, consulte cancelar uma operação .

Exportar coleções específicas

Console do Google Cloud

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

    Vá para a página Importar/Exportar

  2. Clique em Exportar .

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

  4. Abaixo de Choose Destination , insira o nome de um bucket do Cloud Storage ou use o botão Browse 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 coleções específicos, use o --collection-ids . A operação exporta apenas os grupos de coleção com os IDs de coleção fornecidos. O grupo de coleção inclui todas as coleções e subcoleções (em qualquer caminho) com o ID de coleção especificado.

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

Importar dados

Depois de exportar arquivos no Cloud Storage, você pode importar documentos desses arquivos de volta para seu projeto ou para outro projeto. Observe os seguintes pontos sobre as 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 IDs de documento. As importações usam os IDs capturados no momento da exportação. À medida que um documento está sendo importado, seu ID é reservado para evitar colisões de ID. Se já existir um documento com o mesmo ID, a importação substituirá o documento existente.

  • Se um documento em seu banco de dados não for afetado por uma importação, ele permanecerá em seu banco de dados após a importação.

  • As operações de importação não acionam o Cloud Functions. Os ouvintes de instantâneo recebem atualizações relacionadas às operações de importação.

  • O nome do arquivo .overall_export_metadata deve corresponder ao nome de sua pasta pai:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/ PARENT_FOLDER_NAME / PARENT_FOLDER_NAME .overall_export_metadata

    Se você mover ou copiar os arquivos de saída de uma exportação, mantenha o mesmo nome de arquivo PARENT_FOLDER_NAME e .overall_export_metadata .

Importar todos os documentos de uma exportação

Console do Google Cloud

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

    Vá para a página Importar/Exportar

  2. Clique em Importar .

  3. No campo Nome do arquivo, insira o nome do arquivo de um arquivo .overall_export_metadata de uma operação de exportação concluída. Você pode usar o botão Procurar para ajudá-lo 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]/

onde [BUCKET_NAME] e [EXPORT_PREFIX] apontam para o local dos seus arquivos de exportação. Por exemplo:

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

Você pode confirmar a localização dos seus arquivos de exportação no navegador do Cloud Storage no Console do Google Cloud Platform:

Abra o navegador do Cloud Storage

Depois de iniciar uma operação de importação, fechar o terminal não cancela a operação, consulte cancelar uma operação .

Importar coleções específicas

Console do Google Cloud

Você não pode selecionar coleções específicas no console. Use gcloud em vez disso.

gcloud

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

Apenas uma exportação de grupos de coleções específicos dá suporte à importação de grupos de coleções específicos. Você não pode 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],[SUBCOLLECTION_ID_1]

Gerenciamento das operações de exportação e importação

Depois de iniciar uma operação de exportação ou importação, o Cloud Firestore atribui um nome exclusivo à operação. Você pode usar o nome da operação para excluir, cancelar ou verificar o status da 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, você pode 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

Você pode ver uma lista de operações recentes de exportação e importação na página Importar/Exportar do Cloud Firestore do Console do Google Cloud Platform.

Vá para a página Importar/Exportar

gcloud

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

gcloud firestore operations list

Verifique o status da operação

Console do Google Cloud

Você pode visualizar o status de uma operação de exportação ou importação recente na página Importar/Exportar do Cloud Firestore do Console do Google Cloud Platform.

Vá para a página Importar/Exportar

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

Estime 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 em número de bytes e número de entidades:

  • workEstimated mostra o número total estimado de bytes e documentos que uma operação processará. O Cloud Firestore pode omitir essa métrica se não puder fazer uma estimativa.

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

Divida workCompleted por workEstimated para obter uma estimativa aproximada do progresso. Essa estimativa pode ser imprecisa, pois depende da coleta de estatísticas atrasada.

Cancelar uma operação

Console do Google Cloud

Você pode cancelar uma operação de exportação ou importação em execução na página Importar/Exportar do Cloud Firestore do Console do Google Cloud Platform.

Vá para a página Importar/Exportar

Na tabela Importações e exportações recentes , as operações atualmente em execução incluem um 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 depois para Cancelado quando a operação é interrompida completamente.

gcloud

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

gcloud firestore operations cancel [OPERATION_NAME]

Cancelar uma operação em execução não desfaz a operação. Uma operação de exportação cancelada deixará os documentos já exportados no Cloud Storage, e uma operação de importação cancelada deixará as atualizações já feitas em seu banco de dados. Você não pode importar uma exportação parcialmente concluída.

Excluir uma operação

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

gcloud firestore operations delete [OPERATION_NAME]

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

Você precisa ativar o faturamento do seu projeto do Google Cloud antes de usar o serviço gerenciado de exportação e importação. As operações de exportação e importação são cobradas pelas leituras e gravações de documentos de acordo com as taxas listadas nos preços do Cloud Firestore .

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

Visualizando 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 , você pode usar este 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.

Exportar para o BigQuery

Você pode carregar dados de uma exportação do Cloud Firestore para o BigQuery, mas somente se tiver especificado um filtro collection-ids . Consulte Como carregar dados das exportações do Cloud Firestore .

Limite de colunas do BigQuery

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

Se o esquema do BigQuery de um grupo de coleção ultrapassar 10.000 colunas, a operação de exportação do Cloud Firestore tentará ficar abaixo do limite de colunas tratando os campos do mapa como bytes. Se essa conversão reduzir o número de colunas abaixo de 10.000, você poderá carregar os dados no BigQuery, mas não poderá consultar os subcampos nos campos do mapa. Se o número de colunas ainda exceder 10.000, a operação de exportação não gerará um esquema do BigQuery para o grupo de coleta e você não poderá carregar os dados dele no BigQuery.

Exporte arquivos de formato e metadados

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

Arquivos de metadados

Uma operação de exportação cria um arquivo de metadados para cada grupo de coleta especificado. 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 você pode decodificá-los com o compilador de protocolo protoc . Por exemplo, você pode 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

Migração do agente de serviço

Agora você pode usar um agente de serviço do Cloud Firestore para autorizar operações de importação e exportação em vez da conta de serviço do App Engine. O agente de serviço e a conta de serviço usam as seguintes convenções de nomenclatura:

Agente de serviço do Cloud Firestore
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
Conta de serviço do App Engine
project_id @appspot.gserviceaccount.com

O agente de serviço do Cloud Firestore é preferível porque é específico do Cloud Firestore. A conta de serviço do App Engine é compartilhada por mais de um serviço.

Ver conta de autorização

Você pode ver qual conta suas operações de importação e exportação usam para autorizar solicitações na página Importar/Exportar no Console do Google Cloud Platform. Você também pode ver se seu banco de dados já usa o agente de serviço do Cloud Firestore.

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

    Vá para Importar/Exportar

  2. Visualize a conta de autorização ao lado dos trabalhos de importação/exportação executados como rótulo.

Se seu projeto não usa o agente de serviço do Cloud Firestore, você pode migrar para o agente de serviço do Cloud Firestore usando uma destas técnicas:

A primeira dessas técnicas é preferível porque localiza o escopo do efeito em um único projeto do Cloud Firestore. A segunda técnica não é a preferida porque não migra as permissões existentes do bucket do Cloud Storage. No entanto, oferece conformidade de segurança no nível da organização.

Migre verificando e atualizando as permissões de bucket do Cloud Storage

O processo de migração tem duas etapas:

  1. Atualize as permissões do bucket do Cloud Storage. Consulte a seção a seguir para obter detalhes.
  2. Confirme a migração para o agente de serviço do Cloud Firestore.

Permissões de bucket do agente de serviço

Para qualquer operação de exportação ou importação que use um bucket do Cloud Storage em outro projeto, você deve conceder ao agente de serviço do Cloud Firestore permissões para esse bucket. Por exemplo, as operações que movem dados para outro projeto precisam acessar um bucket nesse outro projeto. Caso contrário, essas operações falharão após a migração para o agente de serviço do Cloud Firestore.

Os fluxos de trabalho de importação e exportação que permanecem no mesmo projeto não exigem alterações nas permissões. O agente de serviço do Cloud Firestore pode acessar buckets no mesmo projeto por padrão.

Atualize as permissões dos buckets do Cloud Storage de outros projetos para dar acesso ao agente de serviço service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Conceda ao agente de serviço o papel de agente de serviço do Firestore Service Agent .

O papel Firestore Service Agent concede permissões de leitura e gravação para um bucket do Cloud Storage. Se você precisar conceder apenas permissões de leitura ou apenas de gravação, use uma função personalizada .

O processo de migração descrito na seção a seguir ajuda a identificar buckets do Cloud Storage que podem exigir atualizações de permissão.

Migrar um projeto para o Firestore Service Agent

Conclua as etapas a seguir para migrar da conta de serviço do App Engine para o agente de serviço do Cloud Firestore. Depois de concluída, a migração não pode ser desfeita.

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

    Vá para Importar/Exportar

  2. Caso seu projeto ainda não tenha migrado para o agente de serviço do Cloud Firestore, você verá um banner descrevendo a migração e um botão Verificar status do bucket. A próxima etapa ajuda a identificar e corrigir possíveis erros de permissão.

    Clique em Verificar status do bucket .

    Um menu é exibido com a opção de concluir sua migração e uma lista de buckets do Cloud Storage. Pode levar alguns minutos para a lista terminar de carregar.

    Esta lista inclui buckets que foram usados ​​recentemente em operações de importação e exportação, mas atualmente não concedem permissões de leitura e gravação ao agente de serviço do Cloud Firestore.

  3. Anote o nome principal do agente de serviço do Cloud Firestore do seu projeto. O nome do agente de serviço aparece em Agente de serviço para dar acesso ao rótulo.
  4. Para qualquer bucket na lista que você usará para futuras operações de importação ou exportação, conclua as etapas a seguir:

    1. Na linha da tabela deste bucket, clique em Fix . Isso abre a página de permissões desse bucket em uma nova guia.

    2. Clique em Adicionar .
    3. No campo New principaiss , insira o nome do seu agente de serviço do Cloud Firestore.
    4. No campo Selecionar uma função , selecione Agentes de serviço > Agente de serviço do Firestore .
    5. Clique em Salvar .
    6. Retorne à guia com a página Importar/Exportar do Cloud Firestore.
    7. Repita essas etapas para outros buckets na lista. Certifique-se de visualizar todas as páginas da lista.
  5. Clique em Migrar para Firestore Service Agent . Se você ainda tiver buckets com falhas nas verificações de permissão, será necessário confirmar sua migração clicando em Migrar .

    Um alerta informa quando sua migração é concluída. A migração não pode ser desfeita.

Ver o status da migração

  1. Para verificar o status de migração do seu projeto, acesse a página Importar/Exportar no Console do Google Cloud Platform:

    Vá para Importar/Exportar

  2. Procure o principal ao lado dos trabalhos de importação/exportação executados como rótulo.

    Se o principal for service- project_number @gcp-sa-firestore.iam.gserviceaccount.com , seu projeto já migrou para o agente de serviço do Cloud Firestore. A migração não pode ser desfeita.

    Se o projeto não tiver sido migrado, um banner aparecerá na parte superior da página com um botão Verificar status do bucket. Consulte Migrar para o agente de serviço do Firestore para concluir a migração.

Adicionar uma restrição de política em toda a organização

  • Defina a seguinte restrição na política da sua organização:

    Exigir Firestore Service Agent para importação/exportação ( firestore.requireP4SAforImportExport ).

    Essa restrição exige que as operações de importação e exportação usem o agente de serviço do Cloud Firestore para autorizar solicitações. Para definir essa restrição, consulte Criando e gerenciando políticas da organização .

A aplicação dessa restrição de política organizacional não concede automaticamente as permissões de bucket apropriadas do Cloud Storage para o agente de serviço do Cloud Firestore.

Se a restrição criar erros de permissão para qualquer fluxo de trabalho de importação ou exportação, você poderá desativá-la para voltar a usar a conta de serviço padrão. Depois de verificar e atualizar as permissões do bucket do Cloud Storage , você poderá ativar a restrição novamente.