Cloud Storage 转移作业中的运行时参数

在 Cloud Storage、Azure Blob Storage 或 Amazon Simple Storage Service (Amazon S3) 中设置数据转移作业时，您可以将 URI（或数据路径）和目标表参数化。参数化允许您从按日期整理的存储桶加载数据。这些参数称为运行时参数，以便与查询参数区分开来。

如果您在转移作业中使用运行时参数，则可以执行以下操作：

• 指定您要对目标表进行分区的方式
• 检索与特定日期匹配的文件

可用的运行时参数

设置 Cloud Storage、Blob Storage 或 Amazon S3 转移作业时，您可以使用运行时参数指定如何对目标表进行分区。

参数	模板类型	值
run_time	带格式的时间戳	采用世界协调时间 (UTC)，基于计划。对于定期运行的计划转移作业，run_time 表示预期执行时间。例如，如果转移作业设置为“每 24 小时”执行一次，则连续两次查询之间的 run_time 差值将正好为 24 小时，即使实际的执行时间可能略有不同也是如此。 请参阅 TransferRun.runTime
run_date	日期字符串	run_time 参数的日期格式为 %Y%m%d，例如“20180101”。此格式与提取时间分区表兼容。

模板系统

Cloud Storage、Blob Storage 和 Amazon S3 转移作业支持使用模板语法在目标表名称中采用运行时参数。

参数模板语法

模板语法支持基本的字符串模板和时间偏移量设置。您可以采用以下格式来引用参数：

• {run_date}
• {run_time[+\-offset]|"time_format"}

参数	用途
run_date	此参数将替换成格式为 YYYYMMDD 的日期。
run_time	此参数支持以下属性： offset 按小时 (h)、分钟 (m) 和秒 (s) 的顺序表示的时间偏移量。 不支持天 (d)。 允许使用小数，例如 1.5h。 time_format 带格式的字符串。最常见的格式参数是年 (%Y)、月 (%m) 和日 (%d)。 对于分区表，YYYYMMDD 是必需的后缀，等效于“%Y%m%d”。 详细了解带格式的 datetime 元素。

使用说明：

• run_time、offset 和 time_format 之间不允许有空格。
• 如需在字符串中包含文本大括号，您可以将其转义为 '\{' and '\}'。
• 如需在 time_format 中包含文本引号或竖线（例如 "YYYY|MM|DD"），您可以在格式字符串中将其转义为 '\"' 或 '\|'。

参数模板示例

以下示例演示了如何使用不同的时间格式指定目标表名称，以及如何设置运行时间的偏移量。

run_time (UTC)	模板化参数	输出目标表名称
2018-02-15 00:00:00	mytable	mytable
2018-02-15 00:00:00	mytable_{run_time|"%Y%m%d"}	mytable_20180215
2018-02-15 00:00:00	mytable_{run_time+25h|"%Y%m%d"}	mytable_20180216
2018-02-15 00:00:00	mytable_{run_time-1h|"%Y%m%d"}	mytable_20180214
2018-02-15 00:00:00	mytable_{run_time+1.5h|"%Y%m%d%H"} 或 mytable_{run_time+90m|"%Y%m%d%H"}	mytable_2018021501
2018-02-15 00:00:00	{run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"}	20180215_mytable_000137

分区选项

BigQuery 中有两种类型的分区表：

• 按提取时间分区的表。对于 Cloud Storage、Blob Storage 和 Amazon S3 转移作业，提取时间就是转移作业的运行时间。
• 根据列分区的表。列类型必须是 TIMESTAMP 或 DATE 列。

如果目标表是基于某一列进行分区的，则在创建目标表并指定其架构时，您应确定分区列。如需详细了解如何创建基于列的分区表，请参阅创建和使用分区表。

分区示例

• 没有分区的表
  • 目标表：mytable
• 提取时间分区表
  • 目标表：mytable$YYYYMMDD
  • 请注意，无法指定分钟数。
• 列分区表
  • 目标表：mytable
  • 在创建表的架构时，将分区列指定为 TIMESTAMP 或 DATE 列。

有关参数用法的注意事项

• 如果您根据自己的本地时区对数据进行分区，则需要使用模板语法中的偏移机制手动计算相对于世界协调时间 (UTC) 的小时偏移量。
• 无法在参数中指定分钟数。
• 系统允许将 URI 或数据路径的通配符与目标表名称中的参数搭配使用。

运行时参数示例

以下示例展示了将通配符和参数搭配用于常见用例的方法。对于所有示例，假设表的名称为 mytable，run_time 为 2018-02-15 00:00:00（世界协调时间 (UTC)）。

将数据转移到非分区表

此用例适用于将新文件从 Cloud Storage、Blob Storage 或 Amazon S3 存储桶加载到非分区表中。此示例在 URI 或数据路径中使用通配符，并使用临时刷新转移作业来选取新文件。

数据源	来源 URI 或数据路径	目标表名称
Cloud Storage	gs://bucket/*.csv	mytable
Amazon S3	s3://bucket/*.csv	mytable
Blob 存储	*.csv	mytable

将包含所有数据的快照加载到注入时间分区表中

在此示例中，指定的 URI 或数据路径中的所有数据都将转移到一个按当天日期分区的表中。在一项刷新转移作业中，此配置会选取自从上次加载后添加的文件，并将其添加到某个特定的分区中。

数据源	来源 URI 或数据路径	参数化的目标表名称	计算的目标表名称
Cloud Storage	gs://bucket/*.csv	mytable${run_time|"%Y%m%d"}	mytable$20180215
Amazon S3	s3://bucket/*.csv	mytable${run_time|"%Y%m%d"}	mytable$20180215
Blob 存储	*.csv	mytable${run_time|"%Y%m%d"}	mytable$20180215

此用例将当天的数据转移到按当天日期分区的表中。此示例还适用于刷新转移作业，该作业检索与某一日期相匹配的新增文件，并将数据加载到相应的分区中。

数据源	参数化 URI 或数据路径	参数化的目标表名称	评估的 URI 或数据路径	计算的目标表名称
Cloud Storage	gs://bucket/events-{run_time|"%Y%m%d"}/*.csv	mytable${run_time|"%Y%m%d"}	gs://bucket/events-20180215/*.csv	mytable$20180215
Amazon S3	s3://bucket/events-{run_time|"%Y%m%d"}/*.csv	mytable${run_time|"%Y%m%d"}	s3://bucket/events-20180215/*.csv	mytable$20180215
Blob 存储	events-{run_time|"%Y%m%d"}/*.csv	mytable${run_time|"%Y%m%d"}	events-20180215/*.csv	mytable$20180215

后续步骤

• 了解如何设置 Cloud Storage 转移作业
• 详细了解 BigQuery Data Transfer Service。