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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Вы можете использовать управляемый экспорт и импорт 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 . Вы не можете использовать контейнер Requester Pays для операций экспорта и импорта.

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

   • Роли Cloud Firestore : 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 Platform с помощью 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_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
--database=[DATABASE]

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

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

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

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

1. Экспортируйте базу данных, указав параметр snapshot-time в соответствии с желаемой временной меткой восстановления.

   gcloud

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

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Где,

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

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

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

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

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

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

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

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

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

• Имя файла .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_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1] \
  --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 перейдите на страницу Базы данных .

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

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 Service Agent

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

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

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

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

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

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

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

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

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

5. Обратите внимание на основное имя агента службы Cloud Firestore вашего проекта. Имя агента службы отображается под Агентом службы, чтобы предоставить доступ к метке.

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

   1. В строке таблицы этого контейнера нажмите Fix . Это откроет страницу разрешений этого контейнера в новой вкладке.

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

7. Нажмите Migrate to Firestore Service Agent . Если у вас все еще есть контейнеры с не прошедшими проверку прав доступа, вам необходимо подтвердить миграцию, нажав Migrate .

   Оповещение сообщит вам, когда миграция будет завершена. Миграцию нельзя отменить.

Посмотреть статус миграции

Чтобы проверить статус миграции вашего проекта:

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

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

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

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

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

   Если принципал — service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , то ваш проект уже перенесен в агент службы Cloud Firestore . Миграция не может быть отменена.

   Если проект не был перенесен, в верхней части страницы появится баннер с кнопкой Check Bucket Status . См. Migrate to the Firestore service agent для завершения миграции.

Добавить ограничение политики на уровне всей организации

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

  Для импорта/экспорта требуется Firestore Service Agent ( firestore.requireP4SAforImportExport ).

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

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

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