Работа с восстановлением на момент времени (PITR)

На этой странице описывается, как использовать восстановление на момент времени (PITR) для сохранения и восстановления данных в Cloud Firestore.

Чтобы понять концепцию PITR, см. Восстановление на определенный момент времени .

Разрешения

Чтобы получить разрешения, необходимые для управления настройками PITR, попросите администратора предоставить вам следующие роли IAM в проекте, в котором вы хотите включить PITR:

  • Владелец облачного хранилища данных ( roles/datastore.owner )

Для настраиваемых ролей убедитесь, что предоставлены следующие разрешения:

  • Чтобы включить PITR при создании базы данных: datastore.databases.create
  • Чтобы обновить настройки PITR в существующей базе данных: datastore.databases.update , datastore.databases.list
  • Чтобы выполнить чтение данных PITR: datastore.databases.get , datastore.entities.get , datastore.entities.list
  • Чтобы экспортировать данные PITR: datastore.databases.export
  • Чтобы импортировать данные PITR: datastore.databases.import

Прежде чем вы начнете

Прежде чем начать использовать PITR, обратите внимание на следующие моменты:

  • Вы не можете начать чтение семи дней назад сразу после включения PITR.
  • Если вы хотите включить PITR при создании базы данных, вы должны использовать команду gcloud firestore databases create . Включение PITR при создании базы данных с помощью консоли GCP не поддерживается.
  • Cloud Firestore начинает сохранять версии с момента включения PITR.
  • Вы не сможете читать данные PITR в окне PITR после отключения PITR.
  • Если вы повторно включите PITR сразу после его отключения, прошлые данные PITR больше не будут доступны. Любые данные PITR, созданные до отключения PITR, будут удалены после истечения срока действия PITR.
  • Если вы случайно удалили данные за последний час, а PITR отключен, вы можете восстановить свои данные, включив PITR, в течение одного часа после удаления.
  • Любое чтение данных PITR с истекшим сроком действия завершается неудачно.

Включить ПИТР

Прежде чем использовать PITR, включите оплату для своего проекта Google Cloud . Только проекты Google Cloud с включенной оплатой могут использовать функцию PITR.

Чтобы включить PITR для вашей базы данных:

Консоль

  1. В консоли Google Cloud Platform перейдите на страницу «Базы данных» .

    Перейти к базам данных

  2. Выберите нужную базу данных из списка баз данных.

  3. В меню навигации нажмите Аварийное восстановление .

  4. Нажмите «Изменить» , чтобы изменить настройки.

  5. Установите флажок «Включить восстановление на определенный момент времени» и нажмите « Сохранить» .

Включение PITR повлечет за собой затраты на хранение. См. «Цены» для получения дополнительной информации.

Чтобы отключить PITR, снимите флажок «Включить восстановление на определенный момент времени» на странице «Аварийное восстановление» в консоли GCP.

gcloud

Включите PITR во время создания базы данных с помощью команды gcloud firestore databases create следующим образом:

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

Замените значения следующим образом:

  • Location — место, где вы хотите создать свою базу данных.
  • DATABASE_ID — устанавливается на идентификатор базы данных или (по умолчанию).
  • TYPE — установлен на Firestore-native.

Вы можете отключить PITR с помощью команды gcloud firestore databases update следующим образом:

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

Замените значения следующим образом:

  • DATABASE_ID — устанавливается на идентификатор базы данных или (по умолчанию).

Получите период хранения и время самой ранней версии.

Консоль

  1. В консоли Google Cloud Platform перейдите на страницу «Базы данных» .

    Перейти к базам данных

  2. Выберите нужную базу данных из списка баз данных.

  3. В меню навигации нажмите Аварийное восстановление .

  4. В разделе «Настройки» обратите внимание на «Период хранения» и «Время самой ранней версии» .

    • Период хранения : период, в течение которого Cloud Firestore сохраняет все версии данных для базы данных. Значение равно одному часу, когда PITR отключен, и семи дням, когда PITR включен.
    • Время самой ранней версии : самая ранняя временная метка, с которой более старые версии данных можно прочитать в окне PITR. Это значение постоянно обновляется Cloud Firestore и становится устаревшим в момент запроса. Если вы используете это значение для восстановления данных, обязательно учтите время с момента запроса значения до момента начала восстановления.
    • Восстановление на определенный момент времени : отображается Enabled , если PITR включен. Если PITR отключен, вы увидите Disabled .

gcloud

Запустите команду описания баз данных gcloud Firestore следующим образом:

gcloud firestore databases describe --database=DATABASE_ID

Замените DATABASE_ID идентификатором базы данных или default .

Вот результат:

    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: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

где,

  • earliestVersionTime — временная метка самых ранних сохраненных данных PITR.
  • pointInTimeRecoveryEnablement : показывает POINT_IN_TIME_RECOVERY_ENABLED , если PITR включен. Если PITR отключен, вы либо увидите POINT_IN_TIME_RECOVERY_DISABLED , либо поле pointInTimeRecoveryEnablement может не отображаться.
  • versionRetentionPeriod — период времени, в течение которого сохраняются данные PITR в миллисекундах. Значение может составлять один час, если PITR отключен, или семь дней, если PITR включен.

Чтение данных PITR

Вы можете читать данные PITR с помощью клиентских библиотек, методов REST API или коннектора FirestoreIO Apache Beam.

Клиентские библиотеки

Джава

Для чтения данных PITR необходимо использовать транзакцию ReadOnly . Вы не можете напрямую указать readTime при чтении. Дополнительные сведения см. в разделе Транзакции и пакетная запись .

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

Узел

Для чтения данных PITR необходимо использовать транзакцию ReadOnly . Вы не можете напрямую указать readTime при чтении. Дополнительные сведения см. в разделе Транзакции и пакетная запись .

  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

Чтения PITR поддерживаются во всех методах чтения Cloud Firestore, а именно get , list , atchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery иsectionQuery .

Чтобы выполнить чтение с использованием методов REST, попробуйте один из следующих вариантов:

  1. В запросе метода чтения передайте значение readTime как поддерживаемую временную метку PITR в методе readOptions . Временная метка PITR может быть либо временной меткой с точностью до микросекунды в течение последнего часа, либо временной меткой целой минуты за прошедший час, но не ранее, чем earliestVersionTime .

  2. Используйте параметр readTime вместе с методом BeginTransaction как часть транзакции ReadOnly для нескольких операций чтения PITR.

Апачский луч

Используйте коннектор Cloud FirestoreIO Apache Beam для чтения или записи документов в базе данных Cloud Firestore в больших масштабах с помощью Dataflow.

Чтения PITR поддерживаются следующим методом чтения соединителя Cloud FirestoreIO. Эти методы чтения поддерживают метод withReadTime(@Nullable Instant readTime) , который вы можете использовать для чтения PITR:

Джава

Следующий код можно использовать с примером кода конвейера потока данных для операций массового чтения или записи. В примере используется метод withReadTime(@Nullable Instant readTime) для чтения 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())
  ...

Полный список примеров readTime в конвейере Dataflow смотрите в репозитории Github .

Экспорт и импорт данных PITR

Вы можете экспортировать свою базу данных в Cloud Storage из данных PITR с помощью команды gcloud firestore export . Вы можете экспортировать данные PITR, где временная метка представляет собой целую минуту за последние семь дней, но не ранее самого earliestVersionTime . Если данные больше не существуют в указанную отметку времени, операция экспорта завершается неудачей.

Операция экспорта PITR поддерживает все фильтры, включая экспорт всех документов и экспорт определенных коллекций.

  1. Экспортируйте базу данных, указав в качестве параметра snapshot-time желаемую временную метку восстановления.

    gcloud

    Выполните следующую команду, чтобы экспортировать базу данных в корзину.

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

    Где,

    • BUCKET_NAME_PATH – допустимый сегмент Cloud Storage с необязательным префиксом пути, в котором хранятся файлы экспорта.
    • PITR_TIMESTAMP — временная метка PITR с точностью до минуты, например 2023-05-26T10:20:00.00Z или 2023-10-19T10:30:00.00-07:00 .
    • COLLECTION_IDS — список идентификаторов коллекций или идентификаторов групп коллекций, например 'specific collection group1' , 'specific collection group2' .
    • NAMESPACE_IDS — список идентификаторов пространств имен, например 'customer' , 'orders' .

    Прежде чем экспортировать данные PITR, обратите внимание на следующие моменты:

    • Укажите временную метку в формате RFC 3339 . Например, 2023-05-26T10:20:00.00Z или 2023-10-19T10:30:00.00-07:00 .
    • Убедитесь, что указанная вами временная метка представляет собой целую минуту за последние семь дней, но не раньше, чем earliestVersionTime . Если данные больше не существуют в указанную отметку времени, генерируется ошибка. Временная метка должна быть целой минутой, даже если указанное время находится в пределах последнего часа.
    • С вас не взимается плата за неудачный экспорт PITR.
  2. Импортировать в базу данных.

    Используйте шаги, описанные в разделе «Импорт всех документов» , чтобы импортировать экспортированную базу данных. Если какой-либо документ уже существует в вашей базе данных, он будет перезаписан.