Cloud Storage Text to Spanner 模板

Cloud Storage Text to Spanner 模板是一种批处理流水线，用于从 Cloud Storage 读取 CSV 文本文件并将其导入到 Spanner 数据库。

流水线要求

• 目标 Spanner 数据库和表必须已存在。
• 您必须拥有 Cloud Storage 存储桶的读取权限以及目标 Spanner 数据库的写入权限。
• 包含 CSV 文件的 Cloud Storage 输入路径必须存在。
• 您必须创建包含 CSV 文件的 JSON 说明的导入清单文件，并且必须将该清单存储在 Cloud Storage 中。
• 如果目标 Spanner 数据库已有架构，则清单文件中指定的任何列都必须与目标数据库架构中的相应列具有相同的数据类型。

• 采用 ASCII 或 UTF-8 编码的清单文件必须符合以下格式：

  清单格式和示例

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

  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"}
        ]
      }
    ]
  }

• 要导入的文本文件必须采用 ASCII 或 UTF-8 编码的 CSV 格式。我们建议您不要在 UTF-8 编码文件中使用字节顺序标记 (BOM)。
• 数据必须与下面的一种类型相匹配：

  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 文件中的列必须与目标数据库中的列具有相同的顺序。您可以通过运行以下查询来查看表中列的顺序：

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

警告：如果目标 Spanner 数据库不为空，则新数据可能会覆盖预先存在的数据。

模板参数

必需参数

• instanceId：Spanner 数据库的实例 ID。
• databaseId：Spanner 数据库的 ID。
• importManifest：导入清单文件时在 Cloud Storage 中使用的路径。例如 gs://your-bucket/your-folder/your-manifest.json。

可选参数

• spannerHost：要在模板中调用的 Cloud Spanner 端点。仅用于测试。例如 https://batch-spanner.googleapis.com。默认值为：https://batch-spanner.googleapis.com。
• columnDelimiter：源文件使用的列分隔符。默认值为 ,。例如 ,。
• fieldQualifier：应放置在包含 columnDelimiter 的源文件中任何值前后的字符。默认值为双引号。
• trailingDelimiter：指定源文件中的行是否带有末尾分隔符（即，在每行末尾的最后一列值之后，是否会出现 columnDelimiter 字符）。默认值为 true。
• escape：源文件使用的转义字符。默认情况下，此参数未设置，并且模板不使用转义字符。
• nullString：表示 NULL 值的字符串。默认情况下，此参数未设置，并且模板不使用 null 字符串。
• dateFormat：用于解析日期列的格式。默认情况下，流水线会尝试将日期列解析为 yyyy-M-d[' 00:00:00']，例如，解析为 2019-01-31 或 2019-1-1 00:00:00。如果您的日期格式有所不同，请使用 java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html) 模式指定格式。
• timestampFormat：用于解析时间戳列的格式。如果时间戳为长整数，则会解析为 Unix 时间。否则，系统会使用 java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT) 格式将其解析为字符串。对于其他情况，请指定您自己的模式字符串，例如，您可以对 Jan 21 1998 01:02:03.456+08:00 格式的时间戳使用 MMM dd yyyy HH:mm:ss.SSSVV。
• spannerProjectId：包含 Spanner 数据库的 Google Cloud 项目的 ID。如果未设置，则使用默认 Google Cloud 项目的项目 ID。
• spannerPriority：Spanner 调用的请求优先级。可能的值包括 HIGH、MEDIUM 和 LOW。默认值为 MEDIUM。
• handleNewLine：如果为 true，则输入数据可以包含换行符。否则，换行符会导致错误。默认值为 false。启用换行符处理可能会降低性能。
• invalidOutputPath：写入无法导入的行的 Cloud Storage 路径。例如 gs://your-bucket/your-path。默认值为空。

如果您需要使用自定义日期或时间戳格式，请确保这些格式是有效的 java.time.format.DateTimeFormatter 模式。下表显示了日期和时间戳列的自定义格式的其他示例：

类型	输入值	格式	备注
DATE	2011-3-31		默认情况下，模板可以解析此格式。您无需指定 dateFormat 参数。
DATE	2011-3-31 00:00:00		默认情况下，模板可以解析此格式。您无需指定格式。如果需要，您可以使用 yyyy-M-d' 00:00:00'。
DATE	01 Apr, 18	dd MMM, yy
DATE	Wednesday, April 3, 2019 AD	EEEE, LLLL d, yyyy G
TIMESTAMP	2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		默认格式 ISO_INSTANT 可以解析此类型的时间戳。您无需提供 timestampFormat 参数。
TIMESTAMP	1568402363		默认情况下，模板可以解析此类型的时间戳并将其视为 Unix 时间。
TIMESTAMP	Tue, 3 Jun 2008 11:05:30 GMT	EEE, d MMM yyyy HH:mm:ss VV
TIMESTAMP	2018/12/31 110530.123PST	yyyy/MM/dd HHmmss.SSSz
TIMESTAMP	2019-01-02T11:22:33Z 或 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	如果输入列为 2019-01-02T11:22:33Z 和 2019-01-02T11:22:33.123Z 的混合格式，则默认格式可以解析此类型的时间戳。您无需提供自己的格式参数。您可以使用 yyyy-MM-dd'T'HH:mm:ss[.SSS]VV 来处理这两种情况。您不能使用 yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'，因为后缀“Z”必须解析为时区 ID（而不是字符字面量）。在内部，时间戳列会转换为 java.time.Instant。因此，您必须以 UTC 指定时间戳列，或者将时区信息与其相关联。本地日期时间（例如 2019-01-02 11:22:33）无法解析为有效的 java.time.Instant。

运行模板

控制台

1. 转到 Dataflow 基于模板创建作业页面。
转到“基于模板创建作业”
2. 在作业名称字段中，输入唯一的作业名称。
3. 可选：对于区域性端点，从下拉菜单中选择一个值。默认区域为 us-central1。

   如需查看可以在其中运行 Dataflow 作业的区域列表，请参阅 Dataflow 位置。

4. 从 Dataflow 模板下拉菜单中，选择 the Text Files on Cloud Storage to Cloud Spanner template。
5. 在提供的参数字段中，输入您的参数值。
6. 点击运行作业。

gcloud

注意：如需使用 Google Cloud CLI 运行 classic模板，您必须具有 Google Cloud CLI 138.0.0 或更高版本。

在 shell 或终端中，运行模板：

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

替换以下内容：

• JOB_NAME：您选择的唯一性作业名称
• VERSION：您要使用的模板的版本

  您可使用以下值：

  • latest，以使用模板的最新版本，该模板在存储桶的未标示日期的父文件夹 (gs://dataflow-templates-REGION_NAME/latest/) 中可用
  • 版本名称（如 2023-09-12-00_RC00），以使用模板的特定版本，该版本嵌套在存储桶的相应日期父文件夹 (gs://dataflow-templates-REGION_NAME/) 中
  注意：最新版模板可能会随着重大更改而更新。为了防止这些重大更改影响您的生产工作流程，生产环境应使用有最近标示日期的父文件夹中保存的模板。
• REGION_NAME：要在其中部署 Dataflow 作业的区域，例如 us-central1
• INSTANCE_ID：您的 Spanner 实例 ID
• DATABASE_ID：您的 Spanner 数据库 ID
• GCS_PATH_TO_IMPORT_MANIFEST：导入清单文件的 Cloud Storage 路径

API

如需使用 REST API 来运行模板，请发送 HTTP POST 请求。如需详细了解 API 及其授权范围，请参阅 projects.templates.launch。

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

替换以下内容：

• PROJECT_ID：您要在其中运行 Dataflow 作业的 Google Cloud 项目的 ID
• JOB_NAME：您选择的唯一性作业名称
• VERSION：您要使用的模板的版本

  您可使用以下值：

  • latest，以使用模板的最新版本，该模板在存储桶的未标示日期的父文件夹 (gs://dataflow-templates-REGION_NAME/latest/) 中可用
  • 版本名称（如 2023-09-12-00_RC00），以使用模板的特定版本，该版本嵌套在存储桶的相应日期父文件夹 (gs://dataflow-templates-REGION_NAME/) 中
  注意：最新版模板可能会随着重大更改而更新。为了防止这些重大更改影响您的生产工作流程，生产环境应使用有最近标示日期的父文件夹中保存的模板。
• LOCATION：要在其中部署 Dataflow 作业的区域，例如 us-central1
• INSTANCE_ID：您的 Spanner 实例 ID
• DATABASE_ID：您的 Spanner 数据库 ID
• GCS_PATH_TO_IMPORT_MANIFEST：导入清单文件的 Cloud Storage 路径

模板源代码

Java

此模板的源代码位于 GitHub 上的 GoogleCloudPlatform/DataflowTemplates 代码库中。

后续步骤

• 了解 Dataflow 模板。
• 参阅 Google 提供的模板列表。