导入 Spanner Avro 文件

本页面介绍了如何使用 Google Cloud 控制台如需从其他来源导入 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：

启用 API

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

配额要求

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

• 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 项目级层：
  • Spanner 查看者 (roles/spanner.viewer)
  • Dataflow 管理员 (roles/dataflow.admin)
  • Storage Admin (roles/storage.admin)
• 在 Spanner 数据库或实例级别，或者 Google Cloud 项目级： <ph type="x-smartling-placeholder">
  </ph>
  • Spanner 数据库读取者 (roles/spanner.databaseReader)
  • Spanner 数据库管理员 (roles/spanner.databaseAdmin)

注意 ：只有导入作业需要 Spanner Database Admin 角色。

可选：在 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. 在为导入作业选择一个区域下拉菜单中选择一个区域。

    注意 ：为避免产生出站数据传输费用，请选择 与您的 Cloud Storage 存储桶的位置重叠。请参阅 如需了解详情，请在下方选择区域。

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

13. 选中确认费用下的复选框，确认 费用。

14. 点击导入。

    Google Cloud 控制台会显示数据库详细信息页面，该页面 现在显示一个框，描述导入作业，包括作业的已执行时间 时间：

    

当作业完成或终止时，Google Cloud 控制台会显示 （位于数据库详细信息页面上）消息。如果作业成功，会显示一条成功消息：

注意 ：Dataflow 导入作业成功完成后， Spanner 为导入的数据库创建索引和外键。 在索引创建过程中，Google Cloud 控制台会显示 进度图标，以指示正在进行长时间运行的操作。该图标位于数据库详细信息页面左侧，数据库层次结构中索引名称的旁边。当进行中图标变为索引图标 时，表示该索引创建完成。您可以查询 INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS 视图上的 SPANNER_STATE 以查看外键创建状态。

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

如果作业失败，请检查作业的 Dataflow 日志中是否存在错误 详情，请参阅对失败的导入作业进行问题排查。

关于导入生成的列和变更数据流的说明

Spanner 使用每个生成的列的定义 重新创建该列。Spanner 在导入期间自动计算生成的列值。

同样，Spanner 会使用每项更改的定义 stream，以便在导入期间重新创建它。更改 流数据既不会导出，也不会通过 Avro 导入，因此所有 与新导入的数据库关联的变更数据流将具有 无变更数据记录。

有关导入序列的注意事项

每个序列（GoogleSQL、 PostgreSQL） 使用 GET_INTERNAL_SEQUENCE_STATE() （GoogleSQL、 PostgreSQL） 函数来捕获其当前状态。 Spanner 向计数器添加 1000 的缓冲区，并将新的 计数器值。请注意，这只是 努力避免导入后可能发生的重复值错误。 如果还有更多写入操作，则调整实际序列计数器 源数据库。

导入时，序列从这个新计数器（而非计数器）开始 架构中。如果需要，您可以使用 ALTER SEQUENCE (GoogleSQL, PostgreSQL） 语句以更新为新计数器。

为导入作业选择一个区域

您可能需要根据自己所在的地理位置选择不同的区域， 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.

查看 99% 写入延迟时间： Spanner 数据库的监控标签页， Google Cloud 控制台。如果显示的值较大（几秒钟），则表示实例已过载，导致写入超时并失败。

导致高延迟的一个原因是，运行 Dataflow 作业时，使用过多 这给 Spanner 实例带来了过多的负载。

如需指定 Dataflow 工作器数量限制，请不要使用 Spanner 实例详情页面中的“导入/导出”标签页 数据库，您必须先启动 使用 Dataflow 导入 Cloud Storage Avro to Cloud Spanner 模板 并指定工作器数量上限，如下所述： <ph type="x-smartling-placeholder">

</ph>

• 如果您使用的是 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
  

优化运行缓慢的导入作业

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

• 优化作业和数据位置：运行 Dataflow 作业 区域位置 Cloud Storage 存储桶的位置。

• 确保有足够的 Dataflow 资源：如果 相关的 Compute Engine 配额 限制 Dataflow 作业的资源， Google Cloud 控制台中的 Dataflow 页面 会显示警告图标 并记录 消息：

  

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

• 检查 Spanner CPU 利用率：如果您发现 CPU 利用率 超过 65% 后，您可以 可增加该实例中的计算容量。容量增加了 Spanner 资源和作业应该会加快，但会产生更多 Spanner 费用。

影响导入作业性能的因素

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

• Spanner 数据库大小：处理的数据越多，需要的时间就越长 资源。

• Spanner 数据库架构，其中包括：

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

请注意，索引和外键 Dataflow 导入作业后继续创建 。变更数据流在导入作业完成之前创建， 但在数据导入之后。

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

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

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

• Spanner 计算容量的数量：如果实例的 CPU 利用率 超过 65%，则作业的运行速度会减慢。

调整 worker 以实现良好的导入性能

启动 Spanner 导入作业时，Dataflow 会 必须将工作器设置为最优值以获得良好性能。工作器过多 使 Spanner 过载，而工作器过少会导致负担过重 导入性能。

工作器数量上限在很大程度上取决于数据大小， 但理想情况下，Spanner CPU 的总利用率应介于 70% 到 90%。这在 Spanner 之间实现了良好的平衡 并且不会出错。

为了在大多数架构和场景中实现该利用率目标， 建议将工作器 vCPU 数量上限设置为 4-6 倍 Spanner 节点。

例如，对于 10 节点的 Spanner 实例，使用 n1-standard-2 工作器数量上限，请将工作器数量上限设置为 25，提供 50 个 vCPU。