Nesta página, descrevemos como usar a recuperação pontual (PITR, na sigla em inglês) para reter e recuperar dados no Firestore no modo Datastore.
Para entender os conceitos da PITR, consulte Recuperação pontual.
Permissões
Para ter as permissões necessárias para gerenciar as configurações da PITR,
peça ao administrador para conceder a você
Papel do IAM Proprietário do Cloud Datastore (roles/datastore.owner
) no projeto com as configurações de PITR que você quer ativar.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esse papel predefinido contém as permissões necessárias para gerenciar as configurações de PITR. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para gerenciar as configurações de PITR:
-
Para ativar a PITR ao criar um banco de dados:
datastore.databases.create
-
Para atualizar as configurações da PITR no banco de dados atual:
datastore.databases.update
,datastore.databases.list
-
Para realizar leituras 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 da PITR:
datastore.databases.import
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Antes de começar
Observe os seguintes pontos antes de começar a usar a PITR:
- Não é possível iniciar leituras de sete dias anteriores imediatamente depois de ativar a PITR.
- Se você quiser ativar a PITR ao criar um banco de dados, use o comando
gcloud firestore databases create
. Não há suporte para a ativação da PITR ao criar um banco de dados usando o console do Google Cloud. - O modo Datastore começa a reter versões a partir do momento em que ativar a PITR.
- Não é possível ler dados PITR na janela PITR depois de desativar a PITR.
- Se você reativar a PITR imediatamente após desativá-la, os dados da PITR anteriores não estarão mais disponíveis. Os dados da PITR criados antes da desativação serão excluídos após a data de validade.
- Se você excluiu dados acidentalmente na última hora e a PITR está desativada, é possível restaurar seus dados ativando a PITR dentro de uma hora após a exclusão.
- Qualquer leitura realizada em dados PITR expirados falha.
Ativar a PITR
Antes de usar a PITR, ative o faturamento do projeto do Google Cloud. Somente projetos do Google Cloud com faturamento ativado podem usar o recurso PITR.
Para ativar a PITR no banco de dados:
Console
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Recuperação de desastres.
Clique em Editar para editar as configurações.
Marque a caixa de seleção Ativar recuperação pontual e clique em Salvar.
A ativação da PITR incorre em custos de armazenamento. Para mais informações, consulte Preços.
Para desativar a PITR, desmarque a caixa de seleção Ativar recuperação pontual na página "Recuperação de desastres" no console do Google Cloud.
gcloud
Ative a PITR durante a criação do banco de dados com o comando gcloud firestore databases create
da seguinte maneira:
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
: local em que você quer criar o banco de dados.DATABASE_ID
: definido como o ID do banco de dados ou (padrão).TYPE
: definido como "datastore-mode".
É possível desativar a PITR usando o comando gcloud firestore databases update
da seguinte maneira:
gcloud firestore databases update\
[--database=DATABASE_ID; default="(default)"]\
--no-enable-pitr
Substitua os valores da seguinte forma:
DATABASE_ID
: definido como o ID do banco de dados ou (padrão).
Conseguir o período de armazenamento e o horário da versão mais antiga
Console
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Recuperação de desastres.
Na seção Configurações, anote o Período de armazenamento e o Horário da versão mais antiga.
- Período de armazenamento: o período em que o modo Datastore é mantido todas as versões de dados do banco de dados. O valor é de uma hora quando a PITR está desativada e de sete dias quando a PITR está ativada.
- Horário da versão mais antigo: o carimbo de data/hora mais antigo em que as versões mais antigas dos dados podem ser lidas na janela da PITR. Este valor é atualizado continuamente pelo modo Datastore e fica obsoleto no momento em que é consultado. Se você estiver usando esse valor para recuperar dados, não deixe de considerar o momento entre o momento em que o valor é consultado e o momento em que você inicia a recuperação.
- Recuperação pontual: mostra
Enabled
se a PITR estiver ativada. Se a PITR estiver desativada, você veráDisabled
.
gcloud
Execute o comando gcloud firestore database describe da seguinte maneira:
gcloud firestore databases describe --database=DATABASE_ID
Substitua DATABASE_ID
pelo ID do banco de dados ou default
.
Esta é a saída:
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
Em que:
earliestVersionTime
: carimbo de data/hora dos dados da PITR mais antigos armazenados.pointInTimeRecoveryEnablement
: mostraPOINT_IN_TIME_RECOVERY_ENABLED
, se a PITR estiver ativada. Se a PITR estiver desativada, você veráPOINT_IN_TIME_RECOVERY_DISABLED
ou o campopointInTimeRecoveryEnablement
pode não ser exibido.versionRetentionPeriod
: período em que os dados da 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
Leia dados da PITR usando as bibliotecas de cliente, os métodos da API REST ou o conector do FirestoreIO Apache Beam.
Bibliotecas de cliente
Java
Use o método readTime
na classe ReadOption
para ler dados PITR. Não é possível usar a transação ReadOnly
para realizar leituras.
Para mais informações, consulte o exemplo de código ReadOption (link em inglês).
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 conferir uma lista completa de exemplos de readTime
, consulte o repositório do GitHub (link em inglês).
Python
Use a leitura PITR no SDK do Python no modo Datastore com o método readTime
ou use a transação ReadOnly
com readTime
para realizar 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 uma lista completa de exemplos de readTime
, consulte o repositório do GitHub.
API REST
As leituras da PITR têm suporte nos métodos de leitura do modo V1 do Datastore, que são lookup, runQuery e runAggregationQuery.
Para realizar uma leitura usando os métodos REST, tente uma das seguintes opções:
Na solicitação do método de leitura, transmita o valor
readTime
como um carimbo de data/hora da PITR compatível no métodoreadOptions
. Um carimbo de data/hora da PITR pode ser um carimbo de precisão de microssegundos na última hora ou um carimbo de data/hora de um minuto inteiro além da última hora, mas não antes daearliestVersionTime
.Use o parâmetro
readTime
com o métodoBeginTransaction
como parte de uma transaçãoReadOnly
para várias leituras de PITR.
Apache Beam
Use o conector de E/S do Apache Beam no modo Datastore para ler ou gravar entidades em um banco 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 usando o objeto DatastoreV1.Read
são lidas do mesmo readTime
.
Java
O código a seguir mostra como usar o método withReadTime
para leituras da 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 conferir uma lista completa de exemplos de withReadTime
, consulte o repositório do GitHub (link em inglês).
Exportar e importar dados da PITR
É possível exportar seu banco de dados para o Cloud Storage de dados PITR consistentes
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 da PITR oferece suporte a todos os filtros, incluindo a exportação de todas as entidades e a exportação de tipos ou namespaces específicos.
Exporte o banco de dados, especificando o parâmetro
snapshot-time
para o carimbo de data/hora de recuperação necessário.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,
BUCKET_NAME_PATH
: um bucket válido do Cloud Storage com um prefixo de caminho opcional em que os arquivos de exportação são armazenados.PITR_TIMESTAMP
: um carimbo de data/hora da PITR na granularidade de minutos, por exemplo,2023-05-26T10:20:00.00Z
ou2023-10-19T10:30:00.00-07:00
.COLLECTION_IDS
: uma lista de IDs de coleções ou de grupos de coleções, por exemplo,'specific collection group1'
,'specific collection group2'
.NAMESPACE_IDS
: uma lista de IDs de namespace, por exemplo-'customer'
,'orders'
.
Também é possível exportar um subconjunto específico de tipos e/ou namespaces com um filtro de entidade.
Observe os seguintes pontos antes de exportar dados PITR:
- Especifique o carimbo de data/hora no formato
RFC 3339.
Por exemplo,
2023-05-26T10:20:00.00Z
ou2023-10-19T10:30:00.00-07:00
. - Verifique se o carimbo de data/hora especificado é de um minuto inteiro nos últimos sete dias, mas não antes do
earliestVersionTime
. Se os dados não existirem mais no carimbo de data/hora especificado, você receberá um erro. O carimbo de data/hora precisa ser um minuto inteiro, mesmo que o horário especificado seja anterior à hora anterior. - Não haverá cobrança pela falha na exportação da PITR.
Importar para um banco de dados.
Use as etapas em Importar todas as entidades para importar seu banco de dados exportado. Se alguma entidade já existir no seu banco de dados, ela será substituída. Também é possível importar um subconjunto específico de tipos e/ou namespaces com um filtro de entidade.