Utilizzare il recupero point-in-time (PITR)

Questa pagina descrive come utilizzare il recupero point-in-time (PITR) per conservare e recuperare i dati in Firestore in modalità Datastore.

Per comprendere i concetti relativi al PITR, consulta Recupero point-in-time.

Autorizzazioni

Per ottenere le autorizzazioni necessarie per gestire le impostazioni PITR, chiedi all'amministratore di concederti il ruolo IAM Cloud Datastore Owner (roles/datastore.owner) sul progetto per cui vuoi abilitare le impostazioni PITR. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire le impostazioni PITR. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prima di iniziare

Tieni presente quanto segue prima di iniziare a utilizzare la funzionalità PITR:

• Non puoi iniziare a leggere da sette giorni prima del momento attuale immediatamente dopo aver attivato il PITR.
• Se vuoi attivare il PITR quando crei un database, devi utilizzare il comando gcloud firestore databases create. L'abilitazione del PITR durante la creazione di un database utilizzando la console Google Cloud non è supportata.
• La modalità Datastore inizia a conservare le versioni dal momento in cui viene attivato il PITR.
• Non puoi leggere i dati PITR nella finestra PITR dopo aver disattivato il PITR.
• Se riattivi il PITR subito dopo averlo disattivato, i dati PITR precedenti non saranno più disponibili. Tutti i dati PITR creati prima della disattivazione del PITR verranno eliminati dopo la data di scadenza del PITR.
• Se hai eliminato accidentalmente dei dati nell'ultima ora e il PITR è disattivato, puoi ripristinarli attivando il PITR entro un'ora dall'eliminazione.
• Qualsiasi lettura eseguita su dati PITR scaduti non va a buon fine.

Abilita PITR

Prima di utilizzare il PITR, attiva la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con fatturazione abilitata possono utilizzare la funzionalità PITR.

Per abilitare il PITR per il tuo database:

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

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

Recupera il periodo di conservazione e la data e l'ora della prima versione

gcloud firestore databases describe --database=DATABASE_ID

    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

Leggi i dati PITR

Puoi leggere i dati PITR utilizzando le librerie client, i metodi dell'API REST o il connettore Apache Beam FirestoreIO.

  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");

  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()

  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);
    ...

Clona da un database

Puoi clonare un database esistente in un timestamp selezionato in un nuovo database:

• Il database clonato è un nuovo database che verrà creato nella stessa località del database di origine.

  Per creare un clone, Firestore utilizza i dati di recupero point-in-time (PITR) del database di origine. Il database clonato include tutti i dati e gli indici.

• Per impostazione predefinita, il database clonato verrà criptato nello stesso modo del database di origine, utilizzando la crittografia predefinita di Google o la crittografia CMEK. Puoi specificare un tipo di crittografia diverso o utilizzare una chiave diversa per la crittografia CMEK.

• Il timestamp ha una granularità di un minuto e specifica un momento nel passato, nel periodo definito dalla finestra PITR:

  • Se il PITR è abilitato per il tuo database, seleziona un minuto qualsiasi degli ultimi 7 giorni (o meno se il PITR è stato abilitato meno di 7 giorni fa).
  • Se il PITR non è abilitato, puoi selezionare un minuto qualsiasi nell'ultima ora.
  • Puoi controllare il timestamp più recente che puoi scegliere nella descrizione del tuo database.

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

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

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

Esporta e importa dai dati PITR

Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il comando gcloud firestore export. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero compreso negli ultimi sette giorni, ma non prima del giorno earliestVersionTime. Se i dati non esistono più nel timestamp specificato, l'operazione di esportazione non va a buon fine.

L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutte le entità e l'esportazione di tipi o spazi dei nomi specifici.

1. Esporta il database, specificando il parametro snapshot-time per il timestamp di recupero richiesto.

   gcloud

   Esegui questo comando per esportare il database nel tuo bucket.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Dove:

   • BUCKET_NAME_PATH: un bucket Cloud Storage valido con un prefisso di percorso facoltativo in cui sono archiviati i file di esportazione.
   • PITR_TIMESTAMP: un timestamp PITR con granularità al minuto, ad esempio 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS: un elenco di ID raccolta o ID gruppo di raccolte, ad esempio 'specific collection group1','specific collection group2'.
   • NAMESPACE_IDS: un elenco di ID namespace, ad esempio 'customer','orders'.

   Puoi anche esportare un sottoinsieme specifico di tipi e spazi dei nomi con un filtro delle entità. Per saperne di più, consulta Esportazione di tipi o spazi dei nomi specifici.

   Tieni presente quanto segue prima di esportare i dati PITR:

   • Abilita il PITR nel tuo database. Se il PITR è disabilitato, l'esportazione in un timestamp dello snapshot non va a buon fine, anche per i timestamp nell'ultima ora dopo earliestVersionTime. L'operazione di esportazione restituisce l'errore Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
   • Specifica il timestamp nel formato RFC 3339. Ad esempio: 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • Assicurati che il timestamp specificato sia un timestamp di un minuto intero compreso negli ultimi sette giorni, ma non precedente al earliestVersionTime. Se i dati non esistono più nel timestamp specificato, riceverai un errore. Il timestamp deve essere un minuto intero, anche se l'ora specificata rientra nell'ora precedente.
   • Non ti verrà addebitato alcun costo per un'esportazione PITR non riuscita.

2. Importa in un database.

   Segui i passaggi descritti in Importa tutte le entità per importare il database esportato. Se un'entità esiste già nel tuo database, verrà sovrascritta. Puoi anche importare un sottoinsieme specifico di tipi o spazi dei nomi con un filtro delle entità. Per saperne di più, consulta Importa tipi o spazi dei nomi specifici.