Youtube Analytics Import Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

Treasure DataのCustomer Data Platformを使用して、YouTube Analyticsデータを取り込みます。

前提条件

以下の基本的な知識が必要です

• Treasure Data Console（およびToolbelt）
• YouTube Analytics

TD Consoleからの使用

TD ConsoleからData Connectorを作成できます。これが最も一般的な方法です。

新しい接続の作成

Treasure Data Catalogにアクセスし、YouTubeを検索して選択します。

次のダイアログが開きます。

認証モードのいずれかを選択します：

• OAuth
• Your custom OAuth app

Your custom OAuth appが推奨されるモードです。詳細については、Q&Aセクションを参照してください。

Your custom OAuth appを選択した場合は、以下のパラメータを指定してください：

• OAuth client_id: Google Consoleで設定したカスタムOAuthアプリのclient_id。詳細については、付録を参照してください。
• OAuth client_secret: Google Consoleで設定したカスタムOAuthアプリのclient_secret。詳細については、付録を参照してください。
• OAuth refresh_token: カスタムOAuthアプリのすべてのスコープを許可するアカウントのrefresh_token。詳細については、付録を参照してください。

OAuthを選択した場合は、既存のOAuth接続を選択するか、Click Hereをクリックして新しいアカウントを接続します。

Continueをクリックします。コネクタの名前を入力します。Doneをクリックします。

新しいSourceの作成

保存された認証情報からNew Sourceをクリックします

https://www.youtube.com/yt/creators/benefits/プログラムに参加している場合は、アカウントのCMS IDとChannel IDsを入力してください。そうでない場合は、パラメータを空白のままにしてください。

Report Type（Video、Playlist、またはChannel）を選択し、レポートプリセットを選択します。

パラメータ：

• CMS ID: YouTube Partner Programに参加している場合のYouTubeアカウントのCMS ID。それ以外の場合は空白のままにしてください。
• Channel IDs: Content Ownerの管理下にあるChannel IDsのリスト。パートナーではないYouTubeアカウントの場合は、空白のままにしてください。
• Report Type: 分析の対象となる期待されるターゲット：video、playlist、またはchannels。
• Report Presets: ディメンション、メトリクス、およびフィルタのコレクション。
• Playlists: ビデオのリストをフィルタリングするためのplaylist IDs。このパラメータは、Videosレポートプリセットでのみ使用できます。
• Dimensions: Analyticsディメンションのリスト
• Metrics: Analyticsメトリクスのリスト
• Filters: フィルタのリスト（このパラメータは一部のプリセットにのみ表示されます）
• Max Results: APIが返す分析レコードの数。このパラメータは特定のレポートでのみ必須です。それ以外の場合は、すべての分析を取得するために空白のままにしてください。
• Sort: APIからの分析結果をソートするためのメトリクス。このパラメータは特定のレポートでのみ必須です。
• Include Historical Channel Data: Content Ownerに参加する前のチャネルの履歴分析をYouTube Analytics APIが返すかどうかを指定します。このパラメータは、Content Owner以外のレポートでは必須ではありません。
• Load from published date: 指定されたReport Typeの最も古い公開日が、分析を取得する開始日になります。
• Begin date: 分析を取得する開始日（「Load from published date」または「Begin date」のいずれかを指定する必要があります）。
• End date: 分析を取得する終了日（この日を含む）。
• Aggregation Period (Day): 分析の各レコードをグループ化する日数。
• Duration (Day): 次の増分実行時に現在の終了日から分析を取得する日数。
• Incremental: スケジュールで実行する場合、取得データの時間ウィンドウが実行ごとに自動的に前進します。たとえば、初期設定が1月1日で、1月15日まで取得し、期間が10日の場合、最初の実行では1月1日から1月15日までの変更データを取得し、2回目の実行では1月16日から1月25日まで取得します。
• Ignore Empty Playlist: エラーをスローする代わりに空のプレイリストをスキップします

Data Preview

インポートを実行する前に、Generate Preview を選択してデータのプレビューを表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. Next を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、Generate Preview を選択します。
3. データを確認します。

Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. Next を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。

2. Database を選択 > Select an existing または Create New Database を選択します。

3. オプションで、database 名を入力します。

4. Table を選択 > Select an existing または Create New Table を選択します。

5. オプションで、table 名を入力します。

6. データをインポートする方法を選択します。

   • Append (デフォルト) - データインポートの結果は table に追加されます。 table が存在しない場合は作成されます。
   • Always Replace - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
   • Replace on New Data - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。

7. Timestamp-based Partition Key 列を選択します。 デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。

8. データストレージの Timezone を選択します。

9. Schedule の下で、このクエリを実行するタイミングと頻度を選択できます。

一度だけ実行

1. Off を選択します。
2. Scheduling Timezone を選択します。
3. Create & Run Now を選択します。

定期的に繰り返す

1. On を選択します。
2. Schedule を選択します。UI では、@hourly、@daily、@monthly、またはカスタム cron の 4 つのオプションが提供されます。
3. Delay Transfer を選択して、実行時間の遅延を追加することもできます。
4. Scheduling Timezone を選択します。
5. Create & Run Now を選択します。

転送が実行された後、Data Workbench > Databases で転送の結果を確認できます。

コマンドラインの使用

必要に応じて、TD ConsoleではなくCLIからData Connectorを作成できます。

前提条件のインストール

Ruby gemを使用して最新のtdツールをインストールします：

$ gem install td
$ td --version
0.16.1

他のインストール方法もあります。詳細については、Treasure Data Toolbeltを参照してください。

設定ファイルの作成（config.yml）

• 例（config.yml）

以下は、YouTubeチャンネル上のすべてのビデオの日次基本統計をリクエストする設定ファイルの例です。

in:
  type: youtube
  client_id: xxxxxxxxxxxxx
  client_secret: xxxxxxxxxxxxx
  access_token: xxxxxxxxxxxxx
  refresh_token: xxxxxxxxxxxxx
  report_type: video
  video_report_preset: basic_statistics
  skip_dimension: false
  dimension_video_basic_statistics: country
  metric_video_basic_statistics: views,comments,likes,dislikes
  begin_date: 2018-01-01
  end_date: 2018-02-01
  duration: 30
  interval: 1
  ignore_empty_playlist: true
out:
  mode: append

認証

Google Appで認証するためのclient_id、client_secret、access_token、およびrefresh_tokenを指定します。詳細については、付録を参照してください。

Report Type

report_typeパラメータで分析を取得するターゲットを指定します：

• video: チャンネル内または特定のプレイリスト（playlistパラメータでカンマ区切りのPlaylist IDsリストとして指定）内の個々のビデオの分析を取得します。
• playlist: 個々のプレイリストの分析を取得します
• channel: アカウントの管理下にある個々のチャンネルの分析を取得します。

プリセットまたは個別のディメンションとメトリクスの選択

プリセットは、事前定義されたパラメータのグループです。以下は、このパラメータで使用可能な列挙子と、それに相当するパラメータのグループです。

videoおよびchannel report_typeの場合：

basic_statistics

dimension: country
metric: views,comments,likes,dislikes,videosAddedToPlaylists,videosRemovedFromPlaylists,shares,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,annotationClickThroughRate,annotationCloseRate,annotationImpressions,annotationClickableImpressions,annotationClosableImpressions,annotationClicks,annotationCloses,cardClickRate,cardTeaserClickRate,cardImpressions,cardTeaserImpressions,cardClicks,cardTeaserClicks,subscribersGained,subscribersLost

basic_statistics_co

dimension: country
metric: views,comments,likes,dislikes,videosAddedToPlaylists,videosRemovedFromPlaylists,shares,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,annotationClickThroughRate,annotationCloseRate,annotationImpressions,annotationClickableImpressions,annotationClosableImpressions,annotationClicks,annotationCloses,cardClickRate,cardTeaserClickRate,cardImpressions,cardTeaserImpressions,cardClicks,cardTeaserClicks,subscribersGained,subscribersLost,estimatedRevenue,estimatedAdRevenue,grossRevenue,estimatedRedPartnerRevenue,monetizedPlaybacks,playbackBasedCpm,adImpressions,cpm

basic_statistics_us

dimension: province,subscribedStatus
metric: views,redViews,estimatedMinutesWatched,estimatedRedMinutesWatched,averageViewDuration,averageViewPercentage,annotationClickThroughRate,annotationCloseRate,annotationImpressions,annotationClickableImpressions,annotationClosableImpressions,annotationClicks,annotationCloses,cardClickRate,cardTeaserClickRate,cardImpressions,cardTeaserImpressions,cardClicks,cardTeaserClicks
filter: country==US

playback_detail

dimension: country,liveOrOnDemand,subscribedStatus,youtubeProduct
metric: views,estimatedMinutesWatched,averageViewDuration

playback_detail_us

dimension: province,liveOrOnDemand,subscribedStatus,youtubeProduct
metric: views,redViews,estimatedMinutesWatched,estimatedRedMinutesWatched,averageViewDuration
filter: country==US

dimension: province,liveOrOnDemand,subscribedStatus,youtubeProduct
metric: views,redViews,estimatedMinutesWatched,estimatedRedMinutesWatched,averageViewDuration
filter: country==US

playback_location

dimension: insightPlaybackLocationType,liveOrOnDemand,subscribedStatus
metric: views,estimatedMinutesWatched

playback_location_detail

dimension: insightPlaybackLocationDetail
metric: views,estimatedMinutesWatched
filter: insightPlaybackLocationType==EMBEDDED
max_results: 25
sort: -views

playback_traffic_source

dimension: insightTrafficSourceType,liveOrOnDemand,subscribedStatus
metric: views,estimatedMinutesWatched

playback_traffic_source_detail

dimension: insightTrafficSourceDetail
metric: views,estimatedMinutesWatched
filter: insightTrafficSourceType==YT_SEARCH
max_results: 25
sort: -views

device_os_type

dimension: deviceType,operatingSystem,liveOrOnDemand,subscribedStatus,youtubeProduct
metric: views,estimatedMinutesWatched

viewer_demographic

dimension: ageGroup,gender
metric: viewerPercentage

engagement_and_content_sharing

dimension: sharingService,subscribedStatus
metric: shares

audience_retention (動画のみ)

dimension: elapsedVideoTimeRatio
metric: audienceWatchRatio,relativeRetentionPerformance
filter: audienceType==ORGANIC

プレイリスト report_type の場合:

basic_statistics

dimension: country,subscribedStatus,youtubeProduct
metric: views,estimatedMinutesWatched,averageViewDuration,playlistStarts,viewsPerPlaylistStart,averageTimeInPlaylist
filter: isCurated==1

basic_statistics_us

dimension: province,subscribedStatus,youtubeProduct
metric: views,redViews,estimatedMinutesWatched,estimatedRedMinutesWatched,averageViewDuration,playlistStarts,viewsPerPlaylistStart,averageTimeInPlaylist
filter: isCurated==1;country==US

playback_location

dimension: insightPlaybackLocationType,subscribedStatus
metric: views,estimatedMinutesWatched,playlistStarts,viewsPerPlaylistStart,averageTimeInPlaylist
filter: isCurated==1

traffic_source

dimension: insightTrafficSourceType,subscribedStatus
metric: views,estimatedMinutesWatched,playlistStarts,viewsPerPlaylistStart,averageTimeInPlaylist
filter: isCurated==1

device_os_type

dimension: deviceType,operatingSystem,subscribedStatus,youtubeProduct
metric: views,estimatedMinutesWatched,playlistStarts,viewsPerPlaylistStart,averageTimeInPlaylist
filter: isCurated==1

viewer_demographic

dimension: ageGroup,gender
metric: viewerPercentage
filter: isCurated==1

dimension および metric パラメータ（および他の必須パラメータ）の値については、Google の以下の記事で確認できます:

https://developers.google.com/youtube/analytics/channel_reports

https://developers.google.com/youtube/analytics/content_owner_reports

その他のパラメータ

プレビュー

td connector:preview config.yml

ロードジョブの実行

データを格納するデータベースとテーブルを指定する必要があります。

Treasure Data はストレージを時間で分割するため、--time-column オプションを指定することをお勧めします。このオプションが利用できない場合、データコネクタは最初の long 型または timestamp 型の列をパーティション時間として選択します。--time-column で指定する列の型は、long 型または timestamp 型のいずれかである必要があります (利用可能な列名と型を確認するには、プレビュー結果を使用してください)。時間列は出力の最後に利用できます。

データに時間列がない場合は、add_time フィルタオプションを使用して列を追加できます。詳細については、add_time フィルタ関数 を参照してください。

ロードジョブを投入します。データサイズによっては、数時間かかる場合があります。データを格納するデータベースとテーブルを指定する必要があります。

td connector:issue config.yml \
  --database sample_db \
  --table sample_table

td connector:issue は、すでにデータベース (sample_db) とテーブル (sample_table) を作成していることを前提としています。データベースまたはテーブルが TD に存在しない場合、td connector:issue は失敗します。したがって、データベースとテーブルを手動で作成するか、td connector:issue で --auto-create-table を使用してデータベースとテーブルを自動的に作成する必要があります:

td connector:issue config.yml \
  --database sample_db \
  --table sample_table \
  --auto-create-table

スケジュール実行

定期的なYouTubeインポートのために、データコネクタの実行をスケジュール設定できます。この機能を使用することで、ローカルデータセンターにcronデーモンを設定する必要がなくなります。

スケジュールの作成

td connector:createで新しいスケジュールを作成します。スケジュール名、cron形式のスケジュール、データを保存するデータベースとテーブル、およびData Connector設定ファイルが必須です。

td connector:create \
daily_youtube_import \
"10 0 * * *" \
sample_db \
sample_table \
config.yml

cronパラメータは、@hourly、@daily、@monthlyの3つのオプションも受け付けます。詳細については、スケジュールジョブを参照してください。

デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。--timezoneまたは-tオプションを使用してタイムゾーンを設定できます。--timezoneオプションは、Asia/Tokyo、America/Los_Angelesなどの拡張タイムゾーン形式のみをサポートします。PST、CSTなどのタイムゾーンの略語はサポートされておらず、予期しないスケジュールになる可能性があります。

スケジュールの一覧表示

現在スケジュールされているエントリのリストは、td connector:listで確認できます。

td connector:list

スケジュールの設定と履歴の表示

td connector:showは、スケジュールエントリの実行設定を表示します。

td connector:show daily_youtube_import

制限事項

YouTube Analyticsデータはパシフィック標準時(PST)に基づいており、最大72時間の遅延があります(https://support.google.com/youtube/answer/1714329?hl=en)。

削除された動画とプレイリストの分析データは取得できません。

YouTube API クォータとカスタムOAuthアプリについて

YouTubeには、YouTube Analytics API クォータに関して以下の制限があります:

コネクタは、日次のYouTube分析データを取り込むために多数のYouTube API呼び出しを行います。たとえば、チャンネルに1000本の動画があり、100日分の履歴データをインポートする場合、API呼び出しの合計数は1,000×100 = 100,000になります。

コネクタは、YouTube APIをさらに実行する前に、実行されるリクエストの総数を見積もります。見積もりが100,000を超える場合、ジョブは停止します。集計期間を長くするか、終了日を早めるかのいずれかを行う必要があります。見積もりの計算方法は次のとおりです。

4つの動画があるとします:

• 動画1は2010-02-10に公開
• 動画2は2012-03-11に公開
• 動画3は2016-04-12に公開
• 動画4は2018-05-13に公開

次の例では、開始日はデータコネクタがYouTube Analyticsから分析データの取得を開始する日付です。公開日は動画がYouTubeで公開された日付です。終了日は、Treasure Dataで取り込みセッションを終了するように指定した日付です。

終了日が2017-06-14で、開始日が2010-01-01の場合、集計期間は7です。1つの動画の総呼び出し数を計算する式は次のとおりです: 終了日 - 開始日 + 1 / 集計期間(開始日は公開日と同じ日付)。

終了日は含まれます。つまり、そのend_dateで利用可能な分析データも取り込まれます。4つの動画の場合:

• 動画1: ("2017-06-14" - "2010-02-10") / 7 = 3040 / 7 = 435
• 動画2: ("2017-06-14" - "2012-03-11") / 7 = 2280 / 7 = 326
• 動画3: ("2017-06-14" - "2016-04-12") / 7 = 425 / 7 = 61
• 動画4は、終了日の後に公開されているためスキップされます。終了日は2017年で、動画4は2018年に公開されています

リクエストの総数の見積もりは: 435 + 326 + 61 = 822リクエストです。これは100,000リクエスト未満であるため問題ありません。

複数の入力に同じ接続(新しい接続の作成を参照)を使用すると、クォータがすぐに使い果たされ、インポートジョブが停止します。回避策は、異なるOAuthアプリで複数の接続を作成することです(付録を参照)。

Q&A

コンテンツオーナーレポートプリセットの分析データを取得できないのはなぜですか?

コンテンツオーナーレポートは、https://www.youtube.com/yt/creators/benefits/プログラムに参加しているアカウントでのみ利用できます。このYouTubeプログラムに参加していない場合、コンテンツオーナー分析の取得は例外を引き起こします。

最終日と今日のTD分析がYouTubeサイトとYouTube Analyticsダッシュボードに表示されるものと一致しないのはなぜですか?

分析データが蓄積されるまで最大72時間かかることに注意してください。詳細については、https://support.google.com/youtube/answer/1714329?hl=enを参照してください。

YouTube Creator Studioダッシュボードに表示されるデータと取り込まれるデータの間に不一致があるのはなぜですか?

詳細なテスト中に、YouTube Creator Studioに表示される分析データと取り込まれるデータの間にいくつかの不一致があることがわかりました。調査した結果、いくつかの理由がわかりました:

1. 表示する際、Creator Studioレポートは、Webサイトにデータを表示する前に一部の数値を四捨五入します。
2. YouTube Analytics APIは、返される分析データに一部の制限を適用します。Creator Studioと一致させるには、特定のディメンションとフィルタを削除する必要がある場合があります。詳細については、https://support.google.com/youtube/answer/9101241を参照してください

基本統計プリセットにredViewsメトリックが含まれていないのはなぜですか?

テストフェーズ中に、リクエストにディメンションとメトリックの特定の組み合わせが含まれている場合、YouTube Analytics APIは通知や例外なしに空のレコードを返すことがわかりました。たとえば、国(country)とredViewsメトリックが同じリクエストにある場合、分析データは返されません。

redViewsメトリックを取得するには、国(country)ディメンションを削除する必要があります。逆も同様です。そのため、このディメンションとメトリックのペアを持つレポートプリセットはありません。

TrueView経由でYouTube動画にアクセスしたユーザーの分析データを取り込むにはどうすればよいですか?

TrueViewからのビュー数を取得するには、プリセット: 再生トラフィックソース詳細を使用しますが、フィルタパラメータをinsightTrafficSourceType==YT_SEARCHからinsightTrafficSourceType==ADVERTISINGに変更します。取り込まれたinsightTrafficSourceDetail列には、「TrueView in-search and in-display」や「TrueView in-stream」などの値が保持されます。insightTrafficSourceTypeとinsightTrafficSourceDetailの可能な値のリストについては、https://developers.google.com/youtube/analytics/dimensions#Traffic_Source_Dimensionsを参照してください。

デフォルトのプリセット「再生トラフィックソース詳細」は、動画またはチャンネルにつながるトップ25の検索用語を取得します。YT_SEARCHからADVERTISINGに変更すると、insightTrafficSourceDetailの値のセットが異なります。

1か月前にアップロードして1週間前に公開した動画が、公開日からの分析データのみを表示するのはなぜですか?

動画の作成と動画のアップロードは同じです。ただし、動画の作成日と公開日には違いがあります。動画がYouTubeチャンネルにアップロードされた場合、それはまだプライベート動画であり、公開されるまで誰もその動画を視聴できません。作成時から公開時までインタラクションデータがないため、YouTube Analytics APIから返される分析データは公開時以降のもののみです。

付録

カスタムOAuthアプリの作成方法

以下の手順では、https://console.developers.google.comでカスタムOAuthアプリを設定する方法を示します。

新しいGoogleプロジェクトの作成

Google Cloud Consoleで新しいプロジェクトを作成するには、https://cloud.google.com/resource-manager/docs/creating-managing-projectsに従ってください。

APIとサービスの有効化

https://cloud.google.com/apis/docs/enable-disable-apis?hl=enに従って、以下のAPIを有効にします:

• YouTube Analytics API
• YouTube Data API v3

OAuth Client IDの作成

承認されたリダイレクトURIにhttps://developers.google.com/oauthplaygroundを追加すると、OAuth Playgroundを使用してrefresh_tokenを取得するのに役立ちます。他の方法がある場合は、OAuth Playgroundを追加する必要はありません。

client idとsecretの保存

次の手順で使用するために、client idとsecretをコピーしてどこかに保存します。

refresh_tokenの取得方法

以下の手順では、OAuth Playgroundを使用して、YouTubeデータ接続を作成するためのrefresh_tokenを取得する方法を示します。この情報を取得する他の方法がある場合は、OAuth Playgroundを使用する必要はありません。

OAuth PlaygroundでClient IdとSecretを設定

https://developers.google.com/oauthplayground/にアクセスします

付録で設定したIDとSecretを入力します。

スコープの指定

Input your own scopesボックスに次のスコープを貼り付けます:

https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/yt-analytics-monetary.readonly https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email

スコープの許可

Authorize APIsをクリックし、通常のGoogleの手順に従ってログインし、スコープを許可します。

refresh_tokenのリクエスト

Exchange authorization code for tokensをクリックします。

プロセスが完了するまで待ってから、Refresh tokenをコピーして、Treasure Data YouTubeコネクタ設定で使用します。