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

Управляемый сервис экспорта и импорта позволяет восстанавливать случайно удаленные данные и экспортировать данные для обработки в офлайн-режиме. Вы можете экспортировать все документы или только определенные коллекции. Аналогично, вы можете импортировать все данные из экспорта или только определенные коллекции. Данные, экспортированные из одной базы данных 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, вы сможете импортировать документы из этих файлов обратно в свой проект или в другой проект. При импорте учитывайте следующее:

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

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

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

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

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

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

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

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

• При импорте в базу данных Cloud Firestore нельзя импортировать данные из пространств имен, отличных от стандартных (Datastore API).

  Импорт в базу данных Cloud Firestore из файлов данных, содержащих пространства имен, отличные от стандартных, разрешен, только если операция экспорта включала фильтр --namespace-ids со стандартным пространством имен. Импортируются только данные из пространства имен по умолчанию.

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

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_ID_1],[COLLECTION_ID_2] \
  --database=[DATABASE]

Импорт из экспорта с данными PITR

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

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

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

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

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

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

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

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

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

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

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

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

• Временная метка должна быть указана в формате RFC 3339. Пример: 2020-09-01T23:59:30.234233Z.
• Убедитесь, что указанная временная метка относится к целой минуте в течение последних семи дней, но не ранее earliestVersionTime. Если данные, соответствующие указанной временной метке, больше не существуют, будет возвращена ошибка.
• За неудачный экспорт PITR плата не взимается.

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

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

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

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

projects/my-project/databases/my-database/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…

При загрузке данных Cloud Firestore в BigQuery типы данных BSON представляются типом данных STRING.

Ограничение на количество столбцов: 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