导出和导入数据

您可以使用 Firestore 代管式导出和导入服务来恢复意外删除的数据,并导出数据以供离线处理。您可以导出所有文档或仅导出特定的集合。同样,您也可以导入所有导出数据或仅导入特定的集合。从一个 Firestore 数据库导出的数据可导入另一个 Firestore 数据库中。您还可以将 Firestore 导出文件加载到 BigQuery 中

本页面介绍如何使用代管式导出和导入服务以及 Cloud Storage 来导出和导入 Firestore 文档。可通过 gcloud 命令行工具和 Firestore API (RESTRPC ) 使用 Firestore 代管式导出和导入服务。

准备工作

您必须先完成以下任务,才能使用代管式导出和导入服务:

  1. 为 Google Cloud 项目启用结算功能。只有启用了结算功能的 Google Cloud 项目才能使用导出和导入功能。
  2. Firestore 数据库位置附近为项目创建一个 Cloud Storage 存储分区。您不能使用“请求者付款”存储分区执行导出和导入操作。
  3. 确保您的帐号拥有 Firestore 和 Cloud Storage 的必要权限。如果您是项目所有者,那么您的帐号将具有所需权限。如果不是,可使用以下角色授予必要的导出和导入操作权限以及访问 Cloud Storage 的权限:

    • Firestore 角色OwnerCloud Datastore OwnerCloud Datastore Import Export Admin
    • Cloud Storage 角色OwnerStorage Admin

默认服务帐号权限

每个 Google Cloud 项目都会自动创建一个名为 PROJECT_ID@appspot.gserviceaccount.com 的默认服务帐号。导出和导入操作使用此服务帐号授权 Cloud Storage 操作。

您的项目的默认服务帐号需要访问导出或导入操作中使用的 Cloud Storage 存储分区。如果您的 Cloud Storage 存储分区与您的 Firestore 数据库位于同一项目中,则默认情况下,默认服务帐号能够访问该存储分区

如果 Cloud Storage 存储分区位于其他项目中,则您必须为默认服务帐号授予对 Cloud Storage 存储分区的访问权限。

服务帐号需要使用 Cloud Storage 存储分区的 Storage Admin 角色才能执行导出或导入操作。

如果您停用或删除 App Engine 默认服务帐号,您的 App Engine 应用将无法访问 Firestore 数据库。 如果您停用了 App Engine 服务帐号,则可以重新启用该帐号,请参阅启用服务帐号。如果您在过去 30 天内删除了 App Engine 服务帐号,则可以恢复服务帐号,请参阅取消删除服务帐号

为您的项目设置 gcloud

设置 gcloud 命令行工具,并通过以下任一方式关联到您的项目:

导出数据

导出操作会将数据库中的文档复制到 Cloud Storage 存储分区中的一组文件。请注意,所导出的并不是导出开始那一刻截取的数据库快照,导出内容可能包括在操作过程中对数据库所做的变更。

导出所有文档

使用 firestore export 命令导出数据库中的所有文档,将 [BUCKET_NAME] 替换为 Cloud Storage 存储分区的名称。添加 --async 标志可阻止 gcloud 工具等待操作完成。

gcloud firestore export gs://[BUCKET_NAME]

您可以通过在存储分区名称后面添加文件前缀来整理导出的内容,例如 BUCKET_NAME/my-exports-folder/export-name。如果您不提供文件前缀,代管式导出服务会根据当前时间戳创建一个。

导出操作一旦启动就无法通过关闭终端来取消,具体请参阅取消操作

导出特定集合

如需导出特定集合组,请使用 --collection-ids 标志。该操作仅导出具有指定集合 ID 的集合组。集合组包含具有指定集合 ID 的所有集合和子集合(在任意路径中)。

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

导入数据

文件导出到 Cloud Storage 中后,您可以将这些文件中的文档重新导入原项目或其他项目。请注意关于导入操作的以下几点事项:

  • 在您导入数据时,系统将使用数据库当前的索引定义来更新所需的索引。导出的数据不包含索引定义。

  • 导入操作不分配新的文档 ID,而是使用导出时捕获的 ID。在导入文档时,系统会保留其 ID 以防止 ID 冲突。如果已存在具有相同 ID 的文档,则导入操作将覆盖现有文档。

  • 如果数据库中某个文档未受到导入的影响,导入后该文档将保留在您的数据库中。

  • 导入操作不会触发 Cloud Functions。快照监听器会接收与导入操作相关的更新。

导入某次导出的所有文档

使用 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/

您可以在 Google Cloud Console 的 Cloud Storage 浏览器中确认导出文件的位置:

打开 Cloud Storage 浏览器

导入操作一旦启动就无法通过关闭终端来取消,具体请参阅取消操作

导入特定集合

如需从一组导出文件中导入特定的集合组,请使用 --collection-ids 标志。该操作仅导入具有指定集合 ID 的集合组。集合组包含具有指定集合 ID 的所有集合和子集合(在任意路径中)。

只有包含特定集合组的导出文件支持导入特定集合组。您无法从包含所有文档的导出文件中导入特定的集合。

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

管理导出和导入操作

在您启动导出或导入操作后,Firestore 会为操作分配唯一的名称。您可以使用操作名称来删除、取消操作或检查操作状态。

操作名称的前缀为 projects/[PROJECT_ID]/databases/(default)/operations/,例如:

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

不过,您可以在指定 describecanceldelete 命令的操作名称时省略前缀。

列出所有导出和导入操作

使用 operations list 命令可查看所有正在运行和最近完成的导出和导入操作:

gcloud firestore operations list

查看操作状态

使用 operations describe 命令可显示导出或导入操作的状态。

gcloud firestore operations describe [OPERATION_NAME]

预估完成时间

用于获取运行时间较长的操作状态的请求会返回指标 workEstimatedworkCompleted。返回的这两个指标均包含字节数和实体数。

  • workEstimated 表示操作将处理的预估总字节数和文档数。

  • workCompleted 表示目前已处理的字节数和文档数。 操作完成后,该值会显示实际处理的总字节数和总文档数,可能大于 workEstimated 的值。

workCompleted 除以 workEstimated 可得出粗略的进度估算值。该估算值可能不准确,因为它所依据的是延迟的统计信息收集操作。

取消操作

使用 operations cancel 命令可停止正在进行的操作:

gcloud firestore operations cancel [OPERATION_NAME]

取消正在进行的操作并不会撤消操作。取消的导出操作会在 Cloud Storage 中留下已导出的文档,而取消的导入操作会留下已对数据库进行的更新。您无法导入部分完成的导出文件。

删除操作

使用 operations delete 命令可移除 operations list 输出中的某项操作。此命令不会从 Cloud Storage 中删除导出文件。

gcloud firestore operations delete [OPERATION_NAME]

导出和导入操作的计费与价格

在使用代管式导出和导入服务前,您需要为 Google Cloud 项目启用结算功能。对于导出和导入操作,您需按 Firestore 价格中列出的费率支付文档读写费用。

导出和导入操作的费用不计入您的支出限额。导出或导入操作在完成之前不会触发 Google Cloud 预算提醒。同样,在导出或导入操作期间执行的读写会在操作完成后计入您的每日配额。 导出和导入操作不会影响控制台的“使用量”部分中显示的使用量。

审核日志

Firestore 会针对 Cloud Audit Logs 写入管理员活动审核日志。管理员活动审核日志包含导出操作、导入操作和索引操作。如需查看 Firestore 数据库的管理员活动审核日志,请参阅查看审核日志

Firestore 管理员活动审核日志显示在 Cloud Datastore DatabaseCloud Datastore Index 资源类型下。虽然资源类型使用 Cloud Datastore 名称,但各个日志条目包含 Firestore 标识符。Firestore 会记录以下操作:

审核日志类别 Firestore 操作
管理员活动 FirestoreAdmin.CreateIndex
FirestoreAdmin.DeleteIndex
FirestoreAdmin.ExportDocuments
FirestoreAdmin.GetField
FirestoreAdmin.GetIndex
FirestoreAdmin.ImportDocuments
FirestoreAdmin.ListFields
FirestoreAdmin.ListIndexes
FirestoreAdmin.UpdateField

导出到 BigQuery

您可以将 Firestore 导出文件中的数据加载到 BigQuery,但前提是您指定了 collection-ids 过滤条件。请参阅从 Firestore 导出文件中加载数据

BigQuery 列限制

BigQuery 对表格施加的列数上限为 10000。Firestore 导出操作会为每个集合组生成 BigQuery 表格架构。在此架构中,集合组中的每个唯一字段名称都会变为架构列。

如果集合组的 BigQuery 架构超过 10000 列,则 Firestore 导出操作会尝试将映射字段视为字节,从而保持在列限制以下。如果此转化使列数低于 10000,您可以将数据加载到 BigQuery 中,但无法查询映射字段中的子字段。如果列数仍然超过 10000,则导出操作不会为该集合组生成 BigQuery 架构,而且您无法将其数据加载到 BigQuery 中。