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

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

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

Прежде чем вы начнете

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

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

Разрешения учетной записи службы по умолчанию

Каждый проект Google Cloud автоматически создает учетную запись службы по умолчанию с именем PROJECT_ID @appspot.gserviceaccount.com . Операции экспорта и импорта используют эту учетную запись службы для авторизации операций облачного хранилища.

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

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

Учетной записи службы требуется роль Storage Admin для корзины Cloud Storage, которая будет использоваться для операции экспорта или импорта.

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

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

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

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

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

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

Облачная консоль Google

  1. Перейдите на страницу импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

    Перейти на страницу импорта/экспорта

  2. Щелкните Экспорт .

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

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

  5. Щелкните Экспорт .

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

gcloud

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

gcloud firestore export gs://[BUCKET_NAME]

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

После запуска операции экспорта закрытие терминала не отменяет операцию, см. Отмена операции .

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

Облачная консоль Google

  1. Перейдите на страницу импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

    Перейти на страницу импорта/экспорта

  2. Щелкните Экспорт .

  3. Щелкните параметр Экспортировать одну или несколько групп коллекций . Используйте раскрывающееся меню, чтобы выбрать одну или несколько групп коллекций.

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

  5. Щелкните Экспорт .

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

gcloud

Чтобы экспортировать определенные группы коллекций, используйте флаг --collection-ids . Операция экспортирует только группы коллекций с заданными идентификаторами коллекций. Группа коллекций включает все коллекции и вложенные коллекции (по любому пути) с указанным идентификатором коллекции.

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

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

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

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

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

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

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

  • Имя файла .overall_export_metadata должно совпадать с именем его родительской папки:

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

    Если вы перемещаете или копируете выходные файлы экспорта, оставьте имена файлов PARENT_FOLDER_NAME и .overall_export_metadata одинаковыми.

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

Облачная консоль Google

  1. Перейдите на страницу импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

    Перейти на страницу импорта/экспорта

  2. Щелкните Импорт .

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

  4. Щелкните Импорт .

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

gcloud

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

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

где [BUCKET_NAME] и [EXPORT_PREFIX] указывают на расположение файлов экспорта. Например:

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

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

Откройте браузер облачного хранилища

После запуска операции импорта закрытие терминала не отменяет операцию, см. Отмена операции .

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

Облачная консоль Google

Вы не можете выбрать определенные коллекции в консоли. Вместо этого используйте gcloud .

gcloud

Чтобы импортировать определенные группы коллекций из набора файлов экспорта, используйте флаг --collection-ids . Операция импортирует только группы коллекций с заданными идентификаторами коллекций. Группа коллекций включает все коллекции и вложенные коллекции (по любому пути) с указанным идентификатором коллекции.

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

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

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

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

Имена операций имеют префикс projects/[PROJECT_ID]/databases/(default)/operations/ , например:

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

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

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

Облачная консоль Google

Вы можете просмотреть список последних операций экспорта и импорта на странице импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

Перейти на страницу импорта/экспорта

gcloud

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

gcloud firestore operations list

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

Облачная консоль Google

Вы можете просмотреть статус последней операции экспорта или импорта на странице импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

Перейти на страницу импорта/экспорта

gcloud

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

gcloud firestore operations describe [OPERATION_NAME]

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

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

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

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

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

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

Облачная консоль Google

Вы можете отменить текущую операцию экспорта или импорта на странице импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

Перейти на страницу импорта/экспорта

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

gcloud

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

gcloud firestore operations cancel [OPERATION_NAME]

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

Удалить операцию

Используйте команду gcloud firestore operations delete , чтобы удалить операцию из списка последних операций. Эта команда не удалит файлы экспорта из облачного хранилища.

gcloud firestore operations delete [OPERATION_NAME]

Выставление счетов и ценообразование при экспортно-импортных операциях

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

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

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

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

Получите доступ к ярлыку goog-firestoremanaged из меню фильтров.

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

Агент службы Cloud Firestore
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
Учетная запись службы App Engine
project_id @appspot.gserviceaccount.com

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

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

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

  1. Перейдите на страницу импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

    Перейти к импорту/экспорту

  2. Просмотрите учетную запись авторизации рядом с ярлыком Задания импорта/экспорта, выполняемые от имени.

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

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

Мигрируйте, проверив и обновив разрешения сегмента Cloud Storage.

Процесс миграции состоит из двух этапов:

  1. Обновите разрешения сегмента Cloud Storage. Подробнее см. в следующем разделе.
  2. Подтвердите переход на сервисный агент Cloud Firestore.

Разрешения сегмента агента службы

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

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

Обновите разрешения для сегментов Cloud Storage из других проектов, чтобы предоставить доступ сервисному агенту service- service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Предоставьте агенту службы роль агента Firestore Service Agent .

Роль Firestore Service Agent предоставляет разрешения на чтение и запись для корзины облачного хранилища. Если вам нужно предоставить права только на чтение или только на запись, используйте пользовательскую роль .

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

Перенос проекта в агент службы Firestore

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

  1. Перейдите на страницу импорта/экспорта Cloud Firestore в консоли Google Cloud Platform.

    Перейти к импорту/экспорту

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

    Щелкните Проверить состояние сегмента .

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

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

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

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

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

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

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

  1. Чтобы проверить статус переноса вашего проекта, перейдите на страницу импорта/экспорта в консоли Google Cloud Platform:

    Перейти к импорту/экспорту

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

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

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

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

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

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

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

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

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