Cloud Storage 转移作业

通过适用于 Cloud Storage 的 BigQuery Data Transfer Service,您可以安排从 Cloud Storage 到 BigQuery 的周期性数据加载作业。

准备工作

在创建 Cloud Storage 转移作业之前,请先完成以下操作:

限制

从 Cloud Storage 到 BigQuery 的周期性转移作业受到以下限制:

  • 转移作业中所有与通配符或运行时参数定义的模式匹配的文件都必须共用您已为目标表定义的相同架构,否则该转移作业将失败。如果表架构在多次运行期间发生更改,也会导致转移作业失败。
  • Cloud Storage 中的源文件必须至少已存在一个小时才会被转移作业选取。
  • 由于可以对 Cloud Storage 对象进行版本控制,因此请务必注意,BigQuery 转移作业不支持已归档的 Cloud Storage 对象。对象必须处于活跃状态才能被转移。
  • 对于正在运行的转移作业,您需要先创建目标表及其架构,然后再设置转移作业,这一点与从 Cloud Storage 到 BigQuery 的各个数据加载作业不同。BigQuery 无法在周期性数据转移过程中创建表。
  • 以 Cloud Storage 为来源的转移作业始终会通过 WRITE_APPEND 偏好设置触发,该偏好设置会将数据附加到目标表中。如需了解详情,请参阅 load 作业配置中的 configuration.load.writeDisposition
  • 如果数据集的位置设置为 US 以外的值,则区域或多区域 Cloud Storage 存储分区必须与数据集位于相同的区域。

Cloud Storage 源数据可能还存在其他限制,具体取决于源数据的格式。如需了解详情,请参阅:

所需权限

在将数据加载到 BigQuery 时,您需要拥有相关权限,才能将数据加载到新的或现有的 BigQuery 表和分区中。如果要从 Cloud Storage 加载数据,您还需要拥有对您的数据所在的存储分区的访问权限。确保您拥有以下必要的权限:

  • BigQuery:要创建预定的转移作业,您必须拥有 bigquery.transfers.update 权限。预定义的 Cloud IAM 角色 bigquery.admin 具有 bigquery.transfers.update 权限。如需详细了解 BigQuery 中的 Cloud IAM 角色,请参阅访问权限控制
  • Cloud Storage:您必须拥有针对单个存储分区的 storage.objects.get 权限,或更高级别的权限。如果要使用 URI 通配符,您还必须拥有 storage.objects.list 权限。如果您要在每次成功转移后删除源文件,还需要拥有 storage.objects.delete 权限。预定义的 Cloud IAM 角色 storage.objectAdmin 具有以下所有权限。

设置 Cloud Storage 转移作业

要在 BigQuery Data Transfer Service 中创建 Cloud Storage 转移作业,请按下列步骤操作:

控制台

  1. 转到 GCP Console。

    转到 GCP Console

  2. 点击转移

  3. 点击创建

  4. 创建转移作业页面上:

    • 来源类型部分的来源中,选择 Cloud Storage。

      转移作业来源

    • 转移配置名称部分的显示名中,输入转移作业的名称,例如 My Transfer。转移作业名称可以是任何容易辨识的值,方便您以后在需要修改名称时能轻松识别相应的转移作业。

      转移作业名称

    • 时间表选项部分的时间表中,保留默认值(立即开始)或点击在设置的时间开始 (Start at a set time)。

      • 重复频率部分,从以下选项中选择转移作业的运行频率。
        • 每日一次(默认值)
        • 每周一次
        • 每月一次
        • 自定义
        • 按需
      • 开始日期和运行时间部分,输入转移作业的开始日期和时间。如果选择立即开始,则此选项会处于停用状态。

        转移作业时间安排

    • 目标设置部分的目标数据集中,选择您创建用来存储数据的数据集。

      转移作业数据集

    • 数据源详细信息部分,执行以下操作:

      • 目标表部分,输入目标表的名称。 目标表必须遵循表命名规则。目标表名称也支持使用参数
      • Cloud Storage URI 部分,输入 Cloud Storage URI。您可以使用通配符参数
      • 如果您希望在每次成功转移后删除源文件,请选中在转移作业完成后删除源文件 (Delete source files after transfer) 复选框。 系统会尽力运行删除作业。如果首次删除源文件失败,则系统不会重试删除作业。
      • 转移选项部分,执行以下操作:

        • 所有格式下方:
          • 允许的错误数部分,输入 BigQuery 在运行作业时可以忽略的错误记录数上限。如果错误记录数超过此限值,作业结果中将返回一个“无效”错误,并且作业将运行失败。默认值为 0
        • JSON, CSV 下方:
          • 如果您想让转移作业删除不符合目标表架构的数据,请选中忽略未知值复选框。
        • CSV 下方:

          • 字段分隔符部分,输入用于分隔字段的字符。默认值为英文逗号。
          • 对于要跳过的标题行数部分,如果您不想导入源文件中的标题行,请输入相应的标题行数。默认值为 0
          • 对于允许引用的数据中包含换行符部分,如果您想要允许在引用字段中使用换行符,请选中此复选框。
          • 对于允许使用可选列留空的行部分,如果您想要允许转移缺少 NULLABLE 列内容的行,请选中此复选框。

      Cloud Storage 来源详细信息

    • (可选)在通知选项部分,执行以下操作:

      • 点击切换开关以启用电子邮件通知。启用此选项后,转移作业管理员会在转移作业运行失败时收到电子邮件通知。
      • 选择 Cloud Pub/Sub 主题字段中,选择主题名称或点击创建主题。此选项用于为您的转移作业配置 Cloud Pub/Sub 运行通知。转移作业运行通知目前为 Alpha 版
  5. 点击保存

经典版界面

  1. 转到 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 点击 Transfers

  3. 点击 Add Transfer

  4. New Transfer 页面上,执行以下操作:

    • Source 部分,选择 Cloud Storage。
    • Display name 部分,输入转移作业的名称,例如 My Transfer。显示名可以是任何容易辨识的值,方便您以后在需要修改名称时能轻松识别相应的转移作业。
    • (可选)在 Schedule 部分,您可以保留默认值 Daily(基于创建时间,每 24 小时一次),或点击 Edit 以更改时间。您还可以将间隔时间更改为“Weekly”、“Monthly”或“Custom”。如果选择“Custom”,则需采用类似 Cron 作业使用的时间规范,例如 every 12 hours。允许的最短时长为 12 小时。如需了解其他有效的 API 值,请参阅 TransferConfig 下的 schedule 字段。

      转移作业时间安排

    • Destination dataset 部分,选择相应的数据集。

    • 对于 Destination table,输入目标表的名称。目标表必须遵循表命名规则。目标表名称也支持使用参数

    • Cloud Storage URI 部分,输入 Cloud Storage URI。您可以使用通配符参数

    • 如果您希望在每次成功转移后删除源文件,请选中 Delete source files after transfer 复选框。系统会尽量运行删除作业。如果首次删除源文件失败,则系统不会重试删除作业。

    • File format 部分,输入要转移的文件类型

    • Transfer Options - All Formats 部分下:

      • 对于 Number of errors allowed,输入 BigQuery 在运行作业时可以忽略的错误记录数上限。 如果错误记录数超过此限值,作业结果中将返回一个“无效”错误,并且作业将失败。默认值为 0
    • Transfer Options - JSON, CSV 部分下:

      • 如果您想让转移作业删除不符合目标表架构的数据,请选中 Ignore unknown values 复选框。
    • Transfer Options - CSV 部分下:

      • 对于 Field delimiter,输入用于分隔字段的字符。 默认值为英文逗号。
      • Header rows to skip 部分,如果您不想导入源文件中的标题行,请输入相应的标题行数。默认值为 0
      • 如果您想要允许在引用字段中使用换行符,请选中 Allow quoted newlines 复选框。
      • 如果您想要允许转移缺少 NULLABLE 列内容的行,请选中 Allow jagged rows 复选框。

      新建 Cloud Storage 转移作业

    • (可选)展开 Advanced 部分,并为转移作业配置运行通知。转移作业运行通知目前为 Alpha 版

    • Cloud Cloud Pub/Sub topic 部分,输入您的 Cloud Pub/Sub 主题名称,例如 projects/myproject/topics/mytopic

    • 勾选 Send email notifications,让系统在转移作业运行失败时发送电子邮件通知。

      Cloud Cloud Pub/Sub 主题

  5. 点击 Add

CLI

输入 bq mk 命令并提供转移作业创建标志 --transfer_config。此外,还必须提供以下标志:

  • --data_source
  • --display_name
  • --target_dataset
  • --params
bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--params='parameters'

其中:

  • project_id 是您的项目 ID。如果未提供 --project_id 来指定具体项目,则系统会使用默认项目。
  • data_source 是数据源:google_cloud_storage
  • name 是转移作业配置的显示名。转移作业名称可以是任何容易辨识的值,方便您以后在需要修改名称时能轻松识别相应的转移作业。
  • dataset 是转移作业配置的目标数据集
  • parameters 包含所创建的转移作业配置的参数(采用 JSON 格式)。例如:--params='{"param":"param_value"}'
    • 对于 Cloud Storage,您必须提供 data_path_templatedestination_table_name_templatefile_format 参数。data_path_template 是包含待转移文件的 Cloud Storage URI,其中可包含一个通配符。destination_table_name_template 是目标表的名称。对于 file_format,请指明要转移的文件类型:CSVJSONAVROPARQUETORC。默认值为 CSV。
    • 对于所有 file_format 值,您可以添加可选参数 max_bad_records。默认值为 0
    • 对于 file_format 中的 JSON 或 CSV 值,您可以添加可选参数 ignore_unknown_values。如果您没有为 file_format 选择 CSVJSON,此参数会被忽略。
    • 对于 CSV file_format,您可以为用于分隔字段的字符添加可选参数 field_delimiter。默认值为英文逗号。如果您没有为 file_format 选择 CSV,此参数会被忽略。
    • 对于 CSV file_format,您可以添加可选参数 skip_leading_rows,以指明您不想导入的标题行。默认值为 0。如果您没有为 file_format 选择 CSV,此参数会被忽略。
    • 对于 CSV file_format,如果您想要允许在引用字段中使用换行符,则可以添加可选参数 allow_quoted_newlines。如果您没有为 file_format 选择 CSV,此参数会被忽略。
    • 对于 CSV file_format,如果您想要接受末尾处缺少可选列的行,则可以添加可选参数 allow_jagged_rows。系统将填入 NULL 来代替缺少的值。 如果您没有为 file_format 选择 CSV,此参数会被忽略。
    • 每次成功转移后,可选参数 delete_source_files 将删除源文件。(如果首次删除源文件失败,则系统不会重试删除作业。)delete_source_files 的默认值为 false。

例如,以下命令使用 data_path_templategs://mybucket/myfile/*.csv、目标数据集 mydatasetfile_format CSV 创建一个名为 My Transfer 的 Cloud Storage 转移作业。此示例包含与 CSV file_format 关联的可选参数的非默认值。

该转移作业将在默认项目中创建:

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage

运行命令后,您会收到如下消息:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

请按照说明操作,并将身份验证代码粘贴到命令行中。

API

使用 projects.locations.transferConfigs.create 方法并提供一个 TransferConfig 资源实例。

设置转移作业的刷新运行

除了设置数据源为 Cloud Storage 的周期性转移作业外,您还可以设置刷新运行以选取其他数据文件。

如果转移作业配置与日期相关(已参数化),并且/或者 Cloud Storage URI 已参数化,那么您可以在特定日期运行刷新转移作业。

要设置刷新转移作业,请执行以下操作:

控制台

  1. 打开 GCP Console。

    转到 GCP Console

  2. 点击转移

  3. 点击您的转移作业。

  4. 点击更多菜单,然后选择刷新转移作业。

  5. 安排回填时间对话框中,选择开始日期和结束日期。您可以使用经典版 BigQuery 网页界面来设置更精细的时间限制。

    设置刷新日期

经典版界面

  1. 转到 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 点击 Transfers

  3. 点击您的转移作业。

  4. 点击 Refresh Transfer

    刷新转移作业

  5. Start Transfer Runs 对话框中,选择 Start Time 和 End Time。

    设置刷新日期

    如果您的 Cloud Storage 转移作业配置没有参数化,那么当您点击 Refresh Transfer 后,将不会看到日期选项。 在这种情况下,系统会立即执行刷新。

    立即刷新

  6. 点击 OK

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面