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

后续步骤