Firebase 将于 5 月 14 日重返 Google I/O 大会！立即报名。

Эта страница переведена с помощью Cloud Translation API.

Работа с восстановлением на момент времени (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 для вашей базы данных:

Консоль

В консоли Google Cloud Platform перейдите на страницу «Базы данных» .
Перейти к базам данных
Выберите нужную базу данных из списка баз данных.
В меню навигации нажмите Аварийное восстановление .
Нажмите «Изменить» , чтобы изменить настройки.
Установите флажок «Включить восстановление на определенный момент времени» и нажмите « Сохранить» .

Включение 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 — устанавливается на идентификатор базы данных или (по умолчанию).

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

Консоль

В консоли Google Cloud Platform перейдите на страницу «Базы данных» .
Перейти к базам данных
Выберите нужную базу данных из списка баз данных.
В меню навигации нажмите Аварийное восстановление .
В разделе «Настройки» обратите внимание на «Период хранения» и «Время самой ранней версии» .
- Период хранения : период, в течение которого 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();

Узел

  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, попробуйте один из следующих вариантов:

В запросе метода чтения передайте значение readTime как поддерживаемую временную метку PITR в методе readOptions . Временная метка PITR может быть либо временной меткой с точностью до микросекунды в течение последнего часа, либо временной меткой целой минуты за прошедший час, но не ранее, чем earliestVersionTime .
Используйте параметр 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 поддерживает все фильтры, включая экспорт всех документов и экспорт определенных коллекций.

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