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

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

   • Роли Cloud Firestore: Owner , Cloud Datastore Owner или Cloud Datastore Import Export Admin

   • Роли облачного хранилища: 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. Чтобы просмотреть имя агента службы, см. раздел Просмотр имени агента службы .

Кроме того, вы можете назначить эту роль с помощью консоли GCP .

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

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

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

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

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

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

• Получите доступ к gcloud из консоли Google Cloud Platform с помощью Cloud Shell .

  Запустить облачную оболочку

  Убедитесь, что gcloud настроен для правильного проекта:

  gcloud config set project [PROJECT_ID]
  

• Установите и инициализируйте Google Cloud SDK.

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

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

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

gcloud firestore export gs://[BUCKET_NAME]

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

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 одинаковыми.

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

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

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

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

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 .

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

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]

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

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

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

gcloud firestore operations delete [OPERATION_NAME]

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

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

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

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

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

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

Если в вашем проекте не используется агент службы 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, для которых могут потребоваться обновления разрешений.

Перенос проекта в агент службы 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- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com , то ваш проект уже перенесен на агент службы Cloud Firestore. Миграцию нельзя отменить.

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

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

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

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

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

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

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