YouTube コンテンツ所有者の転送

BigQuery Data Transfer Service for YouTube のコンテンツ所有者コネクタを使用すると、YouTube コンテンツ所有者レポートの定期的な読み込みジョブを自動的にスケジュールして管理できます。

サポートされるレポート

コンテンツ所有者レポート
システム管理レポート

BigQuery Data Transfer Service for YouTube のコンテンツ所有者レポートでは、次のレポートオプションがサポートされています。

レポートオプション	サポート
サポート対象の API バージョン	2018 年 6 月 18 日
繰り返しの頻度	毎日、UTC 時間の 14 時 45 分頃時刻を設定できます。
更新ウィンドウ	過去 1 日構成不可
最大バックフィル期間	30 日 2018 年 7 月現在、過去のデータを含む YouTube レポートは、生成後 30 日間利用できます（履歴データ以外のデータを含むレポートは、ポリシー変更後 60 日間利用できます）。詳細については、YouTube Reporting API ドキュメントの履歴データをご覧ください。

YouTube コンテンツ所有者レポートがどのように BigQuery のテーブルとビューに変換されるかについては、YouTube コンテンツ所有者レポートの変換をご覧ください。

YouTube コンテンツ所有者の転送からのデータ取り込み

YouTube コンテンツ所有者レポートから BigQuery にデータを転送すると、データは日付でパーティション分割された BigQuery テーブルに読み込まれます。データが読み込まれるテーブルパーティションは、データソースの日付に対応します。同じ日付の複数の転送をスケジュールすると、BigQuery Data Transfer Service により、対象の日付のパーティションが最新のデータで上書きされます。同じ日に複数回の転送やバックフィルを実行しても、データは重複せず、他の日付のパーティションに対する影響はありません。

更新ウィンドウ

更新ウィンドウとは、データ転送が行われたときにデータ転送でデータが取得される日数です。たとえば、更新ウィンドウが 3 日であり、毎日転送が行われる場合、BigQuery Data Transfer Service は過去 3 日間のソーステーブルからすべてのデータを取得します。この例では、毎日転送が発生すると、BigQuery Data Transfer Service は、当日のソーステーブルのデータのコピーを含む新しい BigQuery 宛先テーブルパーティションを作成し、バックフィル実行を自動的にトリガーして、過去 2 日間のソーステーブルのデータで BigQuery 宛先テーブルパーティションを更新します。自動トリガーされたバックフィル実行は、BigQuery Data Transfer Service コネクタで増分更新がサポートされているかどうかに応じて、BigQuery の宛先テーブルを上書きするか、増分更新します。

データ転送を初めて実行する際に、更新ウィンドウ内で利用可能なすべてのソースデータを取得します。たとえば、更新ウィンドウが 3 日であり、データ転送を初めて実行する場合は、BigQuery Data Transfer Service によって 3 日以内のすべてのソースデータが取得されます。

更新ウィンドウは TransferConfig.data_refresh_window_days API フィールドにマッピングされます。

更新ウィンドウの期間外のデータ（過去のデータなど）を取得する場合や、転送の停止やギャップからデータを復元する場合は、バックフィル実行を開始またはスケジュールできます。

制限事項

各レポートでサポートされている最大ファイルサイズは 1,710 GB です。
データ移転をスケジュールできる最短の頻度は 24 時間に 1 回です。デフォルトでは、データ転送は、作成した時点でその転送が開始されます。ただし、転送を構成する際に、転送の開始時間を構成できます。
BigQuery Data Transfer Service は、YouTube コンテンツ所有者の転送時のデータの増分転送はサポートしていません。データ転送の日付を指定すると、その日付で使用できるすべてのデータが転送されます。

始める前に

YouTube コンテンツ所有者のデータ転送を作成する前に、以下を行います。

BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
YouTube データを格納する BigQuery データセットを作成します。
YouTube コンテンツ所有者アカウントを持っていることを確認します。YouTube コンテンツ所有者と YouTube チャンネルとは同じではありません。通常、さまざまなチャンネルを管理する場合は、YouTube コンテンツ所有者アカウントのみが必要です。
Pub/Sub の転送実行通知を設定する場合は、pubsub.topics.setIamPolicy 権限が必要です。メール通知を設定するだけの場合、Pub/Sub の権限は必要ありません。詳細については、BigQuery Data Transfer Service の実行通知をご覧ください。

必要な権限

データ転送を作成するユーザーに、次の必要な権限が付与されていることを確認します。

BigQuery:
- データ転送を作成する bigquery.transfers.update 権限
- bigquery.datasets.get と bigquery.datasets.update の両方（抽出先データセットに対する権限）
bigquery.transfers.update 権限、bigquery.datasets.update 権限、bigquery.datasets.get 権限は、IAM 事前定義ロール bigquery.admin に含まれています。BigQuery Data Transfer Service での IAM ロールについて、詳しくはアクセス制御をご覧ください。
YouTube:
- YouTube コンテンツマネージャまたは YouTube コンテンツ所有者。
コンテンツマネージャには、コンテンツ所有者の YouTube コンテンツを管理する権限が付与されます。コンテンツ所有者とは、1 つ以上の YouTube チャンネルとそのチャンネルの動画を所有するアカウントのことです。
- YouTube コンテンツ所有者レポートの設定で、Hide revenue data がオフになっていること。
収益に関連するレポートを転送するには、転送を作成するユーザーの YouTube レポート権限の設定で Hide revenue data をオフにする必要があります。

YouTube コンテンツ所有者の転送を設定する

YouTube コンテンツ所有者のデータ転送を設定するには、以下が必要です。

コンテンツ所有者 ID: YouTube から提供されます。YouTube にコンテンツ所有者またはコンテンツ管理者としてログインすると、URL の o= の後に ID が表示されます。たとえば、URL が https://studio.youtube.com/owner/AbCDE_8FghIjK?o=AbCDE_8FghIjK の場合、コンテンツ所有者 ID は AbCDE_8FghIjK です。別のコンテンツ管理者アカウントを選択するには、コンテンツマネージャアカウントにログインするまたは YouTube チャンネルの切り替えツールをご覧ください。コンテンツ管理者アカウントの作成と管理の詳細については、コンテンツマネージャのアカウント設定をご覧ください。
テーブルサフィックス: 転送を設定するときにユーザーが指定するユーザーフレンドリーなチャンネル名です。サフィックスがジョブ ID に追加され、テーブル名が作成されます（例: reportTypeId_suffix）。このサフィックスは、別のデータ転送による同じテーブルへの書き込みを防ぐために使用されます。テーブルサフィックスは、同じデータセットにデータを読み込むすべての転送で一意にします。また、生成されるテーブル名の長さを抑えるために短くする必要があります。

YouTube Reporting API を使用しており、既存のレポート作成ジョブが存在する場合は、BigQuery Data Transfer Service によってユーザーのレポートデータが読み込まれます。既存のレポート作成ジョブがない場合は、データ転送を設定すると、YouTube レポート作成ジョブが自動的に有効になります。

YouTube コンテンツ所有者のデータ転送を設定するには:

コンソール

Google Cloud コンソールの [BigQuery] ページに移動します。コンテンツ所有者またはコンテンツマネージャとしてアカウントにログインしていることを確認します。

[BigQuery] ページに移動
[転送] をクリックします。
[転送を作成] をクリックします。
[転送の作成] ページで、次の操作を行います。
- [ソースタイプ] セクションの [ソース] で、YouTube コンテンツ管理者を選択します。
- [転送構成名] セクションの [表示名] に、データ転送の名前（例: My Transfer）を入力します。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
- [スケジュールオプション] セクションで:
  - [繰り返しの頻度] で、データ転送を実行する頻度のオプションを選択します。[日数] を選択した場合は、有効な時刻を UTC で入力します。
    - 時間
    - 日数
    - オンデマンド
  - 必要に応じて、[すぐに開始可能] を選択するか、[設定した時刻に開始] を選択して開始日と実行時間を指定します。
- [転送先の設定] セクションの [宛先データセット] で、データを保存するために作成したデータセットを選択します。
- [データソースの詳細] セクションで、次の操作を行います。
  - [コンテンツ所有者 ID] に、コンテンツ所有者 ID を入力します。
  - [テーブルサフィックス] に、サフィックス（例: MT）を入力します。
- [サービスアカウント] メニューで、Google Cloud プロジェクトに関連付けられたサービスアカウントからサービスアカウントを選択します。ユーザー認証情報を使用する代わりに、サービスアカウントをデータ転送に関連付けることができます。データ転送でサービスアカウントを使用する方法の詳細については、サービスアカウントの使用をご覧ください。
  - フェデレーション ID でログインした場合、データ転送を作成するにはサービスアカウントが必要です。Google アカウントでログインした場合、データ転送用のサービスアカウントは省略可能です。
  - サービスアカウントには必要な権限が付与されている必要があります。
- （省略可）[通知オプション] セクションで、次の操作を行います。
  - 切り替えボタンをクリックしてメール通知を有効にします。このオプションを有効にすると、データ転送に失敗した場合、転送の管理者にメール通知が送信されます。
  - [Pub/Sub トピックを選択] で、トピック名を選択するか、[トピックを作成する] をクリックします。このオプションで、Pub/Sub の転送実行通知を構成します。
[保存] をクリックします。
初めてアカウントにログインする場合は、アカウントを選択して [許可] をクリックします。コンテンツ所有者またはコンテンツマネージャと同じアカウントを選択します。

bq

bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。次のフラグも必要です。

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

オプションのフラグ:

--service_account_name - ユーザーアカウントの代わりにコンテンツ所有者の転送認証に使用するサービスアカウントを指定します。

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

各要素の意味は次のとおりです。

project_id は、プロジェクト ID です。
dataset は、転送構成の抽出先データセットです。
name は、転送構成の表示名です。データ転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
parameters には、作成される転送構成のパラメータを JSON 形式で指定します。例: --params='{"param":"param_value"}'。YouTube コンテンツ所有者のデータ転送では、content_owner_id パラメータと table_suffix パラメータを指定する必要があります。必要に応じて configure_jobs パラメータを true に設定し、BigQuery Data Transfer Service に YouTube のレポート作成ジョブの管理を許可します。まだアカウントに存在しない YouTube レポートがある場合は、新しいレポート作成ジョブが作成されて対象のレポートが有効になります。
data_source は、データソース（youtube_content_owner）です。
service_account_name は、データ転送の認証に使用されるサービスアカウント名です。サービスアカウントは、転送の作成に使用した project_id が所有している必要があります。また、必要な権限がすべて付与されている必要があります。

--project_id フラグを指定して、特定のプロジェクトを指定することもできます。--project_id を指定しない場合は、デフォルトのプロジェクトが使用されます。

たとえば、次のコマンドは、コンテンツ所有者 ID AbCDE_8FghIjK、テーブルサフィックス MT、ターゲットデータセット mydataset を使用して、My Transfer という名前の YouTube コンテンツ所有者のデータ転送を作成します。このデータ転送はデフォルトのプロジェクトで作成されます。

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

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 content owner channel transfer config
public class CreateYoutubeContentOwnerTransfer {

  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 contentOwnerId = "MY_CONTENT_OWNER_ID";
    String tableSuffix = "_test";
    Map<String, Value> params = new HashMap<>();
    params.put("content_owner_id", Value.newBuilder().setStringValue(contentOwnerId).build());
    params.put("table_suffix", Value.newBuilder().setStringValue(tableSuffix).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Youtube Owner Channel Config Name")
            .setDataSourceId("youtube_content_owner")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createYoutubeContentOwnerTransfer(projectId, transferConfig);
  }

  public static void createYoutubeContentOwnerTransfer(
      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 content owner channel transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Youtube content owner channel transfer was not created." + ex.toString());
    }
  }
}

データに対するクエリを実行する

データが BigQuery に転送されると、取り込み時間パーティション分割テーブルにそのデータが書き込まれます。詳細については、パーティション分割テーブルをご覧ください。

自動生成されたビューを使用せずに、テーブルで直接クエリする場合は、そのクエリで _PARTITIONTIME 疑似列を使用する必要があります。詳細については、パーティション分割テーブルのクエリをご覧ください。

YouTube コンテンツ所有者の転送設定のトラブルシューティング

データ転送を設定する際に問題が発生した場合は、転送構成のトラブルシューティングにある YouTube の転送に関する問題をご覧ください。