YouTube では、クリエイター ツール内の対応するレポートへのアクセス権を持つコンテンツ所有者向けに、システムが管理する一連の広告収益レポートが自動的に生成されます。これらのレポートは、プログラムでデータにアクセスできるように設計されています。このデータは、YouTube Studio の [レポート] メニューからアクセスできる手動でもダウンロード可能です。
注: レポートには同様のデータが含まれていますが、この API ではクリエイター ツールとは異なる一連のレポートにアクセスできます。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 を使用するアプリケーションでは、常に以下のことを行う必要があります。
-
レポートのヘッダー行で、レポートの列の順序を指定できます。たとえば、閲覧数がレポートの説明で最初に表示される指標であるとは限りません。代わりに、レポートのヘッダー行を使用して、そのデータを含む列を特定します。
-
同じレポートが繰り返し処理されないように、ダウンロードしたレポートを記録しておきましょう。次のリストでは、そのためのいくつかの方法を提案しています。
-
reports.listメソッドを呼び出すときは、createdAfter パラメータを使用して、特定の日付以降に作成されたレポートのみを取得します。（初めてレポートを取得する場合はcreatedAfterパラメータを省略します）。レポートを取得して正常に処理するたびに、そのレポートの最新が作成された日時に対応するタイムスタンプを保存します。次に、
reports.listメソッドの後続の呼び出しごとにcreatedAfterパラメータ値を更新して、API を呼び出すたびに、バックフィル データを含む新しいレポートなど、新しいレポートのみを取得するようにします。安全策として、レポートを取得する前に、レポートの ID がデータベースに登録されていないことも確認してください。
-
ダウンロードして処理した各レポートの ID を保存します。また、各レポートが生成された日時や、レポートの
startTimeやendTimeなどの追加情報を保存することもできます。これらの情報を組み合わせて、レポートに含まれるデータの期間を識別できます。YouTube アナリティクスのデータを一括取得するレポートでは、各レポートには 24 時間分のデータが含まれるため、各ジョブに多数のレポートが含まれる可能性が高くなります。システム管理ジョブの場合は、処理期間が長くなると報告されるレポートが少なくなります。レポート ID を使用して、ダウンロードとインポートの必要があるレポートを特定します。ただし、2 つの新しいレポートで
startTimeプロパティ値とendTimeプロパティ値が同じである場合は、新しいcreateTime値を持つレポートのみをインポートします。
-
レポートの特性
API レポートは、バージョン管理された .csv（カンマ区切り値）ファイルで、次の特性を持ちます。
-
各レポートには、レポート開始日の午前 0 時からレポート終了日の午後 11 時 59 分までの固有の期間のデータが含まれます。
-
レポートデータが並べ替えられていません。