获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

导出和导入数据

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

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

在你开始之前

在使用托管导出和导入服务之前,您必须完成以下任务:

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

默认服务帐号权限

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

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

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

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

如果您禁用或删除 App Engine 默认服务帐户,您的 App Engine 应用将失去对 Cloud Firestore 数据库的访问权限。如果您禁用了 App Engine 服务帐户,您可以重新启用它,请参阅启用服务帐户。如果您在过去 30 天内删除了 App Engine 服务帐户,则可以恢复您的服务帐户,请参阅取消删除服务帐户

为您的项目设置gcloud

您可以通过 Google Cloud Platform Console 或gcloud命令行工具启动导入和导出操作。要使用gcloud ,请设置命令行工具并通过以下方式之一连接到您的项目:

导出数据

导出操作会将数据库中的文档复制到 Cloud Storage 存储分区中的一组文件中。请注意,导出不是在导出开始时拍摄的精确数据库快照。导出可能包括在操作运行时所做的更改。

导出所有文件

谷歌云控制台

  1. 转到 Google Cloud Platform Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出页面

  2. 单击导出

  3. 单击导出整个数据库选项。

  4. 选择目标下方,输入 Cloud Storage 存储分区的名称或使用浏览按钮选择一个存储分区。

  5. 单击导出

控制台返回导入/导出页面。如果操作成功启动,该页面会在最近的导入和导出页面中添加一个条目。失败时,页面会显示错误消息。

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

gcloud firestore export gs://[BUCKET_NAME]

您可以通过在存储桶名称后添加文件前缀来组织导出,例如BUCKET_NAME/my-exports-folder/export-name 。如果您不提供文件前缀,则托管导出服务会根据当前时间戳创建一个。

启动导出操作后,关闭终端不会取消操作,请参阅取消操作

导出特定集合

谷歌云控制台

  1. 转到 Google Cloud Platform Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出页面

  2. 单击导出

  3. 单击导出一个或多个集合组选项。使用下拉菜单选择一个或多个集合组。

  4. 选择目标下方,输入 Cloud Storage 存储分区的名称或使用浏览按钮选择一个存储分区。

  5. 单击导出

控制台返回导入/导出页面。如果操作成功启动,该页面会在最近的导入和导出页面中添加一个条目。失败时,页面会显示错误消息。

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

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

导入数据

在 Cloud Storage 中导出文件后,您可以将这些文件中的文档导入回您的项目或其他项目。请注意有关导入操作的以下几点:

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

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

  • 如果您的数据库中的文档不受导入的影响,则导入后它将保留在您的数据库中。

  • 导入操作不会触发 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文件名相同。

从导出中导入所有文档

谷歌云控制台

  1. 转到 Google Cloud Platform Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出页面

  2. 单击导入

  3. 文件名字段中,输入已完成导出操作的.overall_export_metadata文件的文件名。您可以使用浏览按钮来帮助您选择文件。

  4. 单击导入

控制台返回导入/导出页面。如果操作成功启动,该页面会在最近的导入和导出页面中添加一个条目。失败时,页面会显示错误消息。

使用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 Platform Console 的 Cloud Storage 浏览器中确认导出文件的位置:

打开云存储浏览器

一旦开始导入操作,关闭终端并不会取消操作,请参阅取消操作

导入特定集合

谷歌云控制台

您无法在控制台中选择特定集合。请改用gcloud

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

只有特定集合组的导出支持特定集合组的导入。您不能从所有文档的导出中导入特定集合。

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

但是,在为describecanceldelete命令指定操作名称时,您可以省略前缀。

列出所有导出和导入操作

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 导入/导出页面中查看最近的导出和导入操作列表。

转到导入/导出页面

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

gcloud firestore operations list

检查运行状态

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 导入/导出页面中查看最近导出或导入操作的状态。

转到导入/导出页面

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

gcloud firestore operations describe [OPERATION_NAME]

估计完成时间

对长时间运行操作状态的请求会返回指标workEstimatedworkCompleted 。这些指标中的每一个都以字节数和实体数返回:

  • workEstimated显示操作将处理的估计总字节数和文档。如果 Cloud Firestore 无法做出估计,它可能会忽略此指标。

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

workCompleted除以workEstimated以获得粗略的进度估计。此估计可能不准确,因为它取决于延迟的统计信息收集。

取消操作

谷歌云控制台

您可以在 Google Cloud Platform Console 的Cloud Firestore 导入/导出页面中取消正在运行的导出或导入操作。

转到导入/导出页面

最近的导入和导出表中,当前运行的操作在已完成列中包括一个取消按钮。单击取消按钮停止操作。当操作完全停止时,该按钮变为取消消息,然后变为取消

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

gcloud firestore operations cancel [OPERATION_NAME]

取消正在运行的操作不会撤消该操作。取消的导出操作将保留已在 Cloud Storage 中导出的文档,取消的导入操作将保留已对您的数据库进行的更新。您不能导入部分完成的导出。

删除操作

使用gcloud firestore operations delete命令从最近操作列表中删除操作。此命令不会从 Cloud Storage 中删除导出文件。

gcloud firestore operations delete [OPERATION_NAME]

进出口业务的计费和定价

在使用托管导出和导入服务之前,您需要为您的 GCP 项目启用结算功能。导出和导入操作按Cloud Firestore 定价中列出的费率收取文档读取和写入费用。

进出口业务的费用不计入您的支出限额。导出或导入操作在完成之前不会触发您的Google Cloud 预算提醒。同样,在导出或导入操作期间执行的读取和写入操作将在操作完成后应用到您的每日配额。导出和导入操作不会影响控制台使用部分显示的使用情况。

查看进出口成本

导出和导入操作将goog-firestoremanaged:exportimport标签应用于计费操作。在Cloud Billing 报告页面中,您可以使用此标签查看与导入和导出操作相关的费用:

从过滤器菜单访问 goog-firestoremanaged 标签。

导出到 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 服务代理来授权导入和导出操作,而不是使用 App Engine 服务帐号。服务代理和服务帐户使用以下命名约定:

Cloud Firestore 服务代理
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
App Engine 服务帐号
project_id @appspot.gserviceaccount.com

Cloud Firestore 服务代理更可取,因为它特定于 Cloud Firestore。 App Engine 服务帐号由多个服务共享。

查看授权账号

您可以从 Google Cloud Platform Console 的“导入/导出”页面查看您的导入和导出操作使用哪个帐户来授权请求​​。您还可以查看您的数据库是否已使用 Cloud Firestore 服务代理。

  1. 转到 Google Cloud Platform Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出

  2. 查看Import/Export jobs run as label 旁边的授权帐户。

如果您的项目不使用 Cloud Firestore 服务代理,您可以使用以下任一技术迁移到 Cloud Firestore 服务代理:

这些技术中的第一个更可取,因为它将影响范围本地化到单个 Cloud Firestore 项目。第二种技术不是首选,因为它不会迁移现有的 Cloud Storage 存储分区权限。但是,它确实提供了组织级别的安全合规性。

通过检查和更新 Cloud Storage 存储分区权限进行迁移

迁移过程有两个步骤:

  1. 更新 Cloud Storage 存储分区权限。有关详细信息,请参阅以下部分。
  2. 确认迁移到 Cloud Firestore 服务代理。

服务代理存储桶权限

对于在另一个项目中使用 Cloud Storage 存储分区的任何导出或导入操作,您必须授予 Cloud Firestore 服务代理对该存储分区的权限。例如,将数据移动到另一个项目的操作需要访问另一个项目中的存储桶。否则,这些操作在迁移到 Cloud Firestore 服务代理后会失败。

位于同一项目中的导入和导出工作流不需要更改权限。默认情况下,Cloud Firestore 服务代理可以访问同一项目中的存储分区。

从其他项目更新 Cloud Storage 存储分区的权限,以授予对 service 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 Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出

  2. 如果您的项目尚未迁移到 Cloud Firestore 服务代理,您会看到一个描述迁移的横幅和一个检查存储桶状态按钮。下一步可帮助您识别和修复潜在的权限错误。

    单击检查存储桶状态

    将显示一个菜单,其中包含完成迁移的选项和 Cloud Storage 存储分区列表。列表可能需要几分钟才能完成加载。

    此列表包括最近在导入和导出操作中使用但当前未向 Cloud Firestore 服务代理授予读写权限的存储桶。

  3. 记下项目的 Cloud Firestore 服务代理的主体名称。服务代理名称出现在服务代理下方以授予对标签的访问权限
  4. 对于列表中您将用于未来导入或导出操作的任何存储桶,请完成以下步骤:

    1. 在此存储桶的表格行中,单击Fix 。这将在新选项卡中打开该存储桶的权限页面。

    2. 单击添加
    3. New principals字段中,输入您的 Cloud Firestore 服务代理的名称。
    4. 选择角色字段中,选择服务代理 > Firestore 服务代理
    5. 单击保存
    6. 返回到 Cloud Firestore 导入/导出页面的选项卡。
    7. 对列表中的其他存储桶重复这些步骤。确保查看列表的所有页面。
  5. 单击迁移到 Firestore 服务代理。如果您仍有未通过权限检查的存储桶,您需要通过单击Migrate来确认您的迁移。

    迁移完成时会发出警报通知您。迁移无法撤消。

查看迁移状态

  1. 要验证项目的迁移状态,请转到 Google Cloud Platform Console 中的导入/导出页面:

    转到导入/导出

  2. Import/Export jobs run as label 旁边查找主体。

    如果委托人是service- project_number @gcp-sa-firestore.iam.gserviceaccount.com ,那么您的项目已经迁移到 Cloud Firestore 服务代理。迁移无法撤消。

    如果项目尚未迁移,则页面顶部会显示一个横幅,其中包含检查存储桶状态按钮。请参阅迁移到 Firestore 服务代理以完成迁移。

添加组织范围的策略约束

  • 在组织的策略中设置以下约束:

    需要 Firestore 服务代理进行导入/导出( firestore.requireP4SAforImportExport )。

    此约束要求导入和导出操作使用 Cloud Firestore 服务代理来授权请求​​。要设置此约束,请参阅创建和管理组织策略

应用此组织政策限制不会自动为 Cloud Firestore 服务代理授予相应的 Cloud Storage 存储分区权限。

如果约束为任何导入或导出工作流创建权限错误,您可以禁用它以返回使用默认服务帐户。检查并更新 Cloud Storage 存储分区权限后,您可以再次启用该限制。