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

Это относится только к версии Cloud Firestore Enterprise.

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

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

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

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

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

После экспорта файлов в 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.

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

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

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

Импорт всех документов из экспорта

Консоль Google Cloud

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

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

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

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

  4. Нажмите «Импорт» .

  5. В поле «Имя файла» введите имя файла .overall_export_metadata из завершенной операции экспорта. Для выбора файла можно использовать кнопку «Обзор» .

  6. Нажмите «Импорт» .

Консоль возвращает на страницу импорта/экспорта . Если операция начинается успешно, страница добавляет запись в список последних импортов и экспортов. В случае неудачи страница отображает сообщение об ошибке.

gcloud

Используйте команду firestore import для импорта документов из предыдущей операции экспорта.

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

Замените следующее:

  • BUCKET_NAME/EXPORT_PREFIX : местоположение ваших файлов экспорта.

  • DATABASE : название базы данных.

Например:

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

Вы можете подтвердить местоположение экспортированных файлов в браузере Cloud Storage в консоли Google Cloud:

Откройте браузер Cloud Storage

После начала операции импорта закрытие терминала не отменяет операцию (см. раздел «Отмена операции») .

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

Консоль Google Cloud

В консоли нельзя выбрать конкретные коллекции. Используйте gcloud .

gcloud

Для импорта определенных коллекций из набора файлов экспорта используйте флаг --collection-ids . Операция импортирует только коллекции с указанными идентификаторами. Укажите имя базы данных с помощью флага --database .

Импорт отдельных коллекций возможен только при экспорте определенных коллекций. Импорт отдельных коллекций при экспорте всех документов невозможен.

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

Импорт данных из экспорта с использованием PITR-данных.

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

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

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

Экспорт всех документов

Консоль Google Cloud

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

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

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

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

  4. Нажмите «Экспорт» .

  5. Нажмите кнопку «Экспорт всей базы данных» .

  6. Выберите «Экспорт текущего состояния базы данных» , чтобы экспортировать текущие данные.

  7. В разделе «Назначение» введите имя сегмента Cloud Storage или воспользуйтесь кнопкой «Обзор» , чтобы выбрать сегмент.

  8. Нажмите «Экспорт» .

Консоль возвращает на страницу импорта/экспорта . Если операция начинается успешно, страница добавляет запись в список последних импортов и экспортов. В случае неудачи страница отображает сообщение об ошибке.

gcloud

Используйте команду firestore export для экспорта всех документов из вашей базы данных, заменив [BUCKET_NAME] на имя вашего хранилища Cloud Storage . Добавьте флаг --async , чтобы инструмент gcloud не ожидал завершения операции.

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

Замените следующее:

  • BUCKET_NAME : упорядочите ваши экспорты, добавив префикс файла после имени корзины, например, BUCKET_NAME/my-exports-folder/export-name . Если вы не укажете префикс файла, служба управляемого экспорта создаст его на основе текущей метки времени.

  • DATABASE : имя базы данных, из которой вы хотите экспортировать документы.

После начала операции экспорта закрытие терминала не отменяет операцию (см. раздел «Отмена операции») .

Экспорт конкретных коллекций

Консоль Google Cloud

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

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

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

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

  4. Нажмите «Экспорт» .

  5. Нажмите кнопку «Экспорт одной или нескольких групп коллекций» . Используйте выпадающее меню, чтобы выбрать одну или несколько коллекций.

  6. Выберите «Экспорт текущего состояния базы данных» , чтобы экспортировать текущие данные.

  7. В разделе «Назначение» введите имя сегмента Cloud Storage или воспользуйтесь кнопкой «Обзор» , чтобы выбрать сегмент.

  8. Нажмите «Экспорт» .

Консоль возвращает на страницу импорта/экспорта . Если операция начинается успешно, страница добавляет запись в список последних импортов и экспортов. В случае неудачи страница отображает сообщение об ошибке.

gcloud

Для экспорта определенных коллекций используйте флаг --collection-ids . Операция экспортирует только коллекции с указанными идентификаторами.

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

Например, вы можете создать коллекцию restaurants в базе данных foo , включив в нее дополнительные коллекции, такие как ratings , reviews или outlets . Для экспорта конкретной коллекции restaurants и reviews ваша команда будет выглядеть следующим образом:

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 с вас не взимается плата.

Консоль

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

    Перейти к базам данных
  2. Выберите базу данных из списка баз данных.
  3. В меню навигации нажмите «Импорт/Экспорт» .
  4. Нажмите «Экспорт» .
  5. Настройте источник экспорта таким образом, чтобы экспортировалась либо вся база данных, либо только определенные коллекции.

  6. В разделе « Выберите состояние базы данных для экспорта» выберите «Экспорт из более раннего периода времени» .

    Выберите время создания снимка для экспорта.

  7. В разделе «Назначение» введите имя сегмента Cloud Storage или воспользуйтесь кнопкой «Обзор» , чтобы выбрать сегмент.

  8. Нажмите «Экспорт» .

    Консоль возвращает на страницу импорта/экспорта . Если операция начинается успешно, страница добавляет запись в список последних импортов и экспортов. В случае неудачи страница отображает сообщение об ошибке.

gcloud

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

Экспортируйте базу данных, указав параметр snapshot-time в качестве метки времени восстановления. Выполните следующую команду, чтобы экспортировать базу данных в ваш сегмент.

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

Где PITR_TIMESTAMP — это метка времени PITR с точностью до минуты, например, 2023-05-26T10:20:00.00Z .

Добавьте флаг --collection-ids для экспорта определенных коллекций.

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

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

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

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

Перечислите все операции по экспорту и импорту.

Консоль Google Cloud

Список последних операций экспорта и импорта можно просмотреть на странице «Импорт/Экспорт» в консоли Google Cloud.

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

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

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

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

gcloud

Используйте команду operations list , чтобы просмотреть все запущенные и недавно завершенные операции экспорта и импорта: 

gcloud firestore operations list

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

Консоль Google Cloud

Статус недавней операции экспорта или импорта можно просмотреть на странице «Импорт/Экспорт» в консоли Google Cloud.

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

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

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

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

gcloud

Используйте команду operations describe , чтобы отобразить статус операции экспорта или импорта. 

gcloud firestore operations describe [OPERATION_NAME]

Оцените время выполнения.

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

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

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

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

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

Консоль Google Cloud

Отменить выполняющуюся операцию экспорта или импорта можно на странице «Импорт/Экспорт» в консоли Google Cloud.

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

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

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

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

В таблице «Недавние импорты и экспорты» в столбце «Завершено» отображаются выполняемые операции, в том числе кнопка «Отмена» . Нажмите кнопку «Отмена» , чтобы остановить операцию. После полной остановки операции кнопка изменится на сообщение «Отмена» , а затем на «Отменено» .

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

gcloud

Используйте команду operations cancel , чтобы остановить выполняющуюся операцию: 

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 вы можете использовать эту метку для просмотра затрат, связанных с операциями импорта и экспорта:

Доступ к метке goog-firestoremanaged можно получить из меню фильтров.

Экспорт в 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