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

Вы можете использовать управляемый сервис экспорта и импорта Cloud Firestore, чтобы восстанавливать случайно удаленные данные и экспортировать данные для обработки в офлайн-режиме. Вы можете экспортировать все документы или только определенные группы коллекций. Аналогично, вы можете импортировать все данные из экспорта или только определенные группы коллекций. Данные, экспортированные из одной базы данных Cloud Firestore, можно импортировать в другую базу данных Cloud Firestore. Вы также можете загрузить экспортированные данные Cloud Firestore в BigQuery.

В этой статье рассказывается, как экспортировать и импортировать документы Cloud Firestore с помощью управляемого сервиса экспорта и импорта и Cloud Storage. Управляемый сервис экспорта и импорта Cloud Firestore доступен через инструмент командной строки gcloud и API Cloud Firestore (REST, RPC).

Подготовка

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

1. Включите платежные функции для проекта Google Cloud. Функции экспорта и импорта доступны только в проектах Google Cloud с включенными платежными функциями.
2. Создайте сегмент Cloud Storage для проекта в регионе, расположенном рядом с регионом базы данных Cloud Firestore. Для операций экспорта и импорта нельзя использовать сегменты Rapid и сегменты, за которые платит запрашивающая сторона.

3. Убедитесь, что у вашего аккаунта есть необходимые разрешения для Cloud Firestore и Cloud Storage. Если вы владелец проекта, у вашего аккаунта есть необходимые разрешения. В противном случае необходимые разрешения для экспорта и импорта, а также для доступа к Cloud Storage предоставляют следующие роли:

   • Роли Cloud Firestore: Owner, Cloud Datastore Owner или Cloud Datastore Import Export Admin.

   • Роли в Cloud Storage: Owner или Storage Admin

Разрешения агента сервиса

Для авторизации операций Cloud Storage при экспорте и импорте используется сервисный агент Cloud Firestore. Агент сервиса Cloud Firestore использует следующее соглашение об именовании:

Агент сервиса Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Подробнее о сервисных агентах…

Агенту сервиса Cloud Firestore требуется доступ к сегменту Cloud Storage, используемому в операции экспорта или импорта. Если сегмент Cloud Storage находится в том же проекте, что и база данных Cloud Firestore, то агент сервиса Cloud Firestore может получить доступ к сегменту по умолчанию.

Если сегмент Cloud Storage находится в другом проекте, необходимо предоставить агенту сервиса Cloud Firestore доступ к сегменту Cloud Storage.

Назначьте роли агенту сервиса

Вы можете назначить одну из перечисленных ниже ролей с помощью инструмента командной строки gsutil. Например, чтобы назначить роль администратора хранилища сервисному агенту Cloud Firestore, выполните следующую команду:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Замените PROJECT_NUMBER номером своего проекта, который используется для названия агента сервиса Cloud Firestore. Чтобы узнать название агента сервиса, ознакомьтесь с разделом Как посмотреть название агента сервиса.

Вы также можете назначить эту роль в консоли Google Cloud.

Посмотреть название агента сервиса

Посмотреть, какой аккаунт используется для авторизации запросов на импорт и экспорт, можно на странице Импорт/экспорт в консоли Google Cloud. Вы также можете посмотреть, использует ли ваша база данных агент сервиса Cloud Firestore или устаревший сервисный аккаунт App Engine.

1. Посмотрите, какой аккаунт указан рядом с надписью Задания импорта/экспорта выполняются от имени.

Агенту сервиса требуется роль Storage Admin для сегмента Cloud Storage, который будет использоваться для операции экспорта или импорта.

Настройте gcloud для своего проекта

Вы можете инициировать операции импорта и экспорта через консоль Google Cloud или инструмент командной строки gcloud. Чтобы использовать gcloud, настройте инструмент командной строки и подключитесь к проекту одним из следующих способов:

• Откройте gcloud в консоли Google Cloud с помощью Cloud Shell.

  Начать Cloud Shell

  Убедитесь, что gcloud настроен для нужного проекта:

  gcloud config set project [PROJECT_ID]
  

• Установите и инициализируйте Google Cloud SDK.

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

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

Экспортировать все документы

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Как экспортировать определенные группы коллекций

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
--database=[DATABASE]

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=reviews \
--database='cymbal'

Экспорт из временной метки PITR

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

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

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

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

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Импорт данных

После того как вы экспортируете файлы в Cloud Storage, вы сможете импортировать документы из этих файлов обратно в свой проект или в другой проект. При импорте учитывайте следующее:

• При импорте данных необходимые индексы обновляются с использованием текущих определений индексов вашей базы данных. Экспорт не содержит определений индексов.

• При импорте документам не назначаются новые идентификаторы. При импорте используются идентификаторы, зафиксированные во время экспорта. При импорте документа его идентификатор резервируется, чтобы избежать конфликтов. Если документ с таким же идентификатором уже существует, он будет перезаписан.

• Если документ в вашей базе данных не затронут импортом, он останется в вашей базе данных после импорта.

• Операции импорта не запускают Cloud Functions. Прослушиватели снимков получают обновления, связанные с операциями импорта.

• Не добавляйте новые документы Cloud Firestore, которых не было в исходных файлах экспорта, и не удаляйте существующие документы из файлов GCS перед импортом. В противном случае импорт не будет выполнен.

• Название файла .overall_export_metadata должно совпадать с названием родительской папки.

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  Если вы перемещаете или копируете выходные файлы экспорта, не меняйте названия файлов PARENT_FOLDER_NAME и .overall_export_metadata.

Как импортировать все документы из экспорта

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Импорт определенных групп коллекций

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
  --database=[DATABASE]

Как импортировать экспорт PITR

Чтобы импортировать экспортированную базу данных, выполните действия, описанные в разделе Импорт всех документов. Если в базе данных уже есть документ, он будет перезаписан.

Управление операциями экспорта и импорта

После запуска операции экспорта или импорта Cloud Firestore присваивает ей уникальное название. С помощью названия операции можно удалить или отменить ее, а также проверить ее статус.

Названия операций начинаются с префикса projects/[PROJECT_ID]/databases/(default)/operations/, например:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Однако при указании названия операции для команд describe, cancel и delete префикс можно опустить.

Как посмотреть список всех операций экспорта и импорта

gcloud firestore operations list

Проверить статус операции

gcloud firestore operations describe [OPERATION_NAME]

Оценка времени завершения

Запрос статуса продолжительной операции возвращает показатели workEstimated и workCompleted. Каждый из этих показателей возвращается как в количестве байтов, так и в количестве объектов:

• workEstimated показывает расчетное общее количество байтов и документов, которые будут обработаны в ходе операции. Cloud Firestore может не показывать этот показатель, если его невозможно рассчитать.

• workCompleted – количество обработанных байтов и документов. После завершения операции значение показывает общее количество байтов и документов, которые были фактически обработаны. Оно может быть больше значения workEstimated.

Разделите значение "workCompleted" на workEstimated, чтобы получить приблизительную оценку прогресса. Эта оценка может быть неточной, поскольку она зависит от сбора статистики, который выполняется с задержкой.

Как отменить операцию

gcloud firestore operations cancel [OPERATION_NAME]

Отмена выполняемой операции не отменяет ее. При отмене экспорта документы, которые уже были экспортированы, останутся в Cloud Storage, а при отмене импорта – в базе данных. Вы не можете импортировать частично завершенный экспорт.

Как удалить операцию

Чтобы удалить операцию из списка недавних, используйте команду gcloud firestore operations delete. Эта команда не удалит файлы экспорта из Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Оплата и цены для операций экспорта и импорта

Прежде чем использовать управляемый сервис экспорта и импорта, необходимо включить оплату для проекта Google Cloud.

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

Выходные файлы, хранящиеся в Cloud Storage, учитываются при расчете стоимости хранения данных в Cloud Storage.

Оповещения о бюджете Google Cloud не будут срабатывать до завершения операций экспорта или импорта. Операции экспорта и импорта не влияют на статистику использования, которая показывается в соответствующем разделе консоли.

Просмотр расходов на экспорт и импорт

К операциям экспорта и импорта применяется ярлык goog-firestoremanaged:exportimport. На странице отчетов об оплате Cloud Billing вы можете использовать этот ярлык, чтобы просматривать расходы, связанные с операциями импорта и экспорта.

Экспорт в BigQuery

Вы можете загрузить данные из экспорта Cloud Firestore в BigQuery, но только если вы указали фильтр collection-ids. Подробнее о том, как загружать данные из экспортированных файлов Cloud Firestore…

Ограничение на количество столбцов: BigQuery

В BigQuery действует ограничение в 10 000 столбцов на таблицу. Операции экспорта Cloud Firestore генерируют схему таблицы BigQuery для каждой группы коллекций. В этой схеме каждое уникальное имя поля в группе коллекций становится столбцом схемы. Если схема BigQuery группы коллекций превышает 10 000 столбцов,операция экспорта Cloud Firestore пытается не превысить ограничение на количество столбцов, обрабатывая поля карты как байты. Если после этого количество столбцов станет меньше 10 000, вы сможете загрузить данные в BigQuery, но не сможете запрашивать подполя в полях карты. Если количество столбцов по-прежнему превышает 10 000, то при экспорте не будет создана схема BigQuery для группы коллекций и вы не сможете загрузить ее данные в BigQuery.

Формат экспорта и файлы метаданных

Выходные данные управляемого экспорта используют формат журнала LevelDB.

Файлы метаданных

При экспорте для каждой указанной группы коллекций создается файл метаданных. Обычно файлы метаданных называются ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

Файлы метаданных представляют собой буферы протокола, которые можно декодировать с помощью компилятора протокола protoc. Например, вы можете декодировать файл метаданных, чтобы определить, какие группы коллекций содержатся в экспортированных файлах:

protoc --decode_raw < export0.export_metadata

Перенос агента сервиса

Для авторизации операций импорта и экспорта Cloud Firestore использует сервисный агент Cloud Firestore, а не сервисный аккаунт App Engine. Для агента и аккаунта сервиса используются следующие соглашения об именовании:

Агент сервиса Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Ранее в Cloud Firestore использовался сервисный аккаунт App Engine по умолчанию, а не сервисный агент Cloud Firestore. Если в вашей базе данных для импорта или экспорта данных по-прежнему используется сервисный аккаунт App Engine, рекомендуем следовать инструкциям в этом разделе, чтобы перейти на использование сервисного агента Cloud Firestore.

Сервисный аккаунт App Engine

PROJECT_ID@appspot.gserviceaccount.com

Агент сервиса Cloud Firestore предпочтительнее, поскольку он предназначен специально для Cloud Firestore. Сервисный аккаунт App Engine используется несколькими сервисами.

Посмотреть аккаунт авторизации

Посмотреть, какой аккаунт используется для авторизации запросов на импорт и экспорт, можно на странице Импорт/экспорт в консоли Google Cloud. Вы также можете посмотреть, использует ли ваша база данных агент сервиса Cloud Firestore.

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

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

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

3. В меню навигации нажмите Импорт/экспорт.

4. Посмотрите, какой аккаунт указан рядом с надписью Задания импорта/экспорта выполняются от имени.

Если в вашем проекте не используется агент сервиса Cloud Firestore, вы можете перейти на Cloud Firestore него одним из следующих способов:

• Перенесите проект, проверив и обновив разрешения для сегмента Cloud Storage (рекомендуется).
• Добавьте ограничение на уровне организации, которое будет действовать для всех проектов в ней.

Первый способ предпочтительнее, поскольку он ограничивает область действия одним проектом Cloud Firestore. Второй способ не рекомендуется, поскольку при его использовании не переносятся существующие разрешения для сегмента Cloud Storage. Однако он обеспечивает соответствие требованиям безопасности на уровне организации.

Проверьте и обновите разрешения для сегментов Cloud Storage

Процесс переноса состоит из двух этапов:

1. Обновите разрешения для сегмента Cloud Storage. Подробная информация приведена в следующем разделе.
2. Подтвердите перенос в агент сервиса Cloud Firestore.

Разрешения агента сервиса для сегмента

Для любых операций экспорта или импорта, в которых используется сегмент Cloud Storage в другом проекте, необходимо предоставить агенту сервиса Cloud Firestore разрешения для этого сегмента. Например, для операций, которые перемещают данные в другой проект, требуется доступ к сегменту в этом проекте. В противном случае после перехода на агент сервиса Cloud Firestore эти операции будут завершаться ошибкой.

Если вы импортируете и экспортируете рабочие процессы в рамках одного проекта, менять разрешения не нужно. По умолчанию агент сервиса Cloud Firestore может получать доступ к сегментам в том же проекте.

Обновите разрешения для сегментов Cloud Storage из других проектов, чтобы предоставить доступ агенту сервиса service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com. Назначьте сервисному агенту роль Firestore Service Agent.

Роль Firestore Service Agent предоставляет разрешения на чтение и запись для сегмента Cloud Storage. Если вам нужно предоставить только разрешение на чтение или только разрешение на запись, используйте специальную роль.

Процесс переноса, описанный в следующем разделе, поможет вам определить, для каких сегментов Cloud Storage может потребоваться обновить разрешения.

Как перенести проект в агент сервиса Firestore

Чтобы перейти с сервисного аккаунта App Engine на сервисный агент Cloud Firestore, выполните следующие действия: После завершения переноса отменить его нельзя.

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

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

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

3. В меню навигации нажмите Импорт/экспорт.

4. Если ваш проект ещё не перенесен на агент сервиса Cloud Firestore, вы увидите баннер с описанием переноса и кнопку Проверить статус сегмента. Следующий шаг поможет вам выявить и устранить потенциальные ошибки, связанные с разрешениями.

   Нажмите Проверить статус сегмента.

   Появится меню с возможностью завершить перенос и списком сегментов Cloud Storage. Загрузка списка может занять несколько минут.

   В этом списке перечислены сегменты, которые недавно использовались для импорта и экспорта, но в настоящее время не предоставляют агенту сервиса Cloud Firestore разрешения на чтение и запись.

5. Запишите имя субъекта сервисного агента Cloud Firestore вашего проекта. Название агента сервиса указано под меткой Агент сервиса, которому нужно предоставить доступ.

6. Для каждого сегмента в списке, который вы будете использовать для будущих операций импорта или экспорта, выполните следующие действия:

   1. В строке таблицы, относящейся к этому сегменту, нажмите Исправить. В новой вкладке откроется страница разрешений для этого сегмента.

   2. Нажмите Добавить.
   3. В поле Новые субъекты введите название сервисного агента Cloud Firestore.
   4. В поле Выберите роль выберите Агенты сервисов > Агент сервиса Firestore.
   5. Нажмите Сохранить.
   6. Вернитесь на вкладку со страницей импорта/экспорта Cloud Firestore.
   7. Повторите эти действия для других сегментов в списке. Проверьте все страницы списка.

7. Нажмите Migrate to Firestore Service Agent (Перейти на агент сервиса Firestore). Если у вас все ещё есть сегменты, не прошедшие проверку разрешений, вам нужно подтвердить перенос, нажав Перенести.

   Когда перенос завершится, вы получите оповещение. Перенос нельзя отменить.

Как посмотреть статус переноса

Чтобы проверить статус переноса проекта:

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

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

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

3. В меню навигации нажмите Импорт/экспорт.

4. Найдите пользователя рядом с меткой Задания импорта/экспорта выполняются от имени.

   Если субъект – service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, значит проект уже перенесен на агент сервиса Cloud Firestore. Отменить перенос нельзя.

   Если проект не был перенесен, в верхней части страницы появится баннер с кнопкой Проверить статус сегмента. Чтобы завершить перенос, ознакомьтесь с инструкциями по переносу в агент сервиса Firestore.

Как добавить ограничение правил на уровне организации

• Задайте в правилах организации следующее ограничение:

  Требовать агент сервиса Firestore для импорта и экспорта (firestore.requireP4SAforImportExport).

  Это ограничение требует, чтобы операции импорта и экспорта использовали агент сервиса Cloud Firestore для авторизации запросов. Инструкции приведены в статье Создание правил организации и управление ими .

Применение этого ограничения организационных правил не предоставляет автоматически соответствующие разрешения для сегмента Cloud Storage агенту сервиса Cloud Firestore.

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