將 YouTube 頻道資料載入 BigQuery

您可以使用 YouTube 頻道連接器的 BigQuery 資料移轉服務,將 YouTube 頻道資料載入 BigQuery。您可以使用 BigQuery 資料移轉服務,安排週期性移轉工作,將 YouTube 頻道的最新資料新增至 BigQuery。

連接器總覽

YouTube 頻道連接器的 BigQuery 資料移轉服務支援下列資料移轉選項。

資料移轉選項 支援
受支援的報表 YouTube 頻道連接器支援從頻道報表轉移資料。

YouTube 頻道連接器支援 2018 年 6 月 18 日的 API 版本。

如要瞭解 YouTube 頻道報表如何轉換為 BigQuery 資料表和檢視表,請參閱「YouTube 頻道報表轉換」。

重複頻率 YouTube 頻道連接器支援每日資料移轉。

根據預設,資料移轉作業會排定在建立資料移轉作業時執行。您可以在設定資料移轉作業時,設定資料移轉時間。
重新整理時間範圍 YouTube 頻道連接器會在執行資料移轉作業時,擷取最多 1 天的 YouTube 頻道資料。

詳情請參閱「重新整理時間範圍」。
補充資料可用性 在每次排定的移轉作業執行期間,YouTube 頻道連接器會自動回填新產生或更新的報表,最多可回溯至移轉作業執行日期前 60 天。詳情請參閱「自動補播」。

您也可以執行資料補充作業,手動擷取排定資料移轉作業以外的資料。您可以擷取資料來源資料保留政策允許範圍內的資料。

含有歷來資料的 YouTube 報表自產生當日起有 30 天的效期。(不含歷來資料的報表可保留 60 天)。詳情請參閱「歷來資料」。

從 YouTube 頻道移轉作業擷取資料

將 YouTube 頻道資料移轉至 BigQuery 時,資料會載入依日期分區的 BigQuery 資料表。資料載入的資料表分區會對應至資料來源的日期。如果您在同一天安排多項移轉作業,BigQuery 資料移轉服務會以最新資料覆寫該日期的分區。在同一天進行多次移轉或執行補充作業,不會產生重複資料,其他日期的分區也不會受到影響。

重新整理時間範圍

「更新回溯期」是指資料移轉時,資料移轉作業擷取資料的天數。舉例來說,如果更新時間範圍為三天,且每天都會進行移轉,BigQuery 資料移轉服務會從來源資料表擷取過去三天的所有資料。在本例中,每日移轉作業執行時,BigQuery 資料移轉服務會建立新的 BigQuery 目的地資料表分區,並複製當天的來源資料表資料,然後自動觸發補充執行作業,使用過去兩天的來源資料表資料更新 BigQuery 目的地資料表分區。自動觸發的回填執行作業會覆寫或增量更新 BigQuery 目的地資料表,具體取決於 BigQuery 資料移轉服務連接器是否支援增量更新。

首次執行資料移轉作業時,系統會擷取重新整理期間內的所有可用來源資料。舉例來說,如果更新時間範圍為三天,且您首次執行資料移轉作業,BigQuery 資料移轉服務會擷取三天內的所有來源資料。

這個連接器會自動回填過去 60 天內延遲或更新的報表。如要擷取更新時間範圍以外的其他資料 (例如歷來資料),或復原任何因移轉中斷或缺漏而遺失的資料,您可以手動啟動或排定補充執行作業。

自動候補

如果 YouTube 頻道報表延遲或重新產生先前日期的報表,BigQuery 資料移轉服務會自動回填報表。在每次排定的移轉作業執行期間,BigQuery 資料移轉服務會檢查過去 60 天內產生的報表,以及上次排定的移轉作業執行後產生的報表。只要有新報表,BigQuery 資料移轉服務就會自動安排回填移轉作業,將更新後的資料載入對應的資料表分區。如果 YouTube 報表在這 60 天內延遲或更新,您不需要手動觸發回填。

限制

  • 資料移轉作業的排程頻率下限為每 24 小時一次。根據預設,資料移轉作業會在您建立移轉作業時開始。不過,您可以在設定移轉作業時,指定資料移轉開始時間。
  • BigQuery 資料移轉服務不支援在 YouTube 內容擁有者移轉期間,進行增量資料移轉。指定資料移轉日期後,系統會移轉該日期可用的所有資料。
  • 如果以聯合身分登入,則無法建立 YouTube 頻道資料移轉作業。您必須使用 Google 帳戶登入,才能建立 YouTube 頻道轉移作業。
  • 您只能從與建立資料移轉作業的 Google 帳戶相關聯的 YouTube 頻道移轉資料。詳情請參閱「YouTube 頻道移轉作業的授權考量」。

事前準備

建立 YouTube 頻道資料移轉作業前,請先完成下列事項:

所需權限

請確認您已授予下列權限。

必要的 BigQuery 角色

如要取得建立 BigQuery 資料移轉服務資料移轉作業所需的權限,請要求管理員授予您專案的 BigQuery 管理員 (roles/bigquery.admin) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立 BigQuery 資料移轉服務資料移轉作業所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

您必須具備下列權限,才能建立 BigQuery 資料移轉服務資料移轉作業:

  • BigQuery 資料移轉服務權限:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • BigQuery 權限:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

詳情請參閱「授予 bigquery.admin 存取權」。

必要的 YouTube 頻道角色

你必須擁有 YouTube 頻道。

設定 YouTube 頻道轉移作業

如要設定 YouTube 頻道資料移轉作業,必須具備:

  • 表格後置字串:您在設定資料移轉作業時,為管道提供的容易使用名稱。這個尾碼會附加至工作 ID,以便建立表格名稱,例如 reportTypeId_suffix。後置字串可用於防止不同的移轉作業寫入同一個資料表。所有將資料載入同個資料集的移轉工作,其資料表後置字串都不能重複,且後置字串應盡量簡短,避免產生過於冗長的資料表名稱。

如果您使用 YouTube Reporting API,且已有報表工作,BigQuery 資料移轉服務會載入報表資料。如果沒有現有的報表工作,設定移轉作業時,系統會自動啟用 YouTube 報表工作。

如要建立 YouTube 頻道資料移轉作業,請按照下列步驟操作:

控制台

  1. 前往 Google Cloud 控制台的「資料移轉」頁面。

    前往「資料移轉」

  2. 按一下「 建立移轉作業」。

  3. 在「Create Transfer」(建立轉移作業) 頁面:

    • 在「Source type」(來源類型) 區段,針對「Source」(來源) 選取 [YouTube Channel] (YouTube 頻道)。

      移轉作業來源

    • 在「Transfer config name」(轉移設定名稱) 部分,「Display name」(顯示名稱) 請輸入資料移轉作業的名稱,例如 My Transfer。移轉作業名稱可以是任意值,日後需要修改移轉作業時能夠據此識別。

      移轉作業名稱

    • 在「Schedule options」(排程選項) 專區:

      • 在「Repeat frequency」(重複頻率) 部分選取選項,指定資料移轉作業的執行頻率。如果選取「Days」(天),請按照世界標準時間提供有效的值。
      • 視情況選取「Start now」(立即開始) 或「Start at set time」(在所設時間開始執行),並提供開始日期和執行時間。
    • 在「Destination settings」(目的地設定) 部分,「Destination dataset」(目的地資料集) 請選取您為了儲存資料而建立的資料集。

      移轉資料集

    • 在「Data source details」(資料來源詳細資料) 區段:

      • 在「Table Suffix」(資料表後置字串) 中輸入後置字串,例如 MT。
      • 勾選「Configure jobs」(設定工作) 方塊,允許 BigQuery 代您管理 YouTube 報表工作。如果您的帳戶還沒有特定 YouTube 報表,必須建立新的報表工作才能移轉。

      YouTube 頻道來源詳細資料

    • (選用) 在「Notification options」(通知選項) 區段中:

      • 按一下啟用電子郵件通知的切換開關。當您啟用此選項時,移轉管理員會在移轉作業失敗時收到電子郵件通知。
      • 在「Select a Pub/Sub topic」(選取 Pub/Sub 主題) 選取主題名稱,或是點選「Create a topic」(建立主題)。這個選項會針對資料移轉作業設定 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 資料移轉服務代您管理 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

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 頻道連接器會根據您的排程選項,自動觸發移轉作業。每次執行移轉作業時,YouTube 頻道連接器都會從與使用者憑證 (用於建立這項資料移轉作業) 相關聯的 YouTube 頻道移轉所有可用資料。

如要進一步瞭解各項 YouTube 頻道移轉作業包含的資料,請參閱「YouTube 頻道移轉作業的授權注意事項」。

如要在排程時間以外手動執行資料移轉作業,可以啟動補充執行作業。

查詢資料

資料移轉至 BigQuery 時,系統會將資料寫入擷取時間分區資料表。詳情請參閱分區資料表簡介一文。

如果您直接查詢資料表,而非使用自動生成的檢視表,則必須在查詢中使用 _PARTITIONTIME 虛擬資料欄。詳情請參閱查詢分區資料表一文。

排解 YouTube 頻道移轉作業設定問題

如果無法順利設定資料移轉作業,請參閱「排解移轉設定問題」中的「YouTube 移轉問題」一節。