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

Вы можете использовать управляемую службу экспорта и импорта для восстановления данных после случайного удаления и для экспорта данных для автономной обработки. Вы можете экспортировать все документы или только определенные коллекции. Аналогично, вы можете импортировать все данные из экспорта или только определенные коллекции. Данные, экспортированные из одной базы данных 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. Create a Cloud Storage bucket for your project in a location near your Cloud Firestore database location . You cannot use a Requester Pays bucket or a Rapid 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 : Owner , Cloud Datastore Owner или Cloud Datastore Import Export Admin

   • Cloud Storage roles: Owner or Storage Admin

Service agent permissions

Для авторизации операций экспорта и импорта используется сервисный агент Cloud Storage Cloud Firestore . Сервисный агент Cloud Firestore использует следующую систему именования:

Cloud Firestore service agent

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

Чтобы узнать больше об агентах службы поддержки, см. раздел «Агенты службы поддержки» .

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 .

Если хранилище Cloud Storage находится в другом проекте, необходимо предоставить агенту службы Cloud Firestore доступ к Cloud Storage .

Assign roles to the service agent

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

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

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

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:

• Получите доступ gcloud из консоли Google Cloud , используя Cloud Shell .

  Запустить Cloud Shell

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

  gcloud config set project [PROJECT_ID]
  

• Install and initialize the Google Cloud SDK.

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

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

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

• Imports don't 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.

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

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

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

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

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

• Импорт данных из экспорта с использованием типов BSON в базу данных Firestore Standard Edition завершается неудачей, поскольку типы BSON не поддерживаются в Firestore Standard Edition.

• Импорт данных в базу данных Cloud Firestore невозможен из пространств имен, отличных от пространства имен по умолчанию (API Datastore ).

  An import to a Cloud Firestore database from data files that contain non-default namespaces is permitted only if the export operation included a --namespace-ids filter with the default namespace. Only data from the default namespace is imported.

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'

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

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

Импорт данных из экспорта с использованием PITR-данных.

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

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

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.

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

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

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

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

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

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

You can export your database to Cloud Storage from PITR data . 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.

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

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

• Укажите метку времени в формате RFC 3339. Например, 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.
• За неудачный экспорт PITR с вас не взимается плата.

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

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

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

Названия операций начинаются с префикса projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/ , например:

projects/my-project/databases/my-database/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 .

При загрузке данных Cloud Firestore в BigQuery типы данных BSON представляются с помощью типа данных STRING .

ограничение количества столбцов 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