导入 Spanner Avro 文件

本页介绍了如何使用 Google Cloud 控制台将 Spanner 数据库导入 Spanner。如需从其他来源导入 Avro 文件,请参阅从非 Spanner 数据库导入数据

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

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

准备工作

如需导入 Spanner 数据库,您需要先启用 Spanner、Cloud Storage、Compute Engine 和 Dataflow API:

Enable the APIs

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

配额要求

导入作业的配额要求如下:

  • Spanner:您必须拥有足够多的计算容量来支持您要导入的数据量。导入数据库不需要额外计算容量,但您可能需要增加更多计算容量,以便在合理的时间内完成作业。如需了解详情,请参阅优化作业
  • Cloud Storage:要导入,您必须拥有一个包含之前导出文件的存储分区。您无需为存储分区设置大小。
  • Dataflow:导入作业与其他 Dataflow 作业具有相同的 CPU、磁盘用量和 IP 地址 Compute Engine 配额
  • Compute Engine:在运行导入作业之前,必须为 Compute Engine 设置初始配额,以供 Dataflow 使用。这些配额表示允许 Dataflow 针对作业使用的资源用量上限。建议使用以下初始值:

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

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

所需的角色

如需获得导出数据库所需的权限,请让您的管理员向您授予 Dataflow 工作器服务账号的以下 IAM 角色:

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

如需在 Google Cloud 控制台中查找包含导出的数据库的文件夹,请前往 Cloud Storage 浏览器,然后点击包含已导出文件夹的存储分区。

转到 Cloud Storage 浏览器

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

  • spanner-export.json 文件。
  • 您导出的数据库中每个表的 TableName-manifest.json 文件。
  • 一个或多个 TableName.avro-#####-of-##### 文件。扩展名 .avro-#####-of-##### 中的第一组数字表示 Avro 文件的索引(从零开始),第二组数字则表示为每个表生成的 Avro 文件的数量。

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

  • 您导出的数据库中每个更改流ChangeStreamName-manifest.json 文件。

  • 每个更改流对应一个 ChangeStreamName.avro-00000-of-00001 文件。此文件包含空数据,其中仅包含更改流的 Avro 架构。

导入数据库

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

  1. 前往 Spanner 实例页面。

    转到实例页面

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

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

  4. 选择源文件夹下,点击浏览

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

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

  7. 点击选择

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

  9. 选择新数据库的方言(GoogleSQL 或 PostgreSQL)。

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

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

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

  13. 选中确认费用下的复选框,确认您了解除现有 Spanner 实例产生的费用外,还存在其他费用。

  14. 点击导入

    Google Cloud 控制台会显示数据库详细信息页面,该页面现在会显示一个框并在其中描述导入作业(包括所用时间):

    运行中作业的屏幕截图

作业完成或终止时,Google Cloud 控制台中的数据库详细信息页面上会显示一条消息。如果作业成功,会显示一条成功消息:

导入作业成功消息

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

导入作业失败消息

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

关于导入生成的列和更改流的注意事项

Spanner 会使用 Avro 架构中每个生成的列的定义来重新创建该列。在导入过程中,Spanner 会自动计算生成的列值。

同样,Spanner 会使用 Avro 架构中每个更改流的定义,在导入期间重新创建该更改流。变更数据流数据不会通过 Avro 导出或导入,因此与新导入的数据库关联的所有变更数据流都没有变更数据记录。

关于导入序列的说明

Spanner 导出的每个序列(GoogleSQLPostgreSQL)都使用 GET_INTERNAL_SEQUENCE_STATE()GoogleSQLPostgreSQL)函数来捕获其当前状态。Spanner 会向计数器添加 1000 个缓冲区,并将新的计数器值写入记录字段的属性。请注意,这只是为避免导入后可能发生的重复值错误而采取的一种尽力方法。如果在数据导出期间有更多写入操作到源数据库,请调整实际序列计数器。

导入时,序列将从此新计数器开始,而不是从架构中找到的计数器开始。如有需要,您可以使用 ALTER SEQUENCE (GoogleSQLPostgreSQL) 语句更新为新的计数器。

关于导入交错表和外键的注意事项

Dataflow 作业可以导入交错表,让您保留源文件中的父子关系。不过,系统不会在数据加载期间强制执行外键约束条件。Dataflow 作业会在数据加载完成后创建所有必要的外键。

如果您在导入开始之前对 Spanner 数据库设置了外键约束条件,则可能会因违反参照完整性而遇到写入错误。为避免写入错误,请考虑在发起导入流程之前删除所有现有外键。

为导入作业选择一个区域

您可能需要根据 Cloud Storage 存储分区的位置选择不同的区域。为避免产生出站数据传输费用,请选择与您的 Cloud Storage 存储分区所在位置匹配的区域。

  • 如果您的 Cloud Storage 存储分区位置使用单区域配置,您可以为导入作业选择同一区域(前提是该区域可用),以便享受免费网络使用

  • 如果您的 Cloud Storage 存储分区位置使用双区域配置,您可以为导入作业选择双区域的任一区域(假设其中一个区域可用),从而享受免费网络使用

  • 如果您的导入作业无法使用同位区域,或者您的 Cloud Storage 存储分区位置是多区域,则需要支付出站数据传输费用。请参阅 Cloud Storage 数据传输价格,选择数据传输费用最低的区域。

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

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

查看 Dataflow 作业详情

如需查看过去一周内运行的任何导入或导出作业(包括当前正在运行的任何作业)的详细信息,请执行以下操作:

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

    运行中作业的状态消息

    Google Cloud 控制台会显示 Dataflow 作业的详细信息。

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

  1. 前往 Google Cloud 控制台中的 Dataflow 作业页面。

    转到作业

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

    Google Cloud 控制台会显示 Dataflow 作业的详细信息。

查看作业的 Dataflow 日志

如需查看 Dataflow 作业的日志,请前往作业的详细信息页面,然后点击作业名称右侧的日志

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

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

如需查看作业错误,请执行以下操作:

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

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

  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.

在 Google Cloud 控制台中,查看 Spanner 数据库的 Monitoring 标签页中的 99% Write latency。如果显示的值较大(几秒钟),则表示实例已过载,导致写入超时并失败。

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

如需指定 Dataflow 工作器数量的限额,您必须使用 Dataflow Cloud Storage Avro to Spanner 模板开始导入(而不是使用 Google Cloud 控制台中 Spanner 数据库实例详情页面中的“导入/导出”标签页),并指定工作器数量上限,如下所述:

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

转到 Dataflow

运行 gcloud dataflow jobs run 命令,并指定 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 \
    --network=network-123

排查网络错误

导出 Spanner 数据库时,可能会出现以下错误:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

出现此错误是因为 Spanner 假定您打算在与 Dataflow 作业位于同一项目中的某个位置使用名为 default 的自动模式 VPC 网络。如果该项目中没有默认 VPC 网络,或者您的 VPC 网络是自定义模式 VPC 网络,则必须创建 Dataflow 作业并指定备用网络或子网

优化运行缓慢的导入作业

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

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

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

    配额限制警告的屏幕截图

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

  • 检查 Spanner CPU 使用率:如果您发现实例的 CPU 使用率超过 65%,则可以为该实例增加计算容量。该容量会增加更多 Spanner 资源,从而加快作业的运行速度,但也会因此产生更多的 Spanner 费用。

影响导入作业性能的因素

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

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

  • Spanner 数据库架构,包括:

    • 表数
    • 行大小
    • 二级索引的数量
    • 外键的数量
    • 更改流的数量

请注意,在 Dataflow 导入作业完成后,索引和外键创建仍将继续。更改流会在导入作业完成之前创建,但在导入所有数据之后。

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

  • Dataflow 工作器数量:最佳 Dataflow 工作器是实现良好性能所必需的。Dataflow 使用自动扩缩功能,根据需要完成的工作量选择作业的工作器数量。但是,工作器数量会受到 CPU、使用中的 IP 地址和标准永久性磁盘的配额的限制。如果工作器数量达到配额上限,Dataflow 界面中会显示一个警告图标。在这种情况下,运行速度会减慢,但作业仍会完成。如果有大量数据需要导入,则自动扩缩功能可能会导致 Spanner 过载,从而导致错误。

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

  • Spanner 计算容量:如果实例的 CPU 使用率超过 65%,则作业运行速度会较慢。

调整工作器以实现良好的导入性能

启动 Spanner 导入作业时,Dataflow 工作器必须设为最佳值以获得良好性能。如果工作器过多,使 Spanner 过载,而工作器数量过少,则会导致导入性能不佳。

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

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

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