このページは Cloud Translation API によって翻訳されました。

YouTube Reporting API - Get Bulk Data Reports

YouTube では、クリエイターツールで対応するレポートにアクセスできるコンテンツ所有者向けに、システム管理の広告収益レポートが自動的に生成されます。これらのレポートは、YouTube クリエイターツールの [レポートメニュー] で手動でダウンロードできるレポートでも確認できるデータに、プログラムでアクセスできるように設計されています。

注: API でアクセスできるレポートは、YouTube Studio のレポートとは異なりますが、レポートに含まれるデータは類似しています。API レポートには、クリエイターツールのレポートとは異なるフィールドが含まれ、異なるフィールド名が使用されている場合があります。

YouTube ではシステム管理レポートが自動的に生成されるため、これらのレポートを取得するプロセスは、API で利用できる YouTube アナリティクスのバルクデータレポートとは異なります。

レポートの取得

次の手順では、API を介してシステム管理レポートを取得する方法について説明します。

ステップ 1: 認証情報を取得する

YouTube Reporting API へのすべてのリクエストは承認を受ける必要があります。認可ガイドでは、OAuth 2.0 プロトコルを使用して認可トークンを取得する方法について説明しています。

YouTube Reporting API リクエストでは、次の認証スコープが使用されます。

スコープ
https://www.googleapis.com/auth/yt-analytics.readonly	YouTube コンテンツの YouTube アナリティクスレポートを表示します。このスコープは再生回数や評価数など、ユーザーアクティビティの指標へのアクセスを提供します。
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	YouTube コンテンツに関する YouTube アナリティクス収益レポートを表示します。このスコープは、ユーザーアクティビティの指標と、推定収益と広告パフォーマンスの指標へのアクセスを提供します。

ステップ 2: 目的のレポートのジョブ ID を取得する

jobs.list メソッドを呼び出して、システム管理ジョブのリストを取得します。includeSystemManaged パラメータを true に設定します。

返された各 Job リソースの reportTypeId プロパティは、そのジョブに関連付けられているシステム管理レポートのタイプを識別します。次のステップでは、同じリソースの id プロパティ値が必要です。

レポートドキュメントには、利用可能なレポート、レポートタイプの ID、レポートに含まれるフィールドが記載されています。reportTypes.list メソッドを使用して、サポートされているレポートタイプの一覧を取得することもできます。

ステップ 3: レポートのダウンロード URL を取得する

jobs.reports.list メソッドを呼び出して、ジョブ用に作成されたレポートの一覧を取得します。リクエストで、jobId パラメータを取得するレポートのジョブ ID に設定します。

次のパラメータのいずれかまたはすべてを使用して、レポートのリストをフィルタできます。

createdAfter パラメータを使用して、指定した日時以降に作成されたレポートのみを API が返すように指定します。このパラメータを使用すると、API がまだ処理していないレポートのみを返すようにできます。
startTimeBefore パラメータを使用して、レポート内の最も古いデータが指定した日付より前の場合にのみ、API レスポンスにレポートを含めるように指定します。createdAfter パラメータはレポートが作成された時刻に関連しますが、この日付はレポート内のデータに関連します。
startTimeAtOrAfter パラメータを使用して、レポートの最も古いデータが指定した日付以降の場合にのみ、API レスポンスにレポートを含めるように指定します。startTimeBefore パラメータと同様に、このパラメータ値はレポートのデータに対応しており、レポートの作成時間には対応していません。

API レスポンスには、そのジョブの Report リソースのリストが含まれます。各リソースは、一意の期間のデータを含むレポートを参照します。

リソースの startTime プロパティと endTime プロパティは、レポートのデータが対象とする期間を示します。
リソースの downloadUrl プロパティは、レポートを取得できる URL を識別します。
リソースの createTime プロパティは、レポートが生成された日時を指定します。アプリケーションはこの値を保存し、以前にダウンロードしたレポートが変更されたかどうかを判断するために使用する必要があります。

ステップ 4: レポートをダウンロードする

ステップ 4 で取得した downloadUrl に HTTP GET リクエストを送信して、レポートを取得します。

レポートの処理

ベストプラクティス

YouTube Reporting API を使用するアプリは、常に次のプラクティスに従う必要があります。

レポートのヘッダー行を使用して、レポートの列の順序を決定します。たとえば、レポートの説明に最初に記載されている指標が「ビュー」であるからといって、レポートで最初に返される指標が「ビュー」であるとは限りません。代わりに、レポートのヘッダー行を使用して、そのデータを含む列を特定します。
同じレポートを繰り返し処理しないように、ダウンロードしたレポートの記録を保持します。以下に、そのための 2 つの方法を示します。
- reports.list メソッドを呼び出す際は、createdAfter パラメータを使用して、特定の日付以降に作成されたレポートのみを取得します。（レポートを初めて取得するときは、createdAfter パラメータを省略します）。
  
  レポートを取得して正常に処理するたびに、それらのレポートの最新のものが作成された日時に対応するタイムスタンプを保存します。次に、reports.list メソッドの呼び出しごとに createdAfter パラメータの値を更新して、API を呼び出すたびに、バックフィルされたデータを含む新しいレポートのみを取得するようにします。
  
  安全対策として、レポートを取得する前に、レポートの ID がデータベースにまだ登録されていないことを確認してください。
- ダウンロードして処理した各レポートの ID を保存します。各レポートが生成された日時や、レポートにデータが含まれる期間を特定するレポートの startTime と endTime などの追加情報を保存することもできます。YouTube アナリティクスのデータを一括で取得するレポートの場合、各レポートには 24 時間分のデータが含まれているため、各ジョブには多くのレポートが含まれる可能性があります。より長い期間を対象とするシステム管理ジョブでは、レポートの数が少なくなります。
  
  レポート ID を使用して、ダウンロードとインポートが必要なレポートを特定します。ただし、2 つの新しいレポートの startTime プロパティと endTime プロパティの値が同じ場合は、createTime 値が新しいレポートのみをインポートします。

レポートの特性

API レポートは、次の特性を持つバージョン管理された .csv（カンマ区切り値）ファイルです。

各レポートには、レポートの開始日の午前 12 時（太平洋時間）からレポートの終了日の午後 11 時 59 分（太平洋時間）までの期間のデータが含まれています。
レポートのデータが並べ替えられていない。

YouTube Reporting API - Get Bulk Data Reports コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。