Exportar e importar dados

Você pode usar o serviço gerenciado de exportação e importação do Cloud Firestore para se recuperar de exclusão acidental de dados e exportar dados para processamento offline. 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 Cloud Firestore podem ser importados para outro banco de dados 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 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 terá as permissões necessárias. Caso contrário, os seguintes papéis concederão 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 , Cloud Datastore Owner ou Cloud Datastore Import Export Admin

   • Funções do Cloud Storage: Owner ou Storage Admin

Permissões do agente de serviço

As operações de exportação e importação usam um agente de serviço do Cloud Firestore para autorizar as operações do Cloud Storage. O agente de serviço do Cloud Firestore usa a seguinte convenção de nomenclatura:

Agente de serviço do Cloud Firestore

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Para saber mais sobre agentes de serviço, consulte Agentes de serviço .

O agente de serviço do Cloud Firestore 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 Cloud Firestore, o agente de serviço do Cloud Firestore poderá acessar o bucket por padrão .

Se o bucket do Cloud Storage estiver em outro projeto, você deverá conceder ao agente de serviço do Cloud Firestore acesso ao bucket do Cloud Storage.

Atribuir funções ao agente de serviço

Você pode usar a ferramenta de linha de comando gsutil para atribuir uma das funções abaixo. Por exemplo, para atribuir a função Administrador de armazenamento ao agente de serviço do Cloud Firestore, execute o seguinte:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Substitua PROJECT_NUMBER pelo número do seu projeto, que é usado para nomear seu agente de serviço do Cloud Firestore. Para visualizar o nome do agente de serviço, consulte Visualizar nome do agente de serviço .

Como alternativa, você pode atribuir essa função usando o Console do GCP .

Ver nome do agente de serviço

Você pode visualizar a conta que suas operações de importação e exportação usam para autorizar solicitações na página Importação/Exportação no Console do Google Cloud Platform. Você também pode ver se seu banco de dados usa o agente de serviço do Cloud Firestore ou a conta de serviço legada do App Engine.

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

O agente de serviço precisa da função Storage Admin para que o bucket do Cloud Storage seja usado na operação de exportação ou importação.

Configure 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:

• Acesse gcloud no console do Google Cloud Platform usando o Cloud Shell .

  Iniciar o Cloud Shell

  Verifique se gcloud está configurado para o projeto correto:

  gcloud config set project [PROJECT_ID]
  

• Instale e inicialize o SDK do Google Cloud.

Exportar dados

Uma operação de exportação copia documentos do 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 no horário 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

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Exportar coleções específicas

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

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Exportar de um carimbo de data/hora PITR

Você pode exportar seu banco de dados para o Cloud Storage a partir de dados PITR usando o comando gcloud firestore export . Você pode exportar dados PITR em que o carimbo de data/hora é um carimbo de data/hora de um minuto inteiro nos últimos sete dias, mas não antes do earliestVersionTime . Se os dados não existirem mais no carimbo de data/hora especificado, a operação de exportação falhará.

A operação de exportação PITR oferece suporte a todos os filtros, incluindo a exportação de todos os documentos e a exportação de coleções específicas.

1. Exporte o banco de dados, especificando o parâmetro snapshot-time para o carimbo de data/hora de recuperação desejado.

   gcloud

   Execute o comando a seguir para exportar o banco de dados para seu bucket.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Onde,

   • PITR_TIMESTAMP - um carimbo de data/hora PITR na granularidade de minuto, por exemplo, 2023-05-26T10:20:00.00Z .

   Observe os seguintes pontos antes de exportar dados PITR:

   • Especifique o carimbo de data/hora no formato RFC 3339 . Por exemplo, 2020-09-01T23:59:30.234233Z .
   • Certifique-se de que o carimbo de data/hora especificado seja um carimbo de data/hora de um minuto inteiro dos últimos sete dias, mas não anterior ao earliestVersionTime . Se os dados não existirem mais no carimbo de data/hora especificado, um erro será gerado.
   • Você não será cobrado por uma falha na exportação de PITR.

Importar dados

Depois de exportar os arquivos no Cloud Storage, você poderá importar os documentos desses arquivos de volta para o seu projeto ou para outro projeto. Observe os seguintes pontos sobre operações de importação:

• Ao importar 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 documentos. As importações usam os IDs capturados no momento da exportação. À medida que um documento é 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 no seu banco de dados não for afetado por uma importação, ele permanecerá no seu banco de dados após a importação.

• As operações de importação não acionam o Cloud Functions. Os ouvintes de snapshot 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 nomes dos arquivos PARENT_FOLDER_NAME e .overall_export_metadata iguais.

Importe todos os documentos de uma exportação

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Importar coleções específicas

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

Importar uma exportação PITR

Use as etapas em Importar todos os documentos para importar seu banco de dados exportado. Se já existir algum documento em seu banco de dados, ele será sobrescrito.

Gerenciando 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 describe , cancel e delete .

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

gcloud firestore operations list

Verifique o status da operaçã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 poderá 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 pelo workEstimated para obter uma estimativa aproximada do progresso. Esta estimativa pode ser imprecisa, porque depende do atraso na recolha de estatísticas.

Cancelar uma operação

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 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. 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

É necessário 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 . As operações de exportação incorrem em uma operação de leitura por documento exportado. As operações de importação incorrem em uma operação de gravação por documento importado.

Os arquivos de saída armazenados no Cloud Storage são contabilizados nos custos de armazenamento de dados do Cloud Storage .

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 só acionarão alertas de orçamento do Google Cloud após 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 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:

Exportar para o BigQuery

Você poderá carregar dados de uma exportação do Cloud Firestore para o BigQuery, mas somente se tiver especificado um filtro collection-ids . Consulte Carregamento de 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 coleções. Neste esquema, cada nome de campo exclusivo dentro de um grupo de coleções 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 deixar 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 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 normalmente 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ções que os arquivos de exportação contêm:

protoc --decode_raw < export0.export_metadata

Migração de agente de serviço

O Cloud Firestore usa um agente de serviço do Cloud Firestore para autorizar operações de importação e exportação em vez de usar a 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

Anteriormente, o Cloud Firestore usava a conta de serviço padrão do App Engine em vez do agente de serviço do Cloud Firestore. Se seu banco de dados ainda usa a conta de serviço do App Engine para importar ou exportar dados, recomendamos que você siga as instruções nesta seção para migrar para o agente de serviço do Cloud Firestore.

Conta de serviço do App Engine

PROJECT_ID @appspot.gserviceaccount.com

O agente de serviço 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 Importação/Exportação no Console do Google Cloud Platform. Você também pode visualizar se seu banco de dados já utiliza o agente de serviço Cloud Firestore.

1. No console do Google Cloud Platform, acesse a página Bancos de dados .

   Vá para bancos de dados

2. Selecione o banco de dados necessário na lista de bancos de dados.

3. No menu de navegação, clique em Importar/Exportar .

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

Se o 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:

• Migre um projeto verificando e atualizando as permissões do bucket do Cloud Storage (recomendado) .
• Adicione uma restrição de política para toda a organização que afete todos os projetos da organização.

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 do 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 permissões ao agente de serviço do Cloud Firestore 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 para 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 permissões somente 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 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 poderá ser desfeita.

1. No console do Google Cloud Platform, acesse a página Bancos de dados .

   Vá para bancos de dados

2. Selecione o banco de dados necessário na lista de bancos de dados.

3. No menu de navegação, clique em Importar/Exportar .

4. Se o seu projeto ainda não tiver 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 intervalo .

   Um menu será exibido 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 que atualmente não concedem permissões de leitura e gravação ao agente de serviço do Cloud Firestore.

5. Anote o nome principal do agente de serviço 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.

6. Para qualquer bucket da lista que você usará em futuras operações de importação ou exportação, conclua as seguintes etapas:

   1. Na linha da tabela deste bucket, 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 Selecione 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 Importação/Exportação do Cloud Firestore.
   7. Repita essas etapas para outros buckets da lista. Certifique-se de visualizar todas as páginas da lista.

7. Clique em Migrar para o agente de serviço do Firestore . 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 a migração for concluída. A migração não pode ser desfeita.

Ver o status da migração

Para verificar o status de migração do seu projeto:

1. No console do Google Cloud Platform, acesse a página Bancos de dados .

   Vá para bancos de dados

2. Selecione o banco de dados necessário na lista de bancos de dados.

3. No menu de navegação, clique em Importar/Exportar .

4. Procure o principal próximo aos trabalhos de importação/exportação executados como rótulo.

   Se o principal 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.

Adicione uma restrição de política para 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 apropriadas de 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 bucket do Cloud Storage , você poderá ativar a restrição novamente.