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

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

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

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

Подготовка

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

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.
     Примечание. Эти роли в Datastore также предоставляют разрешения в Cloud Firestore.

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

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

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

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

[e-mail]

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

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

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

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

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

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

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

gsutil iam ch serviceAccount:[e-mail]:roles/storage.admin \
    gs://[BUCKET_NAME]

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

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

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

Посмотреть, какой аккаунт используется для авторизации запросов на импорт и экспорт, можно на странице Import/Export (Импорт/экспорт) в консоли 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 с пространством имен по умолчанию. Импортируются только данные из пространства имен по умолчанию.

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

Google Cloud Console

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

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

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

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

4. Нажмите Импортировать.

5. В поле Filename (Название файла) введите название файла .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 Console

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

Примечание. Вам нужно экспортировать определенные коллекции, если вы планируете:

• Как импортировать только определенные коллекции
• Загрузка данных Cloud Firestore в BigQuery

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

Google Cloud Console

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

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

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

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

4. Нажмите Export (Экспортировать).

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

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

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

8. Нажмите Export (Экспортировать).

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

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 Console

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

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

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

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

4. Нажмите Export (Экспортировать).

5. Нажмите Экспортировать одну или несколько групп коллекций. В раскрывающемся меню выберите одну или несколько подборок.

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

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

8. Нажмите Export (Экспортировать).

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

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

• Включите восстановление на определенный момент времени в базе данных. Если восстановление на определенный момент времени отключено, экспорт с временной меткой снимка не удастся, даже если метка относится к последнему часу после earliestVersionTime. Операция экспорта возвращает ошибку Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
• Временная метка должна быть указана в формате RFC 3339. Пример: 2020-09-01T23:59:30.234233Z.
• Убедитесь, что указанная временная метка относится к целой минуте в течение последних семи дней, но не ранее earliestVersionTime. Если данные, соответствующие указанной временной метке, больше не существуют, будет сгенерирована ошибка.
• За неудачный экспорт на определенный момент времени плата не взимается.

Консоль

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

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

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

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

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

8. Нажмите Export (Экспортировать).

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

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 присваивает ей уникальное название. С помощью названия операции можно удалить или отменить ее, а также проверить ее статус.

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

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

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

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

Google Cloud Console

Список недавних операций экспорта и импорта можно посмотреть на странице Import/Export (Импорт/экспорт) в консоли Google Cloud.

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

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

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

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

gcloud

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

gcloud firestore operations list

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

Google Cloud Console

Статус недавней операции экспорта или импорта можно посмотреть на странице Import/Export (Импорт/экспорт) в консоли Google Cloud.

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

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

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

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

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

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

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

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

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

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

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

Google Cloud Console

Вы можете отменить выполняемую операцию экспорта или импорта на странице Import/Export (Импорт/экспорт) в консоли Google Cloud.

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

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

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.

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

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

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

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

Примечание. К операциям экспорта и импорта, выполненным до 8 сентября 2020 г., ярлык goog-firestoremanaged не применялся.

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