Importe e exporte dados

Importe e exporte dados

Pode usar o serviço de exportação e importação gerido para recuperar dados eliminados acidentalmente e exportar dados para processamento offline. Pode exportar todos os documentos ou apenas coleções específicas. Da mesma forma, pode importar todos os dados de uma exportação ou apenas coleções específicas. Os dados exportados de uma base de dados do Firestore com compatibilidade com o MongoDB podem ser importados para outra base de dados do Firestore com compatibilidade com o MongoDB. Também pode carregar exportações do Firestore com compatibilidade com o MongoDB para o BigQuery.

Esta página descreve como exportar e importar documentos compatíveis com o MongoDB do Firestore através do serviço de exportação e importação gerido e do Cloud Storage. O serviço de exportação e importação gerido do Firestore com compatibilidade com o MongoDB está disponível através da ferramenta de linha de comandos gcloud e da API (REST, RPC) do Firestore com compatibilidade com o MongoDB.

Atenção: a exportação de dados do Firestore com compatibilidade com o MongoDB vai incorrer numa operação de leitura por documento exportado. No entanto, estas leituras não aparecem na secção de utilização da consola. Certifique-se de que compreende isto antes de configurar exportações recorrentes para evitar uma fatura inesperada.

Antes de começar

Antes de poder usar o serviço de exportação e importação gerido, tem de concluir as seguintes tarefas:

1. Ative a faturação para o seu projeto Google Cloud . Apenas Google Cloud os projetos com a faturação ativada podem usar a funcionalidade de exportação e importação.
2. Crie um segmento do Cloud Storage para o seu projeto numa localização perto da localização da base de dados do Firestore com compatibilidade com o MongoDB. Não pode usar um bucket Requester Pays para operações de exportação e importação.

3. Certifique-se de que a sua conta tem as autorizações necessárias para o Firestore com compatibilidade com o MongoDB e o Cloud Storage. Se for o proprietário do projeto, a sua conta tem as autorizações necessárias. Caso contrário, as seguintes funções concedem as autorizações necessárias para operações de exportação e importação, bem como para acesso ao Cloud Storage:

   • Funções de compatibilidade do Firestore com o MongoDB: Owner, Cloud Datastore Owner ou Cloud Datastore Import Export Admin
     Nota: estas funções do Datastore também concedem autorizações no Firestore com compatibilidade do MongoDB.

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

Autorizações do agente de serviço

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

Agente de serviço do Firestore

[e-mail]

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

Nota: anteriormente, o Firestore usava a conta de serviço predefinida do App Engine em vez do agente de serviço do Firestore. Se a sua base de dados continuar a usar a conta de serviço do App Engine para importar ou exportar dados, recomendamos que migre para o agente de serviço do Firestore específico do serviço. Pode ver que conta as suas operações de importação e exportação usam na Google Cloud consola.

Se usar os VPC Service Controls, tem de usar o agente do serviço Firestore específico do serviço para proteger totalmente as operações de importação e exportação. Os VPC Service Controls não são compatíveis com a conta de serviço do App Engine.

O agente de serviço do Firestore requer acesso ao contentor do Cloud Storage usado numa operação de exportação ou importação. Se o seu contentor do Cloud Storage estiver no mesmo projeto que a sua base de dados do Firestore, o agente de serviço do Firestore pode aceder ao contentor por predefinição.

Se o contentor do Cloud Storage estiver noutro projeto, tem de conceder ao agente de serviço do Firestore acesso ao contentor do Cloud Storage.

Atribua funções ao agente do serviço

Pode usar a ferramenta de linha de comandos gsutil para atribuir uma das funções abaixo. Por exemplo, para atribuir a função de administrador do armazenamento ao agente de serviço do Firestore, execute o seguinte comando:

gsutil iam ch serviceAccount:[e-mail]:roles/storage.admin \
    gs://[BUCKET_NAME]

Substitua PROJECT_NUMBER pelo número do seu projeto, que é usado para atribuir um nome ao agente do serviço Firestore. Para ver o nome do agente do serviço, consulte o artigo Veja o nome do agente do serviço.

Em alternativa, pode atribuir esta função através da Google Cloud consola.

Veja o nome do agente do serviço

Pode ver a conta que as suas operações de importação e exportação usam para autorizar pedidos na página Importar/Exportar na Google Cloud consola. Também pode ver se a sua base de dados usa o agente de serviço do Firestore ou a conta de serviço do App Engine antiga.

1. Veja a conta de autorização junto à etiqueta Trabalhos de importação/exportação executados como.

O agente de serviço precisa da função Storage Admin para o contentor do Cloud Storage a usar para a operação de exportação ou importação.

Configure o gcloud para o seu projeto

Pode iniciar operações de importação e exportação através da Google Cloud consola ou da ferramenta de linha de comandos gcloud. Para usar o gcloud, configure a ferramenta de linha de comandos e ligue-se ao seu projeto de uma das seguintes formas:

• Aceda ao gcloud a partir da Google Cloud consola através do Cloud Shell.

  Inicie o Cloud Shell

  Certifique-se de que o dispositivo gcloud está configurado para o projeto correto:

  gcloud config set project [PROJECT_ID]
  

• Instale e inicialize o SDK do Google Cloud.

Importar dados

Depois de ter ficheiros de exportação no Cloud Storage, pode importar documentos desses ficheiros de volta para o seu projeto ou para outro projeto. Tenha em atenção os seguintes pontos acerca das operações de importação:

• Quando importa dados, os índices necessários são atualizados através das definições de índice atuais da sua base 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, o respetivo ID é reservado para evitar conflitos de IDs. Se já existir um documento com o mesmo ID, a importação substitui o documento existente.

• Se um documento na sua base de dados não for afetado por uma importação, permanece na base de dados após a importação.

• O nome do ficheiro .overall_export_metadata tem de corresponder ao nome da respetiva pasta principal:

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

  Se mover ou copiar os ficheiros de saída de uma exportação, mantenha o nome do ficheiro PARENT_FOLDER_NAME e .overall_export_metadata igual.

• Uma importação para uma base de dados do Firestore com compatibilidade com o MongoDB a partir de uma exportação com subcoleções falha, uma vez que as subcoleções não são suportadas no Firestore com compatibilidade com o MongoDB.

• Uma importação para uma base de dados da edição padrão do Firestore a partir de uma exportação com tipos BSON falha, uma vez que os tipos BSON não são suportados na edição padrão do Firestore.

• Uma importação para uma base de dados do Firestore com compatibilidade com o MongoDB não pode importar dados de espaços de nomes não predefinidos (API Datastore).

  Uma importação para uma base de dados do Firestore com compatibilidade com o MongoDB a partir de ficheiros de dados que contenham espaços de nomes não predefinidos só é permitida se a operação de exportação tiver incluído um filtro com o espaço de nomes predefinido.--namespace-ids Só são importados dados do espaço de nomes predefinido.

Importe todos os documentos de uma exportação

Consola do Google Cloud

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione uma base de dados na lista de bases de dados.

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

4. Clique em Importar.

5. No campo Nome do ficheiro, introduza o nome do ficheiro de um ficheiro .overall_export_metadata de uma operação de exportação concluída. Pode usar o botão Procurar para ajudar a selecionar o ficheiro.

6. Clique em Importar.

A consola regressa à página Importar/Exportar. Se a operação for iniciada com êxito, a página adiciona uma entrada à página de importações e exportações recentes. Em caso de falha, a página apresenta 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]/ --database=[DATABASE]

Substitua o seguinte:

• BUCKET_NAME/EXPORT_PREFIX: localização dos seus ficheiros de exportação.

• DATABASE: nome da base de dados.

Por exemplo:

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

Pode confirmar a localização dos seus ficheiros de exportação no navegador do Cloud Storage na Google Cloud consola:

Abrir navegador do Cloud Storage

Depois de iniciar uma operação de importação, o fecho do terminal não cancela a operação. Consulte o artigo Cancelar uma operação.

Importe coleções específicas

Nota: para importar coleções específicas, tem de usar o resultado de uma operação de exportação em que exportou coleções específicas.

Consola do Google Cloud

Não pode selecionar coleções específicas na consola. Em alternativa, use gcloud.

gcloud

Para importar coleções específicas de um conjunto de ficheiros de exportação, use a flag --collection-ids. A operação importa apenas as coleções com os IDs de coleções especificados. Especifique o nome da base de dados com a flag --database.

Apenas uma exportação de coleções específicas suporta uma importação de coleções específicas. 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] \
  --database=[DATABASE]

Importe a partir de uma exportação com dados PITR

Use os mesmos passos que em Importar todos os documentos ou Importar coleções específicas para importar dados PITR. Se já existir algum documento na sua base de dados, este vai ser substituído.

Exportar dados

Uma operação de exportação copia documentos na sua base de dados para um conjunto de ficheiros num contentor do Cloud Storage. Tenha em atenção que uma exportação não é uma imagem exata da base de dados tirada no momento em que a exportação é iniciada. Uma exportação pode incluir alterações feitas enquanto a operação estava em execução.

Nota: tem de exportar coleções específicas se planear:

• Importe apenas coleções específicas
• Carregue dados do Firestore com compatibilidade com o MongoDB no BigQuery

Exporte todos os documentos

Consola do Google Cloud

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione a base de dados necessária na lista de bases de dados.

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

4. Clique em Exportar.

5. Clique na opção Exportar base de dados completa.

6. Selecione Exportar estado atual da base de dados para exportar os dados atuais.

7. Na secção Destino, introduza o nome de um contentor do Cloud Storage ou use o botão Procurar para selecionar um contentor.

8. Clique em Exportar.

A consola regressa à página Importar/Exportar. Se a operação for iniciada com êxito, a página adiciona uma entrada à página de importações e exportações recentes. Em caso de falha, a página apresenta uma mensagem de erro.

gcloud

Use o comando firestore export para exportar todos os documentos na sua base de dados, substituindo [BUCKET_NAME] pelo nome do seu contentor do Cloud Storage. Adicione a flag --async para impedir que a ferramenta gcloud aguarde a conclusão da operação.

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

Substitua o seguinte:

• BUCKET_NAME: organize as suas exportações adicionando um prefixo de ficheiro após o nome do contentor, por exemplo, BUCKET_NAME/my-exports-folder/export-name. Se não fornecer um prefixo de ficheiro, o serviço de exportação gerido cria um com base na data/hora atual.

• DATABASE: nome da base de dados a partir da qual quer exportar os documentos.

Depois de iniciar uma operação de exportação, o fecho do terminal não cancela a operação. Consulte o artigo Cancelar uma operação.

Exporte coleções específicas

Consola do Google Cloud

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione a base de dados necessária na lista de bases de dados.

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

4. Clique em Exportar.

5. Clique na opção Exportar um ou mais grupos de recolha. Use o menu pendente para selecionar uma ou mais coleções.

6. Selecione Exportar estado atual da base de dados para exportar os dados atuais.

7. Na secção Destino, introduza o nome de um contentor do Cloud Storage ou use o botão Procurar para selecionar um contentor.

8. Clique em Exportar.

A consola regressa à página Importar/Exportar. Se a operação for iniciada com êxito, a página adiciona uma entrada à página de importações e exportações recentes. Em caso de falha, a página apresenta uma mensagem de erro.

gcloud

Para exportar coleções específicas, use a flag --collection-ids. A operação exporta apenas as coleções com os IDs de coleções especificados.

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

Por exemplo, pode conceber uma coleção restaurants na base de dados foo para incluir coleções adicionais, como ratings, reviews ou outlets. Para exportar restaurants e reviews específicos da coleção, o comando tem o seguinte aspeto:

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

Exporte a partir de uma indicação de tempo PITR

Pode exportar a sua base de dados para o Cloud Storage a partir de dados PITR. Pode exportar dados PITR cuja data/hora seja uma data/hora de um minuto inteiro nos últimos sete dias, mas não antes de earliestVersionTime. Se os dados já não existirem na data/hora especificada, a operação de exportação falha.

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

Tenha em atenção os seguintes pontos antes de exportar dados PITR:

• Especifique a data/hora no formato RFC 3339. Por exemplo, 2020-09-01T23:59:30.234233Z.
• Certifique-se de que a data/hora especificada é uma data/hora de um minuto inteiro nos últimos sete dias, mas não anterior a earliestVersionTime. Se os dados já não existirem na data/hora especificada, é gerado um erro.
• Não lhe é cobrado um valor por uma exportação PITR falhada.

Consola

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados
2. Selecione uma base de dados na lista de bases de dados.
3. No menu de navegação, clique em Importar/Exportar.
4. Clique em Exportar.
5. Configure a origem da exportação para exportar toda a base de dados ou apenas coleções específicas.

6. Na secção Escolha o estado da base de dados a exportar, selecione Exportar a partir de um ponto anterior no tempo.

   Selecione uma hora do instantâneo a usar para a exportação

7. Na secção Destino, introduza o nome de um contentor do Cloud Storage ou use o botão Procurar para selecionar um contentor.

8. Clique em Exportar.

   A consola regressa à página Importar/Exportar. Se a operação for iniciada com êxito, a página adiciona uma entrada à página de importações e exportações recentes. Em caso de falha, a página apresenta uma mensagem de erro.

gcloud

Pode exportar a sua base de dados para o Cloud Storage a partir de dados PITR através do comando gcloud firestore export.

Exporte a base de dados, especificando o parâmetro snapshot-time para uma data/hora de recuperação. Execute o seguinte comando para exportar a base de dados para o seu contentor.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Em que PITR_TIMESTAMP é uma data/hora de PITR com um nível de detalhe de minutos, por exemplo, 2023-05-26T10:20:00.00Z.

Adicione a flag --collection-ids para exportar coleções específicas.

Faça a gestão das operações de exportação e importação

Depois de iniciar uma operação de exportação ou importação, o Firestore com compatibilidade com o MongoDB atribui um nome único à operação. Pode usar o nome da operação para eliminar, cancelar ou verificar o estado da operação.

Os nomes das operações têm o prefixo projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, por exemplo:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

No entanto, pode omitir o prefixo quando especificar um nome de operação para os comandos describe, cancel e delete.

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

Consola do Google Cloud

Pode ver uma lista das operações de exportação e importação recentes na página Importar/Exportar da Google Cloud consola.

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione a base de dados necessária na lista de bases de dados.

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

gcloud

Use o comando 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 estado da operação

Consola do Google Cloud

Pode ver o estado de uma operação de exportação ou importação recente na página Importar/Exportar da Google Cloud consola.

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione a base de dados necessária na lista de bases de dados.

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

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

Estime o tempo de conclusão

Um pedido do estado de uma operação de longa duração devolve as métricas workEstimated e workCompleted. Cada uma destas métricas é devolvida 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 vai processar. O Firestore com compatibilidade com o MongoDB pode omitir esta métrica se não conseguir fazer uma estimativa.

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

Divida workCompleted por workEstimated para uma estimativa aproximada do progresso. Esta estimativa pode ser imprecisa, uma vez que depende da recolha de estatísticas atrasadas.

Cancele uma operação

Consola do Google Cloud

Pode cancelar uma operação de exportação ou importação em execução na página Importar/Exportar da Google Cloud consola.

1. Na Google Cloud consola, aceda à página Bases de dados.

   Aceda a Bases de dados

2. Selecione a base de dados necessária na lista de bases de dados.

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

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

gcloud

Use o comando operations cancel para parar uma operação em curso:

gcloud firestore operations cancel [OPERATION_NAME]

O cancelamento de uma operação em execução não anula a operação. Uma operação de exportação cancelada deixa os documentos já exportados no Cloud Storage, e uma operação de importação cancelada deixa no lugar as atualizações já feitas à sua base de dados. Não pode importar uma exportação concluída parcialmente.

Elimine 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 elimina os ficheiros de exportação do Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

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

Tem de ativar a faturação para o seu Google Cloud projeto antes de usar o serviço de exportação e importação gerido.

As operações de exportação e importação são cobradas por unidades de leitura e unidades de escrita às taxas indicadas nos preços do Firestore com compatibilidade com o MongoDB.

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

As operações de exportação ou importação não acionam os alertas de Google Cloud orçamento até à conclusão. As operações de exportação e importação não afetam a utilização apresentada na secção de utilização da consola.

Ver custos de exportação e importação

As operações de exportação e importação aplicam a etiqueta goog-firestoremanaged:exportimport às operações faturadas. Na página de relatórios do Cloud Billing, pode usar esta etiqueta para ver os custos relacionados com operações de importação e exportação:

Nota: as operações de exportação e importação executadas antes de 8 de setembro de 2020 não aplicaram a etiqueta goog-firestoremanaged.

Exporte para o BigQuery

Pode carregar dados de uma exportação do Firestore com compatibilidade com o MongoDB para o BigQuery, mas apenas se tiver especificado um filtro collection-ids. Consulte o artigo Carregar dados do Firestore com exportações de compatibilidade do MongoDB.

Quando carrega dados do Firestore com compatibilidade com o MongoDB para o BigQuery, os tipos de dados BSON são representados com o tipo de dados STRING.

Limite de colunas do BigQuery

O BigQuery impõe um limite de 10 000 colunas por tabela. As operações de exportação do Firestore com compatibilidade com o MongoDB geram um esquema de tabela do BigQuery para cada coleção. Neste esquema, cada nome de campo exclusivo numa coleção torna-se uma coluna do esquema.

Se o esquema do BigQuery de uma coleção exceder as 10 000 colunas, a operação de exportação do Firestore com compatibilidade com o MongoDB tenta manter-se abaixo do limite de colunas tratando os campos de mapas como bytes. Se esta conversão fizer com que o número de colunas seja inferior a 10 000, pode carregar os dados para o BigQuery, mas não pode consultar os subcampos nos campos de mapa. Se o número de colunas continuar a exceder 10 000,a operação de exportação não gera um esquema do BigQuery para a recolha, e não pode carregar os respetivos dados para o BigQuery.

Exporte ficheiros de metadados e de formato

A saída de uma exportação gerida usa o formato de registo LevelDB.

Ficheiros de metadados

Uma operação de exportação cria um ficheiro de metadados para cada coleção que especificar. Normalmente, os ficheiros de metadados são denominados ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Os ficheiros de metadados são buffers de protocolo e pode descodificá-los com o protoccompilador de protocolo. Por exemplo, pode descodificar um ficheiro de metadados para determinar as coleções que os ficheiros de exportação contêm:

protoc --decode_raw < export0.export_metadata