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

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

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

Прежде чем начать

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

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

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

   • Роли совместимости Cloud Firestore с MongoDB: Owner , Cloud Datastore Owner или Cloud Datastore Import Export Admin

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

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

Операции экспорта и импорта используют агент службы Cloud Firestore для авторизации операций Cloud Storage . Агент службы 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 с совместимостью с MongoDB из экспорта с подколлекциями завершается ошибкой, поскольку подколлекции не поддерживаются в Cloud Firestore с совместимостью с MongoDB.

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

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

  Импорт в базу данных Cloud Firestore с совместимостью с MongoDB из файлов данных, содержащих пространства имён, отличные от пространств имён по умолчанию, разрешён только в том случае, если операция экспорта включала фильтр --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

Чтобы импортировать данные 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, совместимый с MongoDB, присваивает ей уникальное имя. Имя операции можно использовать для её удаления, отмены или проверки статуса.

Имена операций начинаются с 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 с совместимостью с MongoDB может не учитывать эту метрику, если не может выполнить оценку.

• 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 и MongoDB .

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

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

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

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

Экспорт в BigQuery

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

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

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

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

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

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

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

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

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

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

protoc --decode_raw < export0.export_metadata