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

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

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

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

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

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

• Имя файла .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.

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

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

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

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

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

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

   Нажмите «Проверить статус сегмента» .

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

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

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

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

   1. В строке таблицы этого сегмента нажмите «Исправить» . Страница разрешений этого сегмента откроется на новой вкладке.

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

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

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

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

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

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

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

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

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

4. Найдите участника рядом с заданиями импорта/экспорта, выполняемыми как метка.

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

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

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

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

  Для импорта/экспорта требуется агент службы Firestore ( firestore.requireP4SAforImportExport ).

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

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

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

Вы можете использовать службу управляемого экспорта и импорта 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'

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

Вы можете экспортировать свою базу данных в Cloud Storage из Pitr Data, используя команду gcloud firestore export . Вы можете экспортировать данные PITR, где TimeStamp - это целая минутная метка времени в течение последних семи дней, но не ранее, чем 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 -Например, метка TimeSterity Pitr в минуту, 2023-05-26T10:20:00.00Z .

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

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

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

После того, как у вас есть экспортные файлы в 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 .

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

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]

Счетные расходы и цены на экспортные и импортные операции

Вы должны включить выставление счетов за свой Project Google Cloud Project, прежде чем использовать Управляемый сервис экспорта и импорта.

Экспортные и импортные операции взимаются за чтение документов и записываются по тарифам, перечисленным в ценах на Cloud Firestore . Экспортные операции несут одну операцию чтения на экспорт документа. Импортные операции несут одну операцию записи на импорт документа.

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

Затраты на экспортные и импортные операции не учитываются до предела расходов . Экспортные или импортные операции не запускают ваши предупреждения о Google Cloud до завершения. Точно так же чтения и записи, выполняемые во время экспортной или импортной операции, применяются к вашей ежедневной квоте после завершения операции. Экспортные и импортные операции не повлияют на использование, показанное в разделе использования консоли.

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

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

Экспорт в 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 ранее использовал учетную запись Service Service App Engine по умолчанию вместо сервисного агента Cloud Firestore . Если ваша база данных по -прежнему использует учетную запись Service App Engine для импорта или экспорта данных, мы рекомендуем вам следовать инструкциям в этом разделе, чтобы перейти на использование сервисного агента Cloud Firestore .

Аккаунт сервиса App Engine

PROJECT_ID @appspot.gserviceaccount.com

Сервисный агент Cloud Firestore предпочтительнее, потому что он специфичен для Cloud Firestore . Аккаунт сервиса App Engine разделяется более чем одним сервисом.

Просмотреть учетную запись авторизации

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

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

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

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

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

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

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

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

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

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

   Нажмите «Проверьте статус ведра» .

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

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

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

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

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

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

7. Нажмите «Мигрировать» в агент обслуживания Firestore . Если у вас все еще есть ведра без неудачных проверок разрешений, вам необходимо подтвердить миграцию, нажав мигрировать .

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

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

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

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

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

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

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

4. Ищите принципал рядом с заданиями импорта/экспорта, работающего в качестве метки.

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

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

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

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

  Требуется агент по обслуживанию Firestore для импорта/экспорта ( firestore.requireP4SAforImportExport ).

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

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

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

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

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

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

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

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

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 . Чтобы просмотреть имя агента службы, см. Имя Agent View Service .

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

Просмотреть имя агента службы

Вы можете просмотреть учетную запись, которую ваши операции импорта и экспорта используют для авторизации запросов со страницы импорта/экспорта в облачной консоли Google. Вы также можете просмотреть, использует ли ваша база данных сервисный агент Cloud Firestore или учетную запись Service 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'

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

Вы можете экспортировать свою базу данных в Cloud Storage из Pitr Data, используя команду gcloud firestore export . Вы можете экспортировать данные PITR, где TimeStamp - это целая минутная метка времени в течение последних семи дней, но не ранее, чем 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 -Например, метка TimeSterity Pitr в минуту, 2023-05-26T10:20:00.00Z .

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

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

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

После того, как у вас есть экспортные файлы в 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 .

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

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

Используйте шаги в импорте всех документов для импорта вашей экспортируемой базы данных. If any document already exists in your database, it will be overwritten.

Managing export and import operations

After you start an export or import operation, Cloud Firestore assigns the operation a unique name. You can use the operation name to delete, cancel, or status check the operation.

Operation names are prefixed with projects/[PROJECT_ID]/databases/(default)/operations/ , for example:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

However, you can leave out the prefix when specifying an operation name for the describe , cancel , and delete commands.

List all export and import operations

gcloud firestore operations list

Check operation status

gcloud firestore operations describe [OPERATION_NAME]

Estimate the completion time

A request for the status of a long-running operation returns the metrics workEstimated and workCompleted . Each of these metrics is returned in both number of bytes and number of entities:

• workEstimated shows the estimated total number of bytes and documents an operation will process. Cloud Firestore might omit this metric if it cannot make an estimate.

• workCompleted shows the number of bytes and documents processed so far. After the operation completes, the value shows the total number of bytes and documents that were actually processed, which might be larger than the value of workEstimated .

Divide workCompleted by workEstimated for a rough progress estimate. This estimate might be inaccurate, because it depends on delayed statistics collection.

Cancel an operation

gcloud firestore operations cancel [OPERATION_NAME]

Cancelling a running operation does not undo the operation. A cancelled export operation will leave documents already exported in Cloud Storage , and a cancelled import operation will leave in place updates already made to your database. You cannot import a partially completed export.

Delete an operation

Use the gcloud firestore operations delete command to remove an operation from the list of recent operations. This command will not delete export files from Cloud Storage .

gcloud firestore operations delete [OPERATION_NAME]

Billing and pricing for export and import operations

You are required to enable billing for your Google Cloud project before you use the managed export and import service.

Export and import operations are charged for document reads and writes at the rates listed in Cloud Firestore pricing . Export operations incur one read operation per document exported. Import operations incur one write operation per document imported.

Output files stored in Cloud Storage count towards your Cloud Storage data storage costs .

The costs of export and import operations do not count towards your spending limit . Export or import operations will not trigger your Google Cloud budget alerts until after completion. Similarly, reads and writes performed during an export or import operation are applied to your daily quota after the operation is complete. Export and import operations will not affect the usage shown in the usage section of the console.

Viewing export and import costs

Export and import operations apply the goog-firestoremanaged:exportimport label to billed operations. In the Cloud Billing reports page , you can use this label to view costs related to import and export operations:

Export to BigQuery

You can load data from a Cloud Firestore export into BigQuery , but only if you specified a collection-ids filter. See Loading data from Cloud Firestore exports .

BigQuery column limit

BigQuery imposes a limit of 10,000 columns per table. Cloud Firestore export operations generate a BigQuery table schema for each collection group. In this schema, each unique field name within a collection group becomes a schema column.

If a collection group's BigQuery schema surpasses 10,000 columns, the Cloud Firestore export operation attempts to stay under the column limit by treating map fields as bytes. If this conversion brings the number of columns below 10,000, you can load the data into BigQuery , but you cannot query the subfields within the map fields. If the number of columns still exceeds 10,000, the export operation does not generate a BigQuery schema for the collection group and you cannot load its data into BigQuery .

Export format and metadata files

The output of a managed export uses the LevelDB log format .

Metadata files

An export operation creates a metadata file for each collection group you specify. Metadata files are typically named ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata .

The metadata files are protocol buffers and you can decode them with the protoc protocol compiler . For example, you can decode a metadata file to determine the collection groups the export files contain:

protoc --decode_raw < export0.export_metadata

Service agent migration

Cloud Firestore uses a Cloud Firestore service agent to authorize import and export operations instead of using the App Engine service account. The service agent and service account use the following naming conventions:

Cloud Firestore service agent

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore previously used the App Engine default service account instead of the Cloud Firestore service agent. If your database still uses the App Engine service account to import or export data, we recommend that you follow the instructions in this section to migrate to using the Cloud Firestore service agent.

App Engine service account

PROJECT_ID @appspot.gserviceaccount.com

The Cloud Firestore service agent is preferable because it is specific to Cloud Firestore . The App Engine service account is shared by more than one service.

View authorization account

You can view which account your import and export operations use to authorize requests from the Import/Export page in the Google Cloud console. You can also view if your database already uses the Cloud Firestore service agent.

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. View the authorization account next to the Import/Export jobs run as label.

If your project does not use the Cloud Firestore service agent, you can migrate to the Cloud Firestore service agent using either of these techniques:

• Migrate a project by checking and updating Cloud Storage bucket permissions (recommended) .
• Add an organization-wide policy constraint that affects all projects within the organization.

The first of these techniques is preferable because it localizes the scope of effect to a single Cloud Firestore project. The second technique is not preferred because it doesn't migrate existing Cloud Storage bucket permissions. It does, however, offer security compliance at the organization level.

Migrate by checking and updating Cloud Storage bucket permissions

The migration process has two steps:

1. Update Cloud Storage bucket permissions. See the following section for details.
2. Confirm migration to the Cloud Firestore service agent.

Service agent bucket permissions

For any export or import operations that use a Cloud Storage bucket in another project, you must grant the Cloud Firestore service agent permissions for that bucket. For example, operations that move data to another project need to access a bucket in that other project. Otherwise, these operations fail after migrating to the Cloud Firestore service agent.

Import and export workflows that stay within the same project do not require changes to permissions. The Cloud Firestore service agent can access buckets in the same project by default.

Update the permissions for Cloud Storage buckets from other projects to give access to the service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com service agent. Grant the service agent the Firestore Service Agent role.

The Firestore Service Agent role grants read and write permissions for a Cloud Storage bucket. If you need to grant only read or only write permissions, use a custom role .

The migration process described in the following section helps you identify Cloud Storage buckets that might require permission updates.

Migrate a project to the Firestore Service Agent

Complete the following steps to migrate from the App Engine service account to the Cloud Firestore service agent. Once completed, the migration can't be undone.

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. If your project has not yet migrated to the Cloud Firestore service agent, you see a banner describing the migration and a Check Bucket Status button. The next step helps you identify and fix potential permission errors.

   Click Check Bucket Status .

   A menu appears with the option to complete your migration and a list of Cloud Storage buckets. It may take a few minutes for the list to finish loading.

   This list includes buckets which were recently used in import and export operations, but do not currently give read and write permissions to the Cloud Firestore service agent.

5. Take note of the principal name of your project's Cloud Firestore service agent. The service agent name appears under the Service agent to give access to label.

6. For any bucket in the list that you will use for future import or export operations, complete the following steps:

   1. In this bucket's table row, click Fix . This opens that bucket's permissions page in a new tab.

   2. Click Add .
   3. In the New principals field, enter the name of your Cloud Firestore service agent.
   4. In the Select a role field, select Service Agents > Firestore Service Agent .
   5. Нажмите Сохранить .
   6. Return to the tab with the Cloud Firestore Import/Export page.
   7. Repeat these steps for other buckets in the list. Make sure to view all the pages of the list.

7. Click Migrate to Firestore Service Agent . If you still have buckets with failed permission checks, you need to confirm your migration by clicking Migrate .

   An alert informs you when your migration completes. Migration can't be undone.

View migration status

To verify your project's migration status:

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. Look for the principal next to the Import/Export jobs run as label.

   If the principal is service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , then your project has already migrated to the Cloud Firestore service agent. The migration can't be undone.

   If the project has not been migrated, a banner appears at the top of the page with a Check Bucket Status button. See Migrate to the Firestore service agent to complete the migration.

Add an organization-wide policy constraint

• Set the following constraint in your organization's policy:

  Require Firestore Service Agent for import/export ( firestore.requireP4SAforImportExport ).

  This constraint requires import and export operations to use the Cloud Firestore service agent to authorize requests. To set this constraint, see Creating and managing organization policies .

Applying this organizational policy constraint does not automatically grant the appropriate Cloud Storage bucket permissions for the Cloud Firestore service agent.

If the constraint creates permission errors for any import or export workflows, you can disable it to go back to using default service account. After you check and update Cloud Storage bucket permissions , you can enable the constraint again.

You can use the Cloud Firestore managed export and import service to recover from accidental deletion of data and to export data for offline processing. You can export all documents or just specific collections. Likewise, you can import all data from an export or only specific collections. Data exported from one Cloud Firestore database can be imported into another Cloud Firestore database. You can also load Cloud Firestore exports into BigQuery .

This page describes how to export and import Cloud Firestore documents using the managed export and import service and Cloud Storage . The Cloud Firestore managed export and import service is available through the gcloud command-line tool and the Cloud Firestore API ( REST , RPC ).

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

Before you can use the managed export and import service, you must complete the following tasks:

1. Enable billing for your Google Cloud project. Only Google Cloud projects with billing enabled can use the export and import functionality.
2. Create a Cloud Storage bucket for your project in a location near your Cloud Firestore database location . You cannot use a Requester Pays bucket for export and import operations.

3. Make sure your account has the necessary permissions for Cloud Firestore and Cloud Storage . If you are the project owner, your account has the required permissions. Otherwise, the following roles grant the necessary permissions for export and import operations and for access to Cloud Storage :

   • Cloud Firestore roles: Owner , Cloud Datastore Owner , or Cloud Datastore Import Export Admin

   • Cloud Storage roles: Owner or Storage Admin

Service agent permissions

Export and import operations use a Cloud Firestore service agent to authorize Cloud Storage operations. The Cloud Firestore service agent uses the following naming convention:

Cloud Firestore service agent

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

To learn more about service agents, see Service agents .

The Cloud Firestore service agent requires access to the Cloud Storage bucket used in an export or import operation. If your Cloud Storage bucket is in the same project as your Cloud Firestore database, then the Cloud Firestore service agent can access the bucket by default .

If the Cloud Storage bucket is in another project, then you must give the Cloud Firestore service agent access to the Cloud Storage bucket.

Assign roles to the service agent

You can use the gsutil command-line tool to assign one of the roles below. For example, to assign the Storage Admin role to the Cloud Firestore service agent, run the following:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Replace PROJECT_NUMBER with your project number, which is used to name your Cloud Firestore service agent. To view the service agent name, see View service agent name .

Alternatively, you can assign this role using the Google Cloud console .

View service agent name

You can view the account that your import and export operations use to authorize requests from the Import/Export page in the Google Cloud console. You can also view whether your database uses the Cloud Firestore service agent or the legacy App Engine service account.

1. View the authorization account next to the Import/Export jobs run as label.

The service agent needs the Storage Admin role for the Cloud Storage bucket to be used for the export or import operation.

Set up gcloud for your project

You can initiate import and export operations through the Google Cloud console or the gcloud command-line tool. To use gcloud , set up the command-line tool and connect to your project in one of the following ways:

• Access gcloud from the Google Cloud Platform console using Cloud Shell .

  Start Cloud Shell

  Make sure gcloud is configured for the correct project:

  gcloud config set project [PROJECT_ID]
  

• Install and initialize the Google Cloud SDK.

Export data

An export operation copies documents in your database to a set of files in a Cloud Storage bucket. Note that an export is not an exact database snapshot taken at the export start time. An export may include changes made while the operation was running.

Export all documents

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

Export specific collections

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'

Export from a PITR timestamp

You can export your database to Cloud Storage from PITR data using the gcloud firestore export command. You can export PITR data where the timestamp is a whole minute timestamp within the past seven days, but not earlier than the earliestVersionTime . If data no longer exists at the specified timestamp, the export operation fails.

The PITR export operation supports all filters, including exporting all documents and exporting specific collections.

1. Export the database, specifying the snapshot-time parameter to the desired recovery timestamp.

   gcloud

   Run the following command to export the database to your bucket.

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

   Где,

   • PITR_TIMESTAMP - a PITR timestamp at the minute granularity, for example, 2023-05-26T10:20:00.00Z .

   Note the following points before exporting PITR data:

   • Specify the timestamp in RFC 3339 format . For example, 2020-09-01T23:59:30.234233Z .
   • Make sure that the timestamp you specify is a whole minute timestamp within the past seven days, but not earlier than the earliestVersionTime . If data no longer exists at the specified timestamp, an error is generated.
   • You are not charged for a failed PITR export.

Import data

Once you have export files in Cloud Storage , you can import documents in those files back into your project or to another project. Note the following points about import operations:

• When you import data, the required indexes are updated using your database's current index definitions. An export does not contain index definitions.

• Imports do not assign new document IDs. Imports use the IDs captured at the time of the export. As a document is being imported, its ID is reserved to prevent ID collisions. If a document with the same ID already exists, the import overwrites the existing document.

• If a document in your database is not affected by an import, it will remain in your database after the import.

• Import operations do not trigger Cloud Functions. Snapshot listeners do receive updates related to import operations.

• The .overall_export_metadata file name must match the name of its parent folder:

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

  If you move or copy the output files of an export, keep the PARENT_FOLDER_NAME and .overall_export_metadata file name the same.

Import all documents from an export

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

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

Import specific collections

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

Import a PITR export

Use the steps in Import all documents to import your exported database. If any document already exists in your database, it will be overwritten.

Managing export and import operations

After you start an export or import operation, Cloud Firestore assigns the operation a unique name. You can use the operation name to delete, cancel, or status check the operation.

Operation names are prefixed with projects/[PROJECT_ID]/databases/(default)/operations/ , for example:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

However, you can leave out the prefix when specifying an operation name for the describe , cancel , and delete commands.

List all export and import operations

gcloud firestore operations list

Check operation status

gcloud firestore operations describe [OPERATION_NAME]

Estimate the completion time

A request for the status of a long-running operation returns the metrics workEstimated and workCompleted . Each of these metrics is returned in both number of bytes and number of entities:

• workEstimated shows the estimated total number of bytes and documents an operation will process. Cloud Firestore might omit this metric if it cannot make an estimate.

• workCompleted shows the number of bytes and documents processed so far. After the operation completes, the value shows the total number of bytes and documents that were actually processed, which might be larger than the value of workEstimated .

Divide workCompleted by workEstimated for a rough progress estimate. This estimate might be inaccurate, because it depends on delayed statistics collection.

Cancel an operation

gcloud firestore operations cancel [OPERATION_NAME]

Cancelling a running operation does not undo the operation. A cancelled export operation will leave documents already exported in Cloud Storage , and a cancelled import operation will leave in place updates already made to your database. You cannot import a partially completed export.

Delete an operation

Use the gcloud firestore operations delete command to remove an operation from the list of recent operations. This command will not delete export files from Cloud Storage .

gcloud firestore operations delete [OPERATION_NAME]

Billing and pricing for export and import operations

You are required to enable billing for your Google Cloud project before you use the managed export and import service.

Export and import operations are charged for document reads and writes at the rates listed in Cloud Firestore pricing . Export operations incur one read operation per document exported. Import operations incur one write operation per document imported.

Output files stored in Cloud Storage count towards your Cloud Storage data storage costs .

The costs of export and import operations do not count towards your spending limit . Export or import operations will not trigger your Google Cloud budget alerts until after completion. Similarly, reads and writes performed during an export or import operation are applied to your daily quota after the operation is complete. Export and import operations will not affect the usage shown in the usage section of the console.

Viewing export and import costs

Export and import operations apply the goog-firestoremanaged:exportimport label to billed operations. In the Cloud Billing reports page , you can use this label to view costs related to import and export operations:

Export to BigQuery

You can load data from a Cloud Firestore export into BigQuery , but only if you specified a collection-ids filter. See Loading data from Cloud Firestore exports .

BigQuery column limit

BigQuery imposes a limit of 10,000 columns per table. Cloud Firestore export operations generate a BigQuery table schema for each collection group. In this schema, each unique field name within a collection group becomes a schema column.

If a collection group's BigQuery schema surpasses 10,000 columns, the Cloud Firestore export operation attempts to stay under the column limit by treating map fields as bytes. If this conversion brings the number of columns below 10,000, you can load the data into BigQuery , but you cannot query the subfields within the map fields. If the number of columns still exceeds 10,000, the export operation does not generate a BigQuery schema for the collection group and you cannot load its data into BigQuery .

Export format and metadata files

The output of a managed export uses the LevelDB log format .

Metadata files

An export operation creates a metadata file for each collection group you specify. Metadata files are typically named ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata .

The metadata files are protocol buffers and you can decode them with the protoc protocol compiler . For example, you can decode a metadata file to determine the collection groups the export files contain:

protoc --decode_raw < export0.export_metadata

Service agent migration

Cloud Firestore uses a Cloud Firestore service agent to authorize import and export operations instead of using the App Engine service account. The service agent and service account use the following naming conventions:

Cloud Firestore service agent

service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com

Cloud Firestore previously used the App Engine default service account instead of the Cloud Firestore service agent. If your database still uses the App Engine service account to import or export data, we recommend that you follow the instructions in this section to migrate to using the Cloud Firestore service agent.

App Engine service account

PROJECT_ID @appspot.gserviceaccount.com

The Cloud Firestore service agent is preferable because it is specific to Cloud Firestore . The App Engine service account is shared by more than one service.

View authorization account

You can view which account your import and export operations use to authorize requests from the Import/Export page in the Google Cloud console. You can also view if your database already uses the Cloud Firestore service agent.

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. View the authorization account next to the Import/Export jobs run as label.

If your project does not use the Cloud Firestore service agent, you can migrate to the Cloud Firestore service agent using either of these techniques:

• Migrate a project by checking and updating Cloud Storage bucket permissions (recommended) .
• Add an organization-wide policy constraint that affects all projects within the organization.

The first of these techniques is preferable because it localizes the scope of effect to a single Cloud Firestore project. The second technique is not preferred because it doesn't migrate existing Cloud Storage bucket permissions. It does, however, offer security compliance at the organization level.

Migrate by checking and updating Cloud Storage bucket permissions

The migration process has two steps:

1. Update Cloud Storage bucket permissions. See the following section for details.
2. Confirm migration to the Cloud Firestore service agent.

Service agent bucket permissions

For any export or import operations that use a Cloud Storage bucket in another project, you must grant the Cloud Firestore service agent permissions for that bucket. For example, operations that move data to another project need to access a bucket in that other project. Otherwise, these operations fail after migrating to the Cloud Firestore service agent.

Import and export workflows that stay within the same project do not require changes to permissions. The Cloud Firestore service agent can access buckets in the same project by default.

Update the permissions for Cloud Storage buckets from other projects to give access to the service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com service agent. Grant the service agent the Firestore Service Agent role.

The Firestore Service Agent role grants read and write permissions for a Cloud Storage bucket. If you need to grant only read or only write permissions, use a custom role .

The migration process described in the following section helps you identify Cloud Storage buckets that might require permission updates.

Migrate a project to the Firestore Service Agent

Complete the following steps to migrate from the App Engine service account to the Cloud Firestore service agent. Once completed, the migration can't be undone.

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. If your project has not yet migrated to the Cloud Firestore service agent, you see a banner describing the migration and a Check Bucket Status button. The next step helps you identify and fix potential permission errors.

   Click Check Bucket Status .

   A menu appears with the option to complete your migration and a list of Cloud Storage buckets. It may take a few minutes for the list to finish loading.

   This list includes buckets which were recently used in import and export operations, but do not currently give read and write permissions to the Cloud Firestore service agent.

5. Take note of the principal name of your project's Cloud Firestore service agent. The service agent name appears under the Service agent to give access to label.

6. For any bucket in the list that you will use for future import or export operations, complete the following steps:

   1. In this bucket's table row, click Fix . This opens that bucket's permissions page in a new tab.

   2. Click Add .
   3. In the New principals field, enter the name of your Cloud Firestore service agent.
   4. In the Select a role field, select Service Agents > Firestore Service Agent .
   5. Нажмите Сохранить .
   6. Return to the tab with the Cloud Firestore Import/Export page.
   7. Repeat these steps for other buckets in the list. Make sure to view all the pages of the list.

7. Click Migrate to Firestore Service Agent . If you still have buckets with failed permission checks, you need to confirm your migration by clicking Migrate .

   An alert informs you when your migration completes. Migration can't be undone.

View migration status

To verify your project's migration status:

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Select the required database from the list of databases.

3. In the navigation menu, click Import/Export .

4. Look for the principal next to the Import/Export jobs run as label.

   If the principal is service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , then your project has already migrated to the Cloud Firestore service agent. The migration can't be undone.

   If the project has not been migrated, a banner appears at the top of the page with a Check Bucket Status button. See Migrate to the Firestore service agent to complete the migration.

Add an organization-wide policy constraint

• Set the following constraint in your organization's policy:

  Require Firestore Service Agent for import/export ( firestore.requireP4SAforImportExport ).

  This constraint requires import and export operations to use the Cloud Firestore service agent to authorize requests. To set this constraint, see Creating and managing organization policies .

Applying this organizational policy constraint does not automatically grant the appropriate Cloud Storage bucket permissions for the Cloud Firestore service agent.

If the constraint creates permission errors for any import or export workflows, you can disable it to go back to using default service account. After you check and update Cloud Storage bucket permissions , you can enable the constraint again.