YouTubeコメント収集で返信が漏れる理由：2階層のページネーションと完全性の検証

YouTubeコメントのスクレイピングで返信が欠落する場合、最初に確認すべきはcommentThreadsだけを読み取っていないかどうかです。スレッド一覧に含まれる返信は完全とは限りません。動画のスレッドはページネーションで取得する必要があり、各トップレベルコメントの返信も個別にページネーションが必要な場合があります。1階層目の最後まで到達しても、すべての返信を取得できたとは限りません。

これは新しい問題ではありません。Baskaya氏はStack Overflowの過去の議論で、返信数と実際に返される内容の不一致を指摘しています。古い回答にはGoogle+連携時代の推測が含まれており、現在の問題を説明できるものではありません。今でも役立つのは、そこで提起された問いです。数えているのはスレッドか、コメントか、それともAPIレスポンスに付随する返信の一部か、という問いです。

本記事では、2026年9月5日時点の公式ドキュメントに基づいてこの違いを説明し、取り込み結果の検証方法を紹介します。扱うのはYouTube APIの公式ルールであり、EveryInfraのテストレポートではなく、アクセスできないコンテンツの復元を約束するものでもありません。

commentThreadsの返信が不完全になる理由

YouTubeのリソースドキュメントによると、commentThreadには1件のトップレベルコメントと、場合によってはそれに付随する返信が含まれます。トップレベルコメントはsnippet.topLevelCommentに、返信のリストはreplies.commentsに格納されていますが、後者には一部の返信しか含まれない場合があります。snippet.totalReplyCountはそのトップレベルコメントに対する返信数を表すもので、スレッド一覧全体の件数とそのまま比較することはできません。EveryInfraのYouTubeコメントAPIは、各コメントのreply_countを返します。エクスポート後は、この値を使って実際に取得できた返信数を確認してください。

人工的に作成したスレッドで返信数が12件と示されているのに、現在のオブジェクトには5件しか含まれていないとします。この5件だけでスクレイパーが取得完了と判断することはできず、返却する配列を12要素まで埋めるべきでもありません。正しい対応は、次回は自動的に返信が増えることを期待して同じスレッドオブジェクトを繰り返しリクエストするのではなく、その親コメントの返信エンドポイントへのリクエストを続けることです。

もう一つ見落としやすいのが、スレッドIDとトップレベルコメントIDの違いです。これらはそれぞれのリソースから別々に読み取って記録する必要があります。あるサンプルで2つの文字列がたまたま同じだったとしても、プログラムが常に置き換え可能だとみなしてよいことにはなりません。データモデル上で同じに見えても、APIの定義上で同じ役割を持つとは限りません。

トップレベルコメントと返信それぞれのページネーション進捗管理

公式のcommentThreads.listでは、videoIdでスレッドを取得し、レスポンスのnextPageTokenを使って次のページを取得できます。maxResultsは1ページあたり最大100件です。これは動画のコメントを一度にすべて取得できるリクエストではなく、1つのスレッドの返信が最大100件までという意味でもありません。

特定のトップレベルコメントについては、comments.listのルールに従い、そのコメントIDをparentIdに渡して、返信クエリ固有のnextPageTokenを処理します。このページトークンは返信クエリに属するもので、動画のスレッドクエリに渡すことはできず、別の親コメントのトークンを再利用することもできません。

実装は2つのタスク層に分けられます。動画単位のタスクでトップレベルコメントを検出し、親コメント単位のタスクで追加の返信を取得します。親コメントごとに、それぞれの再開位置と終了理由を保持します。これにより、返信数が極端に多いスレッドがあっても、完了済みの他のスレッドまで最初からやり直す必要はありません。

進捗と一緒にリクエスト条件も保存しておく必要があります。たとえばsearchTermsを使ったかどうか、どの並べ替え方法を選んだか、対象の動画は何か、といった情報です。最初からキーワードで絞り込んでいた場合、その後の完全性の判断はそのクエリの範囲にしか当てはまりません。エクスポートファイルでフィルタ条件を省略し、「この動画の全コメント」であるかのように見せてはいけません。

ログと結果の両方への完了条件の記録

コメントの内容とスクレイピングの進捗は分けて扱うことをおすすめします。内容はプラットフォームとコメントIDで重複排除し、動画、親コメントとの関連、観測時刻を保持します。一方、進捗は現在のタスクがどこまで進んだかを表します。これらはアプリケーション側の設計上の提案であり、以下のフィールドはYouTubeやEveryInfraがそのまま返すフィールドではありません。

最小限の進捗レコードでも、次の点がわかるようにします。スレッド一覧が最終ページに達したか、どの親コメントが返信の末尾まで達したか、どれがリクエストの失敗やタスクの予算によって停止したか、最後に確認した時刻はいつか。success: trueだけでは、「トップレベルは完了したが、ある親コメントにまだ未取得のページが2つ残っている」という状態を表現できません。

重複排除はコンテンツの保存時に行います。ページを書き込んだ後にプロセスが終了すると、復旧時に同じページを再度取得する可能性があります。重複をコメント本文で判断するより、IDをもとに既存のレコードを更新するほうが確実です。2人が同じ短いフレーズを書いても、それは2件のコメントです。また、1件のコメントの本文が編集されても、編集前後を直ちに別々の意見2件として扱うべきではありません。

進捗は、コンテンツの保存に成功してから進める必要があります。現在のページを保存する前に次のページを記録すると、途中で失敗した場合にデータを取りこぼすおそれがあります。重複排除を前提に再読み込みを許容するほうが、ページが気付かれないままスキップされるのを許容するより、一般に検証が容易です。カーソルが重複した場合や、新しいIDが長時間現れない場合は、実行を停止して異常として報告してください。同じページの再試行を繰り返すことを、有効な進捗とみなしてはいけません。

解消できないコメント数の不一致

まずオブジェクトの階層、フィルタ条件、2階層のページネーションを確認し、その後でエラーの種類を見ます。公式のスレッド一覧のドキュメントでは、commentsDisabled、権限不足、動画が存在しない場合が区別されています。いずれも「この動画には現在コメントがない」として扱ってはいけません。クエリが成功した結果としての空配列と、クライアントで例外が握りつぶされたために返された空配列は、同じ根拠にはなりません。

件数の不一致については、観測した期間も記録しておく必要があります。ページ上に表示される件数、スレッドのメタデータ、ページネーションの結果は、まったく同じ時点で取得されたものとは限りません。件数の差だけでは、どのコンテンツが欠けているかは特定できず、ましてやその本文を生成することはできません。読み取れるテキストを分析する際は、実際に取得でき、投稿元を特定できるコメントをサンプルとして使い、取得できていない範囲は公開時に明示してください。

ステータスの確認結果は、「このクエリのスレッド一覧は最終ページまで取得済みで、親コメントに対する返信取得タスクが2つ未完了」のように、検証可能な表現で記述することをおすすめします。「完全性98%」と書くより誠実です。後者には、同じ定義に基づく信頼できる分母が必要だからです。分母がないのに、一見正確そうな割合を作り出してはいけません。

一般的なHTTPやパラメータの問題については、ドキュメントのAPIエラーハンドリングを参照してください。リトライで一時的な障害の一部には対処できますが、権限を広げたり、部分的な返信オブジェクトを完全なデータセットに変えたりすることはできません。

4つの小規模なサンプルによるスクレイパーの検証

アクセス可能なテスト対象や人工的に作成したフィクスチャで4つのシナリオを確認すると、最初から大量の動画を一括で処理するよりもエラーを切り分けやすくなります。

1. スレッド内の返信数が公称返信数を下回る場合：プログラムはすぐに完了と判定せず、返信取得タスクを作成する必要があります。
2. 返信リストに次のページがある場合：プログラムは動画のスレッド一覧をページ送りするだけでなく、その親コメントの処理を続ける必要があります。
3. 同じページを2回読み込んだ場合：重複を除いた最終的なコメント数が2倍になってはならず、親子関係も一貫している必要があります。
4. 親コメントのリクエストが失敗した場合：他の結果は保持してかまいませんが、エクスポートでは一部が未完了であることを示す必要があり、以前の有効な結果を空の返信で上書きしてはいけません。

受け入れテストでは、出力が実際に役立つかどうかも確認します。トピック分類を行う場合、「これは間違っている」のような返信は、親コメントから切り離されるとほとんど解釈できなくなります。親コメントとの関連を保持しておけば、人間やモデルが議論の文脈に立ち返りやすくなります。ドキュメントのDouyinのコメントと返信の関係でもこのモデリングの問題を扱っていますが、プラットフォームが異なればリクエストパラメータをそのまま流用することはできません。

以上は推奨するテストであり、本記事で実際の動画を使って実施した実験ではありません。APIからエクスポートしたJSONがすでにある場合は、データの再取得に許可が必要かどうかを判断する前に、これらの構造と状態をオフラインで検証できます。

範囲を限定したコメントサンプルの納品

「何件スクレイピングしたか」は結果の一部にすぎません。分析に適したエクスポートには、対象、フィルター、収集日時、親子関係、重複排除の方法、未完了の項目についての説明も含める必要があります。分析レポートでもこれらの範囲を引き継ぎ、要約段階に入ったからといって、前の工程ですでに判明している欠落を省いてはいけません。

パッケージ化されたデータAPIを選ぶ際は、統合データAPI入門にあるディレクトリの確認方法を使い、実際にどのフィールドとページネーション機能が提供されているかを項目ごとに確認してください。本記事で紹介した公式のパラメータを別のAPIにそのまま当てはめたり、「コメントに対応」とあるからといって、すべての階層や過去のコンテンツまで網羅されていると考えたりしないでください。

YouTubeのコメント収集で重要なのは、1ページあたりの上限を引き上げ続けることではなく、各返信の紐付け先、各ページネーションタスクの進捗、各処理の終了理由を説明できる状態に保つことです。そうして初めて、スクレイピング結果は取りこぼしを説明できないファイルではなく、分析の根拠として使えるものになります。