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.

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 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\
  --type=firestore-native\
  --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 durante o qual o Firestore 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 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 das bibliotecas cliente, dos métodos da API REST ou do conetor Apache Beam FirestoreIO.

Bibliotecas cliente

Java

Tem de usar a transação ReadOnly para ler dados PITR. Não pode especificar diretamente readTime em leituras. Consulte o artigo Transações e gravações em lote para mais informações.

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

Nó

Tem de usar uma transação ReadOnly para ler dados PITR. Não pode especificar diretamente readTime em leituras. Consulte o artigo Transações e gravações em lote para mais informações.

const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

API REST

As leituras PITR são suportadas em todos os métodos de leitura do Firestore, que são: get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery e partitionQuery.

Para fazer uma leitura através dos métodos REST, experimente uma das seguintes opções:

No pedido do método de leitura, transmita o valor readTime como uma data/hora PITR suportada no método readOptions. Uma data/hora de PITR pode ser uma data/hora com precisão de microssegundos na última hora ou uma data/hora de minuto inteiro para além da última hora, mas não anterior a earliestVersionTime.
Use o parâmetro readTime juntamente com o método BeginTransaction como parte de uma ReadOnly transação para várias leituras PITR.

Apache Beam

Use o conetor do Apache Beam FirestoreIO para ler ou escrever documentos numa base de dados do Firestore em grande escala com o Dataflow.

As leituras PITR são suportadas no seguinte método de leitura do conector FirestoreIO. Estes métodos de leitura suportam o método withReadTime(@Nullable Instant readTime) que pode usar para leituras PITR:

Java

Pode usar o seguinte código com o código de pipeline do Dataflow de exemplo para operações de leitura ou escrita em massa. O exemplo usa o método withReadTime(@Nullable Instant readTime) para leituras PITR.

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

Para ver uma lista completa de readTimeexemplos no pipeline do Dataflow, consulte o repositório do GitHub.

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 \
    --namespace-ids=NAMESPACE_IDS
```
Onde,
- 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'.
- NAMESPACE_IDS – uma lista de IDs de espaços de nomes, por exemplo, 'customer','orders'.
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.