将 YouTube 频道数据加载到 BigQuery 中

您可以使用适用于 YouTube 频道的 BigQuery Data Transfer Service 连接器将数据从 YouTube 频道加载到 BigQuery。借助 BigQuery Data Transfer Service，您可以安排周期性转移作业，以将 YouTube 频道中的最新数据添加到 BigQuery。

连接器概览

适用于 YouTube 频道连接器的 BigQuery Data Transfer Service 支持以下数据转移选项。

数据转移选项	支持
支持的报告	YouTube 频道连接器支持从频道报告转移数据。 YouTube 频道连接器支持 2018 年 6 月 18 日的 API 版本。 如需了解 YouTube 频道报告如何转换为 BigQuery 表和视图，请参阅 YouTube 频道报告转换。
重复频率	YouTube 频道连接器支持每天转移数据。 默认情况下，数据转移是在创建数据转移时安排的。您可以在设置数据转移时配置数据转移时间。
刷新时段	YouTube 频道连接器会检索数据转移运行时最多 1 天前的 YouTube 频道数据。 如需了解详情，请参阅刷新时段。
回填数据可用性	运行数据回填，以检索预定数据转移之外的数据。您可以检索的数据最早可追溯到数据源的数据保留政策允许的最早时间。 包含历史数据的 YouTube 报告自生成之日起 30 天内可用。（包含非历史数据的报告在 60 天内可用。）如需了解详情，请参阅历史数据。

从 YouTube 频道转移中注入数据

当您将数据从 YouTube 频道转移到 BigQuery 时，系统会将数据加载到按日期分区的 BigQuery 表中。数据加载到的表分区对应于数据源中的日期。如果您在同一日期安排多次转移，BigQuery Data Transfer Service 会使用最新数据覆盖该特定日期的分区。同一天的多个转移作业或正在运行的回填不会导致重复数据，其他日期的分区不受影响。

刷新时段

刷新时段是指发生数据转移时数据转移检索数据的天数。例如，如果刷新时段为三天，并且每天进行转移，则 BigQuery Data Transfer Service 会从过去三天内的源表中检索所有数据。在此示例中，当每天进行转移时，BigQuery Data Transfer Service 会使用当前日期的源表数据副本创建新的 BigQuery 目标表分区，然后自动触发回填运行作业，以使用过去两天的源表数据来更新 BigQuery 目标表分区。自动触发的回填运行作业会覆盖或以增量方式更新 BigQuery 目标表，具体取决于 BigQuery Data Transfer Service 连接器是否支持增量更新。

首次运行数据转移作业时，数据转移作业会检索刷新时段内可用的所有源数据。例如，如果刷新时段为三天，并且您首次运行数据转移作业，则 BigQuery Data Transfer Service 会检索三天内的所有源数据。

刷新时段会映射到 TransferConfig.data_refresh_window_days API 字段。

如需检索刷新时段之外的数据（例如历史数据），或在出现任何转移中断或缺口时恢复数据，您可以启动或安排回填运行作业。

限制

• 每个报告支持的文件大小上限为 1710 GB。
• 可安排数据转移作业的最小频率为每 24 小时一次。默认情况下，数据转移作业从创建转移作业时开始。但是，您可以在设置转移作业时配置数据转移作业开始时间。
• BigQuery Data Transfer Service 不支持在 YouTube 内容所有者转移期间执行增量数据转移。指定数据转移的日期时，系统会转移该日期的所有数据。
• 如果您以联合身份登录，则无法创建 YouTube 频道数据转移作业。您只能在使用 Google 账号登录时创建 YouTube 频道转移作业。

准备工作

创建 YouTube 频道数据转移作业之前，请先做好以下准备工作：

• 确认您已完成启用 BigQuery Data Transfer Service 所需的所有操作。
• 创建 BigQuery 数据集以存储 YouTube 数据。

所需权限

创建 YouTube 频道数据转移作业需要以下权限：

• YouTube：YouTube 频道的所有权

• BigQuery：BigQuery 中的以下 Identity and Access Management (IAM) 权限：

  • 用于创建转移作业的 bigquery.transfers.update。
  • 目标数据集的 bigquery.datasets.get 和 bigquery.datasets.update 权限。
  • 如果您要设置 Pub/Sub 的转移作业运行通知，必须拥有 pubsub.topics.setIamPolicy 权限。如果您只是要设置电子邮件通知，则无需 Pub/Sub 权限。如需了解详情，请参阅 BigQuery Data Transfer Service 运行通知。

预定义的 IAM 角色 bigquery.admin 具有创建 YouTube 频道数据转移作业所需的所有 BigQuery 权限。如需详细了解 BigQuery 中的 IAM 角色，请参阅预定义的角色和权限。

设置 YouTube 频道转移作业

设置 YouTube 频道数据转移作业需要提供以下信息：

• 表后缀：您在设置数据转移作业时为频道提供的简单易记的名称。系统会将此后缀附加到作业 ID 的后面以创建表名称，例如 reportTypeId_suffix。此后缀用于防止不同的转移作业写入相同的表。在将数据加载到同一数据集的所有转移作业中，表后缀必须是唯一的，而且要简短，以尽量缩短所生成的表名称的长度。

如果您使用 YouTube Reporting API，并且已有报告作业，则 BigQuery Data Transfer Service 会加载您的报告数据。如果您还没有报告作业，则设置转移作业会自动启用 YouTube 报告作业。

如需创建 YouTube 频道数据转移作业，请执行以下操作：

控制台

1. 前往 Google Cloud 控制台中的“数据转移”页面。

   转到“数据传输”

2. 点击 创建转移作业。

3. 在创建转移作业页面上：

   • 在来源类型部分的来源中，选择 YouTube 频道。

     

   • 在转移配置名称部分的显示名称中，输入数据转移作业的名称，例如 My Transfer。转移作业名称可以是任何可让您以后在需要修改转移作业时识别该转移作业的值。

     

   • 在时间表选项部分中，执行以下操作：

     • 在重复频率部分，从选项中选择数据转移作业的运行频率。如果您选择天，请提供世界协调时间 (UTC) 的有效时间。
     • 如果适用，请选择立即开始或从设置的时间开始，并提供开始日期和运行时间。

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

     

   • 在数据源详细信息部分，执行以下操作：

     • 在 Table suffix（表后缀）部分，输入后缀，例如 MT。
     • 选中 Configure jobs（配置作业）复选框，以允许 BigQuery 为您管理 YouTube 报告作业。如果您的账号还没有对应的 YouTube 报告，系统会创建新的报告作业来启用它们。

     

   • （可选）在通知选项部分，执行以下操作：

     • 点击切换开关以启用电子邮件通知。启用此选项后，转移作业管理员会在转移作业运行失败时收到电子邮件通知。
     • 在选择 Pub/Sub 主题部分，选择主题名称或点击创建主题。此选项用于为数据转移作业配置 Pub/Sub 运行通知。

4. 点击保存。

bq

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

• --data_source
• --target_dataset
• --display_name
• --params

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

其中：

• project_id 是项目 ID。
• dataset 是转移作业配置的目标数据集。
• name 是转移作业配置的显示名。数据转移作业名称可以是任何可让您以后需要修改转移作业时识别该转移作业的值。
• parameters 包含所创建转移作业配置的参数（采用 JSON 格式），例如 --params='{"param":"param_value"}'。对于 YouTube 频道数据转移作业，您必须提供 table_suffix 参数。您可以选择将 configure_jobs 参数设置为 true，以允许 BigQuery Data Transfer Service 为您管理 YouTube 报告作业。如果您的频道目前没有 YouTube 报告，系统会创建新的报告作业来启用报告。
• data_source 是数据源，即 youtube_channel。

注意：您无法使用命令行工具配置通知。

您还可以提供 --project_id 标志以指定具体项目。如果未指定 --project_id，系统会使用默认项目。

例如，以下命令使用表后缀 MT 和目标数据集 mydataset 创建名为 My Transfer 的 YouTube 频道数据转移作业。该数据转移作业将在默认项目中创建：

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"table_suffix":"MT","configure_jobs":"true"}' \
--data_source=youtube_channel

注意：当您使用命令行工具创建 YouTube 频道转移作业时，系统会使用时间表的默认值来设置转移作业配置。

API

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

Java

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。 如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create youtube channel transfer config.
public class CreateYoutubeChannelTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableSuffix = "_test";
    Map<String, Value> params = new HashMap<>();
    params.put("table_suffix", Value.newBuilder().setStringValue(tableSuffix).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Youtube Channel Config Name")
            .setDataSourceId("youtube_channel")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createYoutubeChannelTransfer(projectId, transferConfig);
  }

  public static void createYoutubeChannelTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Youtube channel transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Youtube channel transfer was not created." + ex.toString());
    }
  }
}

注意：如果您是首次设置 YouTube 报告作业，则会遇到延迟，您的第一批报告最长可能需要 48 小时才能完成。如需了解详情，请参阅 YouTube Reporting API 文档中的创建报告作业。

查询数据

当数据转移到 BigQuery 时，这些数据会写入注入时间分区表。如需了解详情，请参阅分区表简介。

如果您要直接查询表，而不是使用自动生成的视图，则必须在查询中使用 _PARTITIONTIME 伪列。如需了解详情，请参阅查询分区表。

排查 YouTube 频道转移作业设置问题

如果您在设置数据转移作业时遇到问题，请参阅排查转移作业配置问题中的 YouTube 转移作业问题。