获取我们在 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 存储桶。您不能将 Requester Pays 存储桶用于导出和导入操作。
  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. Choose Destination下方,输入 Cloud Storage 存储桶的名称或使用Browse按钮​​选择一个存储桶。

  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. Choose Destination下方,输入 Cloud Storage 存储桶的名称或使用Browse按钮​​选择一个存储桶。

  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 Import/Export页面中查看最近的导出和导入操作列表。

转到导入/导出页面

云端

使用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的值。

workCompletedworkEstimated进行粗略的进度预估。此估计可能不准确,因为它依赖于延迟的统计信息收集。

取消操作

谷歌云控制台

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

转到导入/导出页面

Recent imports and exports表中,当前运行的操作在Completed列中包含一个Cancel按钮。单击取消按钮停止操作。该按钮变为取消消息,然后在操作完全停止时变为已取消

云端

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

gcloud firestore operations cancel [OPERATION_NAME]

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

删除操作

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

gcloud firestore operations delete [OPERATION_NAME]

进出口业务的计费和定价

在使用托管导出和导入服务之前,您需要为您的 Google Cloud 项目启用结算功能。导出和导入操作按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 架构超过 10000 列,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标签旁边的授权帐户。

如果您的项目不使用 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- 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 Platform Console 中的Cloud Firestore 导入/导出页面。

    转到导入/导出

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

    单击检查存储桶状态

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

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

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

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

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

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

查看迁移状态

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

    转到导入/导出

  2. 在作为标签运行的导入/导出作业旁边查找主体。

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

    如果项目尚未迁移,页面顶部会出现一个带有检查存储桶状态按钮的横幅。请参阅迁移到 Firestore 服务代理以完成迁移。

添加组织范围的策略约束

  • 在您的组织策略中设置以下限制:

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

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

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

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