Exportar e importar dados

É possível usar o serviço de exportação e importação gerenciado do Cloud Firestore para recuperar a exclusão acidental de informações e exportar dados para 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 Cloud Firestore podem ser importados para outro banco de dados do Cloud Firestore. Também é possível carregar exportações do Cloud Firestore para o BigQuery.

Esta página descreve como exportar e importar documentos do Cloud 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 Cloud Firestore está disponível por meio da ferramenta de linha de comando do gcloud e da API Cloud Firestore (REST, RPC).

Antes de começar

Antes de usar o serviço gerenciado de exportação e importaçã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 seu local do banco de dados do Cloud Firestore. Não é possível usar um intervalo de pagamentos do solicitante para operações de exportação e importação.

3. Verifique se a conta tem as permissões necessárias para o Cloud Firestore e o Cloud Storage. Se você é o proprietário do projeto, isso significa que sua conta tem 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 Cloud Firestore: Owner, Cloud Datastore Owner ou Cloud Datastore Import Export Admin

   • Papéis 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 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 os 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, será necessário conceder ao agente de serviço do Cloud Firestore acesso ao bucket do Cloud Storage.

Atribuir papéis ao agente de serviço

Use a ferramenta de linha de comando gsutil para atribuir um dos papéis abaixo. Por exemplo, para atribuir o papel de Administrador de armazenamento ao agente de serviço do Cloud Firestore, execute este comando:

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 projeto, que é usado para nomear o agente de serviço do Cloud Firestore. Para conferir o nome do agente de serviço, acesse Consultar o nome do agente de serviço.

Também é possível atribuir esse papel usando o console do Google Cloud.

Consultar o nome do agente de serviço

É possível consultar a conta que 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. Também é possível verificar se o banco de dados usa o agente de serviço do Cloud Firestore ou a conta de serviço legada do App Engine.

1. Veja a conta de autorização ao lado do rótulo Importar/exportar jobs executados como.

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

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:

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

  Iniciar o Cloud Shell

  Verifique se a gcloud está configurada 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 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

  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

É possível exportar seu banco de dados para o Cloud Storage de dados PITR usando o comando gcloud firestore export. É possível exportar dados PITR em que o carimbo de data/hora é um minuto inteiro nos últimos sete dias, mas não anterior ao 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 de PITR é compatível com todos os filtros, inclusive 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 o bucket.

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

   Em que,

   • PITR_TIMESTAMP: um carimbo de data/hora da PITR na granularidade de minutos, 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.
   • Verifique se o carimbo de data/hora especificado é de um minuto inteiro nas últimas 7 horas, mas não antes do earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, será gerado um erro.
   • Você não vai receber cobranças por uma falha na exportação da PITR.

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.

• O nome do arquivo .overall_export_metadata precisa ser igual ao nome da pasta mãe:

  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 PARENT_FOLDER_NAME e .overall_export_metadata iguais.

Importar 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 algum documento já existir no seu banco de dados, ele será substituído.

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

Após iniciar uma operação de exportação ou importação, o Cloud 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

gcloud firestore operations list

Verificar o status da operaçã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á. 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 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

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

É necessário ativar o faturamento para o projeto do Google Cloud antes de você usar o serviço de exportação e importação gerenciadas.

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 Cloud Firestore. As operações de exportação geram uma operação de leitura por documento exportado. As operações de importação geram 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 seu limite de gastos. As operações de exportação ou importação não vão acionar os alertas do orçamento do Google Cloud até a conclusão. 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:

Exportar para o BigQuery

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

Limite de colunas do BigQuery

O BigQuery impõe um limite de 10 mil colunas por tabela. As operações de exportação doCloud 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 um esquema do BigQuery do grupo de coleções ultrapassar 10 mil colunas, a operação de exportação do Cloud Firestore tentará permanecer abaixo do limite da coluna ao considerar 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.

Exportar arquivos de formatos e 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 que você especificar. 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. É 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 dos arquivos de exportação:

protoc --decode_raw < export0.export_metadata

Migração do agente de serviço

O Cloud Firestore usa um agente de serviço do Cloud Firestore para autorizar as 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

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 o banco de dados ainda usar a conta de serviço do App Engine para importar ou exportar dados, recomendamos que você siga as instruções desta seção para migrar para o uso do agente de serviço do Cloud Firestore.

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 para o Cloud Firestore. A conta de serviço do App Engine é compartilhada por mais de um serviço.

Visualizar conta de autorização

Você pode verificar 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 verificar se o banco de dados já usa o agente de serviço do Cloud Firestore.

1. No Console do Google Cloud, acesse a página Bancos de Dados.

   Acessar "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. Veja a conta de autorização ao lado do rótulo Importar/exportar jobs executados como.

Se o projeto não usa o agente de serviço do Cloud Firestore, é possível migrar para o agente de serviço do Cloud Firestore usando uma destas técnicas:

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

A primeira dessas técnicas é recomendada porque localiza o escopo do efeito de um único projeto do Cloud Firestore. A segunda técnica não é preferencial porque não migra as permissões dos buckets atuais do Cloud Storage. Porém, ela oferece compliance de segurança no nível da organização.

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

O processo de migração tem duas etapas:

1. Atualizar permissões de buckets do Cloud Storage. Consulte a próxima seção para mais detalhes.
2. Confirme a migração para o agente de serviço do Cloud Firestore.

Permissões do 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, é preciso 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 vão falhar 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 mudanças nas permissões. O agente de serviço do Cloud Firestore pode acessar buckets no mesmo projeto por padrão.

Atualize as permissões de 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 o papel Firestore Service Agent.

O papel Firestore Service Agent concede permissões de leitura e gravação a um bucket do Cloud Storage. Se você precisar conceder apenas permissões de leitura ou de 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 agente de serviço do Firestore

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

1. No Console do Google Cloud, acesse a página Bancos de Dados.

   Acessar "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 projeto ainda não tiver sido migrado para o agente de serviço do Cloud Firestore, serão exibidos um banner descrevendo a migração e um botão Verificar status do bucket. A próxima etapa ajuda você a identificar e corrigir possíveis erros de permissão.

   Clique em Verificar status do bucket.

   Será exibido um menu com a opção para concluir a migração e uma lista de buckets do Cloud Storage. Pode levar alguns minutos para a lista terminar de ser carregada.

   Essa lista inclui buckets 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 do Cloud Firestore do seu projeto. O nome do agente de serviço aparece abaixo do identificador Agente de serviço que receberá acesso.

6. Para qualquer bucket na lista que você usar em operações futuras de importação ou exportação, siga estas etapas:

   1. Na linha da tabela desse bucket, clique em Corrigir. A página de permissões do bucket será aberta em uma nova guia.

   2. Clique em Adicionar.
   3. No campo Novos principais, insira o nome do agente de serviço do Cloud Firestore.
   4. No campo Selecionar um papel, selecione Agentes de serviço > Agente de serviço do Firestore.
   5. Clique em Salvar.
   6. Volte para a guia na página de importação/exportação do Cloud Firestore.
   7. Repita essas etapas para outros buckets na lista. Analise todas as páginas da lista.

7. Clique em Migrar para o agente de serviço do Firestore. Se ainda houver buckets com falha nas verificações de permissão, será necessário confirmar a migração clicando em Migrar.

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

Ver o status da migração

Para verificar o status da migração do projeto:

1. No Console do Google Cloud, acesse a página Bancos de Dados.

   Acessar "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 a principal ao lado do rótulo Importar/exportar jobs executados como.

   Se a principal for service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, seu projeto já migrou para o agente de serviço do Cloud Firestore. Não é possível desfazer a migração.

   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 restrição a seguir na política da organização:

  Exigir o agente de serviço do Firestore 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 Como criar e gerenciar políticas da organização.

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

Se a restrição criar erros de permissão para os fluxos de trabalho de importação ou exportação, será possível desativá-la para voltar a usar a conta de serviço padrão. Depois que você verificar e atualizar as permissões do bucket do Cloud Storage, é possível ativá-la novamente.