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

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

   • Роли облачного хранилища: 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 .

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

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

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

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 Platform перейдите на страницу «Базы данных» .

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

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 Platform перейдите на страницу «Базы данных» .

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

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 , вы сможете снова включить ограничение.