此页面由 Cloud Translation API 翻译。

以 CSV 格式导入和导出数据

本页介绍如何将数据从 Spanner 导出到 CSV 文件或导入将数据从 CSV 文件导入 Spanner 数据库。

如果要导入您之前导出到 Cloud Storage 中的 Avro 文件的 Spanner 数据库，请参阅导入 Spanner Avro 文件。
如果要从非 Spanner 数据库中导入 Avro 文件，请参阅从非 Spanner 数据库导入数据。

该流程使用 Dataflow。您可以将 Spanner 中的数据导出到 Cloud Storage 存储桶，或者您可以将数据从包含 JSON 清单文件和一组 CSV 文件的 Cloud Storage 存储桶导入 Spanner。

准备工作

如需导入或导出 Spanner 数据库，请执行以下操作：首先，您需要启用 Spanner、Cloud Storage Compute Engine 和 Dataflow API：

Enable the APIs

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

配额要求

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

Spanner：您必须有足够的计算容量以支持您要导入的数据量。导入或导出数据库不需要额外计算容量，但您可能需要增加更多计算容量，以便在合理的时间内完成作业。如需了解详情，请参阅优化作业。
Cloud Storage：若要导入，您必须拥有一个包含之前导出文件的存储分区。如需执行导出操作，在以下情况下，您必须为导出的文件创建一个存储桶：则您可能还没有账号。您可以在 Google Cloud 控制台中执行此操作，通过 Cloud Storage 页面或在创建导出作业时通过 Spanner 页面皆可。您无需为存储桶设置大小。
Dataflow：导入或导出作业与其他 Dataflow 作业具有相同的 CPU、磁盘用量和 IP 地址 Compute Engine 配额。
Compute Engine：在运行导入或导出作业之前，必须为 Compute Engine 设置初始配额，以供 Dataflow 使用。这些配额表示允许 Dataflow 针对作业使用的资源用量上限。建议使用以下初始值：
- CPU 数：200
- 使用中的 IP 地址数：200
- 标准永久性磁盘：50 TB
通常情况下，您不必进行其他调整。 Dataflow 提供自动扩缩功能，因此您只需支付导入或导出期间实际使用的资源费用。如果您的作业可能会使用更多资源，Dataflow 界面会显示警告图标。出现警告图标不会影响作业的完成。

所需的角色

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

Cloud Spanner 查看者 (roles/spanner.viewer)
Dataflow 工作器 (roles/dataflow.worker)
Storage Admin (roles/storage.admin)
Spanner Database Reader (roles/spanner.databaseReader)
Database Admin (roles/spanner.databaseAdmin)

将 Spanner 数据导出到 CSV 文件

如需将 Spanner 中的数据导出到 Cloud Storage 中的 CSV 文件，请执行以下操作：按照说明使用 Google Cloud CLI 运行 Cloud Storage Text to Spanner 模板。

您还可以在此文档中参阅有关查看作业或对作业进行问题排查、对运行缓慢的作业进行优化和影响作业性能的因素的信息。

将数据从 CSV 文件导入 Spanner

从 CSV 文件导入数据的过程包含以下步骤：

将您的数据导出为 CSV 文件，并将这些文件存储在 Cloud Storage 中。请勿添加标题行。
创建 JSON 清单文件，并将该文件与 CSV 文件存储在一起。
在您的 Spanner 数据库中创建空目标表，或者确保 CSV 文件中的列的数据类型与您现有表中的任何相应列匹配。
运行导入作业。

第 1 步：将数据从非 Spanner 数据库导出为 CSV 文件

导入过程从位于 Cloud Storage 存储分区的 CSV 文件中提取数据。您可以从任何来源导出采用 CSV 格式的数据。

导出数据时，请注意以下事项：

需要导入的文本文件必须采用 CSV 格式。
数据必须与下面的一种类型相匹配：

GoogleSQL

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea

导出 CSV 文件时，您不必包括或生成任何元数据。
您的文件不必遵循任何特定的命名惯例。

如果您不将文件直接导出到 Cloud Storage，则必须将 CSV 文件上传到 Cloud Storage 存储分区。

第 2 步：创建 JSON 清单文件

您还必须创建一个清单文件，其中包含要导入的文件的 JSON 说明，并将该清单文件放在存储 CSV 文件的相同 Cloud Storage 存储分区中。该清单文件包含 tables 数组，其中列出了每个表的名称和数据文件位置。该文件还指定了接收数据库方言。如果省略方言，则默认为 GoogleSQL。

清单文件的格式对应于以下消息类型，此处以协议缓冲区格式显示：

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

以下示例展示了将名为 Albums 和 Singers 的表导入 GoogleSQL 方言数据库的清单文件。Albums 表使用作业从数据库中检索的列架构，Singers 表使用清单文件指定的架构：

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

第 3 步：为 Spanner 数据库创建表

在运行导入之前，您必须在 Spanner 数据库中创建目标表。如果目标 Spanner 表已有架构，则清单文件中指定的任何列都必须与目标表架构中的相应列具有相同的数据类型。

我们建议您在将数据导入 Spanner 后创建二级索引、外键和更改流，而不是在最初创建表时创建二级索引。如果您的表已包含那么我们建议将其删除并重新创建您导入数据时

第 4 步：使用 gcloud 运行 Dataflow 导入作业

如需开始导入作业，请借助 Cloud Storage Text to Spanner 模板，按照使用 Google Cloud CLI 运行作业的说明进行操作。

启动导入作业后，您可以在 Google Cloud 控制台中查看作业的详细信息。

导入作业完成后，添加任何必要的二级索引，外键和更改流。

为导入作业选择一个区域

您可能需要根据自己所在的地理位置选择不同的区域， Cloud Storage 存储分区。为避免出站数据传输费用，请选择与您的 Cloud Storage 存储桶的位置一致。

如果您的 Cloud Storage 存储桶位置使用单区域配置，您可以为导入作业选择同一区域（前提是该区域可用），以便享受免费网络使用。
如果您的 Cloud Storage 存储桶位置是双区域，您可以充分利用免费网络使用量，只需选择作为导入作业的双区域位置中的其中一个，（假设其中一个区域可用）。
如果您的导入作业无法使用同位区域，或者您的 Cloud Storage 存储桶位置是多区域，则需要支付出站数据传输费用。参阅 Cloud Storage 数据传输价格来选择数据传输费用最低。

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

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

查看 Dataflow 作业的详细信息

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

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

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

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

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

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

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

查看作业的 Dataflow 日志

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

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

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

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

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

Google Cloud 控制台将显示作业的日志。您可能需要向下滚动才能看到错误。
找到带错误图标的条目。
点击各个日志条目以展开其内容。

如需详细了解如何对 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% Read/Write latency。如果显示的值较高（多秒），则则表示实例过载，导致读写超时和失败。

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

如需指定 Dataflow 工作器数量限制，请执行以下操作：

控制台

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

转到 Dataflow

gcloud

运行 gcloud dataflow jobs run 命令，并指定 max-workers 参数。例如：

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Text_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 作业位于同一项目中的自动模式 VPC 网络中使用名为 default 的 VPC 网络。如果该项目中没有默认 VPC 网络，或者您的 VPC 网络是自定义模式 VPC 网络，则必须创建 Dataflow 作业并指定备用网络或子网。

优化运行缓慢的导入或导出作业

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

优化作业和数据位置：运行 Dataflow 作业区域位置 Cloud Storage 存储桶的位置。
确保有足够的 Dataflow 资源：如果相关的 Compute Engine 配额限制 Dataflow 作业的资源， Google Cloud 控制台中的 Dataflow 页面会显示警告图标并记录消息：

在这种情况下，为 CPU、使用中的 IP 地址和标准永久性磁盘增加配额或许可以缩短作业的运行时间，但可能会因此产生更多的 Compute Engine 费用。
检查 Spanner CPU 使用率：如果您发现实例的 CPU 使用率超过 65%，则可以为该实例增加计算容量。该容量会增加更多 Spanner 资源，从而加快作业的运行速度，但也会因此产生更多的 Spanner 费用。

影响导入或导出作业性能的因素

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

Spanner 数据库大小：处理的数据越多，需要的时间就越长资源。
Spanner 数据库架构，包括：
- 表的数量
- 行大小
- 二级索引的数量
- 外键的数量
- 更改流的数量

数据位置：数据在 Spanner 和使用 Dataflow 存储 Cloud Storage。理想情况下，这三个组件全都位于同一区域。如果这些组件不在同一区域，则跨区域移动数据会减慢作业运行速度。
Dataflow 工作器数量：最佳 Dataflow 工作器是实现良好性能所必需的。Dataflow 使用自动扩缩功能，根据需要完成的工作量选择作业的工作器数量。但是，工作器数量会受到 CPU、使用中的 IP 地址和标准永久性磁盘的配额的限制。如果工作器数量达到配额上限，Dataflow 界面中会显示一个警告图标。在这种情况下，运行速度会减慢，但作业仍会完成。如果有大量数据需要导入，则自动扩缩功能可能会导致 Spanner 过载，从而导致错误。
Spanner 上的现有负载：导入作业会将大量 CPU 负载导出作业通常会在 Spanner 实例上增加少量负载。如果该实例原本已有大量负载，则作业的运行速度会较慢。
Spanner 计算容量：如果实例的 CPU 使用率超过 65%，则作业运行速度会较慢。

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

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

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

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

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