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 偏好设置触发,该偏好设置会将数据附加到目标表中。如需了解详情,请参阅加载配置下的 configuration.load.writeDisposition
  • 如果数据集的位置设置为 US 以外的值,则区域或多区域 Cloud Storage 存储分区必须与数据集位于相同的区域。

Cloud Storage 源数据可能还会受到其他限制,具体取决于源数据的格式。如需了解详情,请参阅以下内容:

所需权限

当您将数据加载到 BigQuery 中时,您需要拥有项目级层或数据集级层的权限,以便能够将数据加载到新的或现有的 BigQuery 表和分区中。如果要从 Cloud Storage 加载数据,您还需要拥有数据所在存储分区的访问权限。确保您拥有以下必备权限:

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

设置 Cloud Storage 转移作业

要在 BigQuery Data Transfer Service 中创建 Cloud Storage 转移作业,请按如下所述操作:

Console

  1. 转到 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 点击转移作业

  3. 点击 + 创建

  4. 创建转移作业页面上,执行以下操作:

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

      转移作业来源

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

      转移作业名称

    • 时间安排选项部分的时间安排中,保留默认值(立即开始)或点击从设置的时间开始

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

        转移作业时间安排

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

      转移作业数据集

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

      • 目标表部分,输入目标表的名称。目标表必须遵循表命名规则。目标表名称也支持使用参数
      • 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,如果您想要允许在引用字段中使用换行符,请选中此复选框。
      • 对于 Allow jagged rows 部分,如果您想要允许转移缺少 NULLABLE 列内容的行,请选中此复选框。

      新建 Cloud Storage 传输作业

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

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

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

      Cloud Pub/Sub 主题

  5. 点击 Add

命令行

输入 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
  • --display_name 是转移作业配置的显示名称。转移作业名称可以是任何容易辨识的值,以便您以后需要修改转移作业时易于识别它。
  • --target_dataset 是转移作业配置的目标数据集。
  • --params 包含所创建的转移作业配置的参数(采用 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。

例如,以下命令使用 gs://mybucket/myfile/*.csvdata_path_template 值、目标数据集 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 已参数化,那么您可以在特定日期运行刷新转移作业。

要设置刷新转移作业,请按如下所述操作:

Console

  1. 在 GCP Console 中打开 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 点击转移作业

  3. 点击您的转移作业。

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

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

    设置刷新日期

经典版界面

  1. 转到 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 点击 Transfers

  3. 点击您的传输作业。

  4. 点击 Refresh Transfer

    刷新转移作业

  5. Start Transfer Runs 对话框中,选择 Start TimeEnd Time

    设置刷新日期

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

    立即刷新

  6. 点击 OK

后续步骤

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

发送以下问题的反馈:

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