| name | analytics-collect |
| description | Use when YouTube Analyticsデータの収集・最新化が必要なとき。/analytics-analyze 実行前のデータ準備ステップとして使用。ユーザーが「データ更新」「最新の数字」「統計を取得」「分析の準備」と言及したとき、または analytics_system.py の実行が必要な場面で必ず使用すること |
Overview
analytics_system.py を実行し、チャンネルの YouTube Analytics データを収集します。
前提
config/channel/ が存在すること（load_config() でロード可能）。
存在しない場合、ユーザーに確認:
- 新規チャンネル →
/channel-new を案内
- 既存チャンネル（YouTube で既に運営中）→
/channel-import を案内
When to Use
- 分析の前にデータを最新化したいとき
- チャンネル統計・動画別パフォーマンスデータが必要なとき
/analytics-analyze 実行前のデータ収集ステップとして
Quick Reference
| 引数 | 説明 |
|---|
/analytics-collect | デフォルト: 効率モード（上位50本 + 直近30日投稿） |
$ARGUMENTS | モード指定（省略可） |
鮮度チェック（並列実行対応）
実行前に既存データの鮮度を確認する:
ls -t data/analytics_data_*.json 2>/dev/null | head -1 で最新ファイルを取得- ファイルの更新時刻が 30分以内 → 収集をスキップし、既存データを使用
- 30分以上経過 or ファイルなし → 通常どおり下記コマンドを実行
スキップ時: 「既存データが十分新しいため収集をスキップしました（<filename>、<N>分前に収集）」と表示。
実行コマンド
uv run yt-analytics
出力
- チャンネル統計データ
- 動画別パフォーマンス分析
- 戦略的分析結果
- JSON データファイル保存（
data/ ディレクトリ）
出力例
📊 YouTube Analytics データ収集
チャンネル: <channel_config: channel.name>
期間: YYYY-MM-DD 〜 YYYY-MM-DD
✅ チャンネル統計: 登録者 X / 総再生 Y
✅ 動画パフォーマンス: 上位50本 + 直近30日投稿を収集
✅ データ保存: data/analytics_YYYYMMDD.json
データ収集完了後、/analytics-analyze で詳細分析を実行してください。
障害時ガイダンス
| 状況 | 兆候 | 対処 |
|---|
| OAuth 未認証/失効 | auth.oauth_handler の FileNotFoundError（client_secrets.json 不在）/ AuthError / HTTP 403 | 初回認証フローを再実行。403 が続く場合は auth/token.json を削除しスコープを確認のうえ再認証 |
| YouTube quota / rate | HTTP 429 / 403 quotaExceeded | 日次 quota（既定 10,000 units・太平洋時間 0 時リセット）を待つか呼び出しを抑える |
| API 障害 / サービス停止 | HTTP 503 / タイムアウト | Google Cloud / YouTube のステータスを確認し、時間を置いて再実行 |
Next Step
データ収集完了後:
→ /analytics-analyze で収集データの詳細分析を実行
