Esta página foi traduzida pela API Cloud Translation.

Trabalhe com a recuperação pontual (PITR)

Esta página descreve como usar a recuperação num ponto específico no tempo (PITR) para reter e recuperar dados no Firestore com compatibilidade com o MongoDB.

Para compreender os conceitos de PITR, consulte o artigo Recuperação pontual.

Autorizações

Para receber as autorizações de que precisa para gerir as definições de PITR, peça ao seu administrador para lhe conceder a função de IAM de proprietário do Cloud Datastore (roles/datastore.owner) no projeto cujas definições de PITR quer ativar. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para gerir as definições de PITR. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para gerir as definições de PITR:

Para ativar a PITR ao criar uma base de dados: datastore.databases.create
Para atualizar as definições de PITR na base de dados existente: datastore.databases.update,datastore.databases.list
Para fazer leituras a partir de dados PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
Para exportar dados PITR: datastore.databases.export
Para importar dados PITR: datastore.databases.import
Para clonar uma base de dados: datastore.databases.clone

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Antes de começar

Tenha em atenção os seguintes pontos antes de começar a usar a PITR:

Não pode começar a ler a partir de sete dias no passado imediatamente após ativar a PITR.
Se quiser ativar a PITR quando criar uma base de dados, tem de usar o comando gcloud firestore databases create. A ativação da PITR durante a criação de uma base de dados através da Google Cloud consola não é suportada.
O Firestore com compatibilidade com o MongoDB começa a reter versões a partir do momento em que a PITR é ativada.
Não pode ler dados PITR na janela PITR depois de desativar o PITR.
Se reativar a PITR imediatamente após a desativar, os dados da PITR anteriores deixam de estar disponíveis. Todos os dados de PITR criados antes da desativação da PITR são eliminados após a data de validade da PITR.
Se eliminou acidentalmente dados na última hora e a PITR estiver desativada, pode restaurar os seus dados ativando a PITR no prazo de uma hora após a eliminação.
Qualquer leitura realizada em dados PITR expirados falha.

Ative a PITR

Antes de usar a PITR, ative a faturação para o seu projeto do Google Cloud. Apenas os projetos do Google Cloud com a faturação ativada podem usar a funcionalidade PITR.

Para ativar a PITR para a sua base de dados:

Consola

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

Aceda a Bases de dados
Selecione a base de dados necessária na lista de bases de dados.
No menu de navegação, clique em Recuperação de desastres.
Clique em Editar para editar as definições.
Selecione a caixa de verificação Ativar recuperação num ponto específico no tempo e, de seguida, clique em Guardar.

A ativação da PITR incorre em custos de armazenamento. Consulte Preços para mais informações.

Para desativar a PITR, desmarque a caixa de verificação Ativar recuperação pontual na página Recuperação de desastres na Google Cloud consola.

gcloud

Ative a PITR durante a criação da base de dados com os comandos gcloud firestore databases create e --enable-ptir da seguinte forma:

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --edition=enterprise\
  --enable-pitr

Substitua os valores da seguinte forma:

LOCATION: a localização onde quer criar a base de dados.
DATABASE_ID: definido como um ID da base de dados.

Pode desativar a PITR através do comando gcloud firestore databases update da seguinte forma:

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

Substitua os valores da seguinte forma:

DATABASE_ID: definido como o ID da base de dados ou (predefinição).

Obtenha o período de retenção e a hora da versão mais antiga

Consola

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

Aceda a Bases de dados
Selecione a base de dados necessária na lista de bases de dados.
No menu de navegação, clique em Recuperação de desastres.
Na secção Definições, tome nota do Período de retenção e da Hora da versão mais antiga.
- Período de retenção: o período em que o Firestore com compatibilidade com o MongoDB retém todas as versões dos dados da base de dados. O valor é de uma hora quando a PITR está desativada e de sete dias quando a PITR está ativada.
- Hora da versão mais antiga: a data/hora mais antiga em que as versões mais antigas dos dados podem ser lidas na janela PITR. Este valor é atualizado continuamente pelo Firestore com compatibilidade com o MongoDB e fica desatualizado no momento em que é consultado. Se estiver a usar este valor para recuperar dados, certifique-se de que tem em conta o tempo decorrido desde o momento em que o valor é consultado até ao momento em que inicia a recuperação.
- Recuperação pontual: mostra Enabled, se a recuperação pontual estiver ativada. Se a PITR estiver desativada, é apresentado o ícone Disabled.

gcloud

Execute o comando gcloud firestore databases describe da seguinte forma:

gcloud firestore databases describe --database=DATABASE_ID

Substitua DATABASE_ID pelo ID da base de dados ou '(default)'.

Segue-se o resultado:

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

onde,

earliestVersionTime: data/hora dos dados PITR mais antigos armazenados.
pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED se o PITR estiver ativado. Se a PITR estiver desativada, é apresentado POINT_IN_TIME_RECOVERY_DISABLED ou o campo pointInTimeRecoveryEnablement pode não ser apresentado.
versionRetentionPeriod: período durante o qual os dados de PITR são retidos em milissegundos. O valor pode ser de uma hora quando o PITR está desativado ou de sete dias se o PITR estiver ativado.

Ler dados PITR

Pode ler dados PITR através da sessão de instantâneo em vários controladores de cliente do MongoDB. Defina um snapshotTimestamp na sessão. O exemplo seguinte usa o controlador Java do MongoDB e está disponível uma funcionalidade semelhante noutros controladores:

Java

    var session =
        mongoClient.startSession(ClientSessionOptions.builder().snapshot(true).build());
  session.setSnapshotTimestamp(new BsonTimestamp(seconds, nanos));

  // run a find query with PITR timestamp
  collection.find(session, <filter>).toList();

  // run an aggregation query pipeline with PITR timestamp
  collection.aggregate(session, <aggregation pipeline stages>).toList();

  // run distinct command with PITR timestamp
  collection.distinct(session, <field>, <return value type class>).toList();

No MongoDB, o BsonTimestamp é um tipo BSON de 64 bits apenas interno do MongoDB. Os primeiros 32 bits representam os segundos da data/hora de época e os últimos 32 bits representam uma contagem de operações ordinal num cluster do MongoDB.

No Firestore com compatibilidade com o MongoDB, a data/hora da captura instantânea, que continua a usar um tipo de valor BsonTimestamp, interpreta os primeiros 32 bits como segundos da data/hora de época, mas os últimos 32 bits como nanosegundos dentro do segundo. Tenha em atenção que nem todas as cópias de segurança PITR com precisão de nanosegundos são suportadas. As datas/horas em microssegundos da última hora são permitidas, e as datas/horas em minutos inteiros dos últimos 7 dias são permitidas. Consulte a vista geral da recuperação pontual (PITR) para saber que carimbos de data/hora de leitura são suportados.

Clonar a partir de uma base de dados

Pode clonar uma base de dados existente num momento específico selecionado para uma nova base de dados:

A base de dados clonada é uma nova base de dados que vai ser criada na mesma localização que a base de dados de origem.

Para fazer um clone, o Firestore usa dados de recuperação num determinado momento (PITR) da base de dados de origem. A base de dados clonada inclui todos os dados e índices.
Por predefinição, a base de dados clonada é encriptada da mesma forma que a base de dados de origem, através da encriptação predefinida da Google ou da encriptação CMEK. Pode especificar um tipo de encriptação diferente ou usar uma chave diferente para a encriptação CMEK.
A data/hora tem uma granularidade de um minuto e especifica um ponto no tempo no passado, no período definido pela janela PITR:
- Se a PITR estiver ativada para a sua base de dados, pode selecionar qualquer minuto nos últimos 7 dias (ou menos, se a PITR tiver sido ativada há menos de 7 dias).
- Se a PITR não estiver ativada, pode selecionar qualquer minuto na última hora.
- Pode verificar a data/hora mais antiga que pode escolher na descrição da base de dados.

Consola

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

Aceda a Bases de dados
Clique em Ver mais na linha da tabela da base de dados que quer clonar. Clique em Clonar. É apresentada a caixa de diálogo Criar um clone.
Na caixa de diálogo Crie um clone, indique os parâmetros para clonar a base de dados:
1. No campo Atribua um ID ao clone, introduza um ID da base de dados para uma nova base de dados clonada. Este ID da base de dados não pode estar associado a uma base de dados existente.
2. No campo Clonar a partir de, selecione um ponto no tempo a usar para a clonagem. A hora selecionada corresponde a uma data/hora de PITR, com uma granularidade de minutos.
Clique em Criar clone.

gcloud

Use o comando gcloud alpha firestore databases clone para clonar uma base de dados:

gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

Substitua o seguinte:

SOURCE_DATABASE: o nome da base de dados de uma base de dados existente que quer clonar. O nome usa o formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.
PITR_TIMESTAMP: a data/hora de PITR no formato RFC 3339, com granularidade de minutos. Por exemplo: 2025-06-01T10:20:00.00Z ou 2025-06-01T10:30:00.00-07:00.
DESTINATION_DATABASE_ID: um ID da base de dados para uma nova base de dados clonada. Este ID da base de dados não pode estar associado a uma base de dados existente.

Exemplo:

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db'

Altere a configuração de encriptação da base de dados clonada

Por predefinição, a base de dados clonada tem a mesma configuração de encriptação que a base de dados de origem. Para alterar a configuração de encriptação, use o argumento --encryption-type:

(Predefinição) use-source-encryption: use a mesma configuração de encriptação que a base de dados de origem.
google-default-encryption: use a encriptação predefinida da Google.
customer-managed-encryption: use a encriptação CMEK. Especifique um ID da chave no argumento --kms-key-name.

O exemplo seguinte mostra como configurar a encriptação CMEK para a base de dados clonada:

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Exporte e importe dados de PITR

Pode exportar a sua base de dados para o Cloud Storage a partir de dados PITR usando o comando gcloud firestore export. 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 indicação de tempo 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.

Exporte a base de dados, especificando o parâmetro snapshot-time para a data/hora de recuperação escolhida.
gcloud
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 \
    --collection-ids=COLLECTION_IDS
```
Substitua o seguinte:
- BUCKET_NAME_PATH: um contentor do Cloud Storage válido com um prefixo do caminho opcional onde os ficheiros de exportação são armazenados.
- PITR_TIMESTAMP – Uma indicação de tempo de PITR com um nível de detalhe de minutos, por exemplo, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
- COLLECTION_IDS – uma lista de IDs de coleções ou IDs de grupos de coleções, por exemplo –'specific-collection-group1','specific-collection-group2'.
Tenha em atenção os seguintes pontos antes de exportar dados PITR:
- Especifique a data/hora no formato RFC 3339. Por exemplo, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
- 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. A data/hora tem de ser um minuto completo, mesmo que a hora especificada esteja na última hora.
- Não lhe é cobrado um valor por uma exportação PITR falhada.
Importar para uma base de dados.

Siga os passos em Importar todos os documentos para importar a base de dados exportada. Se já existir algum documento na sua base de dados, este vai ser substituído.