导入 Cloud Spanner Avro 文件

本页面介绍如何使用 Google Cloud Console 将 Cloud Spanner 数据库导入 Cloud Spanner。要从其他来源导入 Avro 文件，请参阅从非 Cloud Spanner 数据库中导入数据。

该过程使用 Dataflow；它从包含一组 Avro 文件和 JSON 清单文件的 Cloud Storage 存储分区文件夹中导入数据。此导入过程仅支持从 Cloud Spanner 导出的 Avro 文件。

要使用 REST API 或 gcloud 命令行工具导入 Cloud Spanner 数据库，请完成此页面上准备工作部分中的步骤，然后查看 Cloud Storage Avro 到 Cloud Spanner 中的详细说明。

准备工作

要导入 Cloud Spanner 数据库，首先需要启用 Cloud Spanner、Cloud Storage、Compute Engine 和 Dataflow API：

启用 API

此外，您还需要足够的配额和必要的 IAM 权限。

配额要求

Google Cloud 服务对导入作业的配额要求如下：

  • Cloud Spanner：您必须拥有足够的节点来支持您要导入的数据量。导入数据库本身不需要额外节点，但您可能需要增加更多节点，以便在合理的时间内完成作业。如需了解详情，请参阅优化作业。
  • Cloud Storage：要导入，您必须拥有一个包含之前导出文件的存储分区。您无需为存储分区设置大小。
  • Dataflow：导入作业与其他 Dataflow 作业具有相同的 CPU、磁盘用量和 IP 地址 Compute Engine 配额。

  • Compute Engine：在运行导入作业之前，必须为 Compute Engine 设置初始配额，以供 Dataflow 使用。这些配额表示允许 Dataflow 针对作业使用的资源用量上限。建议使用以下初始值：

    • CPU 数：200
    • 使用中的 IP 地址数：200
    • 标准永久性磁盘：50 TB

    通常情况下，您不必进行其他调整。 Dataflow 提供自动扩缩功能，因此您只需支付导入期间实际使用的资源费用。如果您的作业可能会使用更多资源，Dataflow 界面会显示警告图标。出现警告图标不会影响作业的完成。

IAM 要求

要导入数据库，您还需要有具备足够权限的 IAM 角色，以便使用导入作业中涉及的所有服务。如需了解有关授予角色和权限的信息，请参阅应用 IAM 角色。

要导入数据库，您需要以下角色：

  • 在 Google Cloud 项目级层：
    • Cloud Spanner Viewer
    • Dataflow Admin
    • Storage Admin
  • 在 Cloud Spanner 数据库或实例级层，或在 Google Cloud 项目级层：
    • Cloud Spanner Reader
    • Cloud Spanner Database Admin（仅导入作业才需要）

可选：在 Cloud Storage 中查找数据库文件夹

要在 Cloud Console 中查找包含导出的数据库的文件夹，请转到 Cloud Storage 浏览器，并点击包含已导出文件夹的存储分区。

转到 Cloud Storage 浏览器

包含导出数据的文件夹名称以实例的 ID 开头，后跟数据库名称和导出作业的时间戳。该文件夹包含以下内容：

  • spanner-export.json 文件。
  • 您导出的数据库中每个表的 TableName-manifest.json 文件。

  • 一个或多个 TableName.avro-#####-of-##### 文件。扩展名 .avro-#####-of-##### 中的第一组数字表示 Avro 文件的索引（从零开始），第二组数字则表示为每个表生成的 Avro 文件的数量。

    例如，Songs.avro-00001-of-00002 表示包含 Songs 表数据的两个文件中的第二个文件。

导入数据库

要将 Cloud Spanner 数据库从 Cloud Storage 导入到您的实例，请按照以下步骤操作。

  1. 转到 Cloud Spanner 实例页面。

    转到实例页面

  2. 点击将包含导入的数据库的实例名称。

  3. 点击左侧窗格中的导入/导出菜单项，然后点击导入按钮。

  4. 在选择源文件夹下，点击浏览。

  5. 在初始列表中找到包含导出内容的存储分区，或点击搜索 搜索界面元素的屏幕截图 来过滤列表，然后找到相应的存储分区。双击该存储分区可查看其包含的文件夹。

  6. 找到包含导出文件的文件夹，然后点击以选中该文件夹。

  7. 点击选择。

  8. 为 Cloud Spanner 在导入过程创建的新数据库输入名称。该数据库名称不能是您实例中已存在的名称。

  9. （可选）如需使用客户管理的加密密钥来保护新数据库，请点击显示加密选项，然后选择使用客户管理的加密密钥 (CMEK)。然后，从下拉列表中选择密钥。

  10. 在为导入作业选择一个区域下拉菜单中选择一个区域。

  11. （可选）如需使用客户管理的加密密钥来加密 Dataflow 流水线状态，请点击显示加密选项，然后选择使用客户管理的加密密钥 (CMEK)。然后，从下拉列表中选择密钥。

  12. 选中确认费用下的复选框，确认您了解除现有 Cloud Spanner 节点产生的费用外，还存在其他费用。

  13. 点击导入。

    Cloud Console 会显示数据库详细信息页面，该页面现在会显示一个框并在其中描述导入作业（包括所用时间）：

    运行中作业的屏幕截图

作业完成或终止时，Cloud Console 会在数据库详细信息页面上显示一条消息。如果作业成功，会显示一条成功消息：

导入作业成功消息

如果作业未成功，则会显示一条失败消息：

导入作业失败消息

如果作业运行失败，请检查作业的 Dataflow 日志以获取关于错误的详细信息并参阅排查导入作业失败问题。

为导入作业选择一个区域

您可能需要根据 Cloud Storage 存储分区是使用单区域配置还是多区域配置来选择不同的区域。为避免产生网络出站流量费用，请选择与 Cloud Storage 存储分区位置重叠的区域。

单区域存储分区位置

如果您的 Cloud Storage 存储分区位置使用单区域配置，请为导入作业选择提供免费网络使用的可用区域。

如果同一区域不可用，则出站流量将收费。请参阅 Cloud Storage 出站网络流量价格，选择出站网络流量费用最低的区域。

多区域存储分区位置

如果您的 Cloud Storage 存储分区位置使用多区域配置，请选择多区域位置的重叠区域以享受免费网络使用。

如果没有重叠区域，则出站流量将收费。请参阅 Cloud Storage 网络出站流量价格，选择出站流量费用最低的区域。

在 Dataflow 界面中查看作业或对作业进行问题排查

启动导入作业后，您可以在 Cloud Console 中的 Dataflow 部分中查看作业的详细信息，包括日志。

查看 Dataflow 作业的详细信息

如需查看过去一周内运行的任何导入/导出作业（包括当前正在运行的任何作业）的详细信息，请执行以下操作：

  1. 转到数据库的数据库概览页面。
  2. 点击左侧窗格中的导入/导出菜单项。数据库导入/导出页面会显示最近的作业列表。

  3. 在数据库导入/导出页面中，点击 Dataflow 作业名称列中的作业名称：

    运行中作业的状态消息

    Cloud Console 将显示 Dataflow 作业的详细信息。

如需查看超过一周前运行的作业，请执行以下操作：

  1. 转到 Cloud Console 的 Dataflow 作业页面。

    转到作业页面

  2. 在列表中找到您的作业，然后点击其名称。

    Cloud Console 将显示 Dataflow 作业的详细信息。

查看作业的 Dataflow 日志

如需查看 Dataflow 作业的日志，请按上文所述转到作业的详细信息页面，然后点击作业名称右侧的日志。

如果作业失败，请查看日志了解错误。如果有错误，日志旁边会显示错误计数：

“日志”按钮旁边的错误计数示例

如需查看作业错误，请执行以下操作：

  1. 点击日志旁边的错误计数。

    Cloud Console 将显示作业的日志。您可能需要向下滚动才能看到错误。

  2. 找到带错误图标 “错误”图标 的条目。

  3. 点击各个日志条目以展开其内容。

如需详细了解如何对 Dataflow 作业进行问题排查，请参阅排查流水线问题。

排查导入作业失败问题

如果您在作业日志中看到以下错误，请执行以下操作：

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

在 Cloud Console 中您的 Cloud Spanner 数据库的监控标签页中，查看 99% Write latency。如果显示的值较大（几秒钟），则表示实例已过载，导致写入超时并失败。

高延迟的一个原因是 Dataflow 作业运行时使用的工作器过多，导致 Cloud Spanner 实例负载过高。

要指定 Dataflow 工作器数量的限制，您必须使用 Dataflow Cloud Storage Avro to Cloud Spanner 模板开始导入（而不是使用 Cloud Console 中您的 Cloud Spanner 数据库的实例详情页面上的导入/导出标签页），并指定工作器数量上限，如下所述：

  • 如果您使用的是 Dataflow 控制台，则工作器数量上限参数位于基于模板创建作业页面上的可选参数部分。

  • 如果您使用的是 gcloud，请指定 max-workers 参数。例如：

    gcloud dataflow jobs run my-import-job \
--gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
--max-workers=10

工作器的数量上限与数据大小密切相关，但理想情况下，Spanner 的总 CPU 利用率应在 70% 到 90% 之间。这可以实现 Spanner 效率和无错误地完成作业之间的良好平衡。

如需在大多数架构/场景中实现该利用率目标，我们建议最大工作器 vCPU 数量在 Spanner 节点数量的 4-6 倍之间。

例如，对于使用 n1-standard-2 工作器的 10 个节点 spanner 实例，您需要将最大工作器数量设置为 25 个，从而提供 50 个 vCPU。

对运行缓慢的导入作业进行优化

如果您已按照初始设置中的建议配置，则通常不必进行其他调整。如果作业运行缓慢，则可以尝试以下优化操作：

  • 优化作业和数据位置选择：在 Cloud Spanner 实例和 Cloud Storage 存储分区所在的同一区域中运行 Dataflow 作业。

  • 确保有足够的 Dataflow 资源：如果相关的 Compute Engine 配额限制了您的 Dataflow 作业的资源，则 Google Cloud Console 中该作业的 Dataflow 页面会显示警告图标 警告图标 和日志消息：

    配额限制警告的屏幕截图

    在这种情况下，为 CPU、使用中的 IP 地址和标准永久性磁盘增加配额或许可以缩短作业的运行时间，但可能会因此产生更多的 Compute Engine 费用。

  • 检查 Cloud Spanner CPU 使用率：如果您发现某个实例的 CPU 使用率超过 65%，则可以为该实例增加节点。额外的节点会增加更多 Cloud Spanner 资源，从而加快作业的运行速度，但也会因此产生更多的 Cloud Spanner 费用。

影响导入作业性能的因素

以下几个因素会影响完成导入作业所需的时间。

  • Cloud Spanner 数据库大小：处理更多数据需要更多时间和资源。

  • Cloud Spanner 数据库架构：表的数量、行的大小、二级索引的数量以及外键的数量会影响运行导入作业所需的时间。 请注意，在 Dataflow 导入作业完成后，索引和外键创建仍将继续。

  • 数据位置：数据使用 Dataflow 在 Cloud Spanner 和 Cloud Storage 之间传输。理想情况下，这三个组件全都位于同一区域。如果这些组件不在同一区域，则跨区域移动数据会减慢作业运行速度。

  • Dataflow 工作器的数量：Dataflow 根据需要完成的工作量使用自动扩缩为作业选择工作器数量。但是，工作器数量会受到 CPU、使用中的 IP 地址和标准永久性磁盘的配额的限制。如果工作器数量达到配额上限，Dataflow 界面中会显示一个警告图标。在这种情况下，运行速度会减慢，但作业仍会完成。

  • Cloud Spanner 上的现有负载：导入作业会大幅增加 Cloud Spanner 实例上的 CPU 负载。如果该实例原本已有大量负载，则作业的运行速度会较慢。

  • Cloud Spanner 节点数：如果实例的 CPU 使用率超过 65%，则作业的运行速度会较慢。