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 no modo Datastore.

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,datastore.namespaces.get,datastore.namespaces.list,datastore.statistics.get,datastore.statistics.list
Para exportar dados PITR: datastore.databases.export
Para importar dados PITR: datastore.databases.import

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 consola Google Cloud não é suportada.
O modo Datastore 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 Google Cloud projeto. Apenas os Google Cloud projetos 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 implica 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 o comando gcloud firestore databases create da seguinte forma:

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

Substitua os valores da seguinte forma:

LOCATION: localização onde quer criar a base de dados.
DATABASE_ID: definido como o ID da base de dados ou (predefinição).
TYPE - definido como datastore-mode.

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

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --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 modo Datastore retém todas as versões de dados para a 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 anteriores dos dados podem ser lidas na janela PITR. Este valor é atualizado continuamente pelo modo Datastore 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/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: DATASTORE_MODE
    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 PITR são retidos em milissegundos. O valor pode ser de uma hora quando a PITR está desativada ou de sete dias se a PITR estiver ativada.

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 o método readTime na classe ReadOption para ler dados PITR. Não pode usar a transação ReadOnly para executar leituras. Consulte o código de exemplo ReadOption para mais informações.

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query<Entity> query = ...
  QueryResults<Entity> queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

Para ver uma lista completa de exemplos de readTime, consulte o repositório do GitHub.

Python

Use a leitura PITR no SDK Python do modo Datastore através do método readTime ou use a transação ReadOnly com readTime para fazer leituras.

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

Para ver uma lista completa de exemplos de readTime, consulte o repositório do GitHub.

API REST

As leituras PITR são suportadas nos métodos de leitura da V1 do modo Datastore, que são lookup, runQuery e runAggregationQuery.

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 após a ú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 Apache Beam de E/S do modo Datastore para ler ou escrever entidades numa base de dados do modo Datastore em grande escala com o Dataflow.

Especifique o método withReadTime(Instant readTime) no objeto DatastoreV1.Read. Todas as leituras subsequentes que usam o objeto DatastoreV1.Read são lidas a partir do mesmo readTime.

Java

O código seguinte mostra como usar o método withReadTime para leituras PITR.

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection<Entity> entities = pipeline.apply(read);
    ...

Para ver uma lista completa de exemplos de withReadTime, consulte o repositório do GitHub.

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 todas as entidades e a exportação de tipos ou espaços de nomes específicos.

Exporte a base de dados, especificando o parâmetro snapshot-time para a data/hora de recuperação necessária.
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 de caminho opcional onde os ficheiros de exportação são armazenados.
- PITR_TIMESTAMP – Uma indicação de tempo 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 recolha ou IDs de grupos de recolha, por exemplo,'specific collection group1''specific collection group2'.
- NAMESPACE_IDS – uma lista de IDs de espaços de nomes, por exemplo,'customer''orders'.
A exportação de um subconjunto específico de tipos e/ou espaços de nomes com um filtro de entidades também é suportada.

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 completa de um minuto nos últimos sete dias, mas não anterior a earliestVersionTime. Se os dados já não existirem na data/hora especificada, recebe 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.

Use os passos em Importe todas as entidades para importar a base de dados exportada. Se já existir alguma entidade na sua base de dados, esta é substituída. A importação de um subconjunto específico de tipos e/ou espaços de nomes com um filtro de entidades também é suportada.

Trabalhe com a recuperação pontual (PITR) Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Autorizações

Autorizações necessárias

Antes de começar

Ative a PITR

Consola

gcloud

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

Consola

gcloud

Ler dados PITR

Bibliotecas cliente

Java

Python

API REST

Apache Beam

Java

Exporte e importe dados de PITR

gcloud

Trabalhe com a recuperação pontual (PITR)