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 de exportação e importação gerenciado do Cloud Firestore para se recuperar da exclusão acidental de dados 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 as 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 de importação e exportação gerenciado do Cloud Firestore está disponível por meio da ferramenta de linha de comando gcloud e da API do 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 para 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. Certifique-se de que sua conta tenha as permissões necessárias para Cloud Firestore e Cloud Storage. Se você for o proprietário do projeto, sua conta possui as permissões necessárias. Caso contrário, as seguintes funções concedem as permissões necessárias para operações de exportação e importação e para acesso ao Cloud Storage:

    • Funções do Cloud Firestore: Owner , Proprietário do Cloud Datastore Owner ou Cloud Datastore Import Export Admin do Cloud Datastore
    • Funções do Cloud Storage: Owner ou Storage Admin do 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 seu bucket do Cloud Storage estiver no mesmo projeto que seu banco de dados do Cloud 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, você deverá conceder à conta de serviço padrão acesso ao bucket do Cloud Storage.

A conta de serviço precisa da função Storage Admin para que o bucket do Cloud Storage seja 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 seu banco de dados do Cloud Firestore. Se você desativou sua conta de serviço do App Engine, pode 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, pode restaurá-la, consulte como recuperar uma conta de serviço .

Configure o gcloud para seu projeto

Você pode iniciar as operações de importação e exportação por meio do Google Cloud Platform Console 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 de importação/exportação 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 todo o banco de dados .

  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 incluirá uma entrada na 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 em seu banco de dados, substituindo [BUCKET_NAME] pelo nome do seu intervalo do Cloud Storage. Adicione o sinalizador --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 depósito, 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 registro de data e 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 de importação/exportação 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ções . Use o menu suspenso para selecionar um ou mais grupos de coleta.

  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 incluirá uma entrada na 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 coleta com os IDs de coleta fornecidos. O grupo de coleções 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âneos 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 os mesmos nomes 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 de importação/exportação 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 incluirá uma entrada na 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 de seus arquivos de exportação no navegador do Cloud Storage no Google Cloud Platform Console:

Abra o navegador de armazenamento em nuvem

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. Em vez disso, use gcloud .

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 coleta com os IDs de coleta fornecidos. O grupo de coleções 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 suporta uma 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]

Gestão 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 à operação um nome exclusivo. 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 deixar de fora 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 visualizar uma lista de operações recentes de exportação e importação na página Cloud Firestore Import/Export do Google Cloud Platform Console.

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 concluídas recentemente:

gcloud firestore operations list

Verifique o status da operação

Console do Google Cloud

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

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 execução longa 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, o que pode ser maior que o valor de workEstimated .

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

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 Cloud Firestore Import/Export do Google Cloud Platform Console.

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 de Cancelamento e depois para Cancelado quando a operação para 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. Não é possível 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ê deve ativar o faturamento para 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.

Visualização de 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-firestore managed 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 Carregando dados de 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 dentro de um grupo de coleta torna-se 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 Cloud Firestore tentará permanecer abaixo do limite de colunas tratando os campos do mapa como bytes. Se essa conversão reduzir o número de colunas para menos 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 seus dados no BigQuery.

Exportar 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 coleta 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 Google Cloud Platform Console. Você também pode ver se seu banco de dados já usa o agente de serviço Cloud Firestore.

  1. Acesse a página de importação/exportação do Cloud Firestore no Console do Google Cloud Platform.

    Ir para Importar/Exportar

  2. Exiba 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 Cloud Firestore, você pode migrar para o agente de serviço 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 é 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 intervalo 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 conceder acesso ao agente de serviço service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Conceda ao agente de serviço a função Firestore Service Agent .

A função 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 somente gravação, use uma função personalizada .

O processo de migração descrito na seção a seguir ajuda a identificar os 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 de importação/exportação do Cloud Firestore no Console do Google Cloud Platform.

    Ir para Importar/Exportar

  2. Se seu projeto ainda não migrou para o agente de serviço do Cloud Firestore, você verá um banner descrevendo a migração e um botão Check Bucket Status . A próxima etapa ajuda a identificar e corrigir possíveis erros de permissão.

    Clique em Verificar status do bucket .

    Um menu aparece com a opção de concluir a migração e uma lista de buckets do Cloud Storage. Pode levar alguns minutos para que a lista termine 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 sob o 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 seguintes etapas:

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

    2. Clique em Adicionar .
    3. No campo Novos principais , 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 Cloud Firestore Import/Export.
    7. Repita essas etapas para outros depósitos 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 verificações de permissão com falha, será necessário confirmar sua migração clicando em Migrar .

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

Ver status da migração

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

    Ir 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, aparecerá um banner na parte superior da página com um botão Check Bucket Status . Consulte Migrar para o agente de serviço do Firestore para concluir a migração.

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

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

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

    Essa restrição requer operações de importação e exportação para usar 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 apropriadas do bucket 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 intervalo do Cloud Storage , você pode ativar a restrição novamente.