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

Вы можете использовать управляемую службу экспорта и импорта 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 Storage Cloud Firestore . Сервисный агент 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. Просмотрите учетную запись авторизации рядом с меткой « Задания импорта/экспорта, выполняемые от имени» .

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

Настройте 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_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
--database=[DATABASE]

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

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

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

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

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

• Укажите метку времени в формате RFC 3339. Например, 2023-05-26T10:20:00.00Z .
• Убедитесь, что указанная вами метка времени представляет собой целую минуту за последние семь дней, но не раньше, чем earliestVersionTime . Если данные на указанную метку времени больше не существуют, будет сгенерирована ошибка.
• За неудачный экспорт PITR с вас не взимается плата.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

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

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

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

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

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

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

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

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

  При перемещении или копировании выходных файлов экспорта сохраняйте неизменными имена файлов PARENT_FOLDER_NAME и .overall_export_metadata .

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

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

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

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

  gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ \
  --collection-ids=[COLLECTION_GROUP_ID_1],[COLLECTION_GROUP_ID_2] \
  --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

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

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

Агент службы Cloud Firestore

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

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

служебный аккаунт App Engine

PROJECT_ID @appspot.gserviceaccount.com

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

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

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

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

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

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

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

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

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

• Перенесите проект, проверив и обновив разрешения для сегмента Cloud Storage (рекомендуется) .
• Добавьте общеорганизационное ограничение политики , которое затрагивает все проекты в организации.

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

Для миграции проверьте и обновите разрешения для сегментов Cloud Storage

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

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

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

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

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

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

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

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

Перенесите проект в службу поддержки Firestore Service Agent.

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

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

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

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

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

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

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

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

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

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

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

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

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

7. Нажмите «Перенести в Firestore Service Agent» . Если у вас по-прежнему есть корзины с неудачными проверками разрешений, вам необходимо подтвердить перенос, нажав «Перенести» .

   Уведомление сообщит вам о завершении миграции. Миграцию отменить нельзя.

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

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

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

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

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

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

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

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

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

Добавьте общеорганизационное ограничение политики.

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

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

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

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

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