YouTube Reporting API - System-Managed Reports

YouTube 會針對可存取創作者工作室對應報表的內容擁有者,自動產生一組系統管理的廣告收益報表。這類報表旨在透過程式輔助方式存取資料,您也可以在 YouTube 創作者工作室的報表選單中,透過手動下載的報表查看這些資料。

注意: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:擷取報表的下載網址

呼叫 jobs.reports.list 方法即可擷取為工作建立的報表清單。在要求中,將 jobId 參數設為您要擷取的報表工作 ID。

您可以使用下列任一或所有參數篩選報表清單:

  • 使用 createdAfter 參數,表示 API 應只傳回指定時間之後建立的報表。此參數可用來確保 API 只會傳回尚未處理的報表。

  • 使用 startTimeBefore 參數,表示當報表最早的資料早於指定日期時,API 回應只能包含報表。createdAfter 參數則與報表建立的時間有關,報表中的資料則與該日期相關。

  • 使用 startTimeAtOrAfter 參數,表示當報表最早資料位於指定日期或晚於指定日期時,API 回應應僅包含報表。如同 startTimeBefore 參數,這個參數值會對應報表中的資料,而不是報表建立時間。

API 回應會包含該工作的 Report 資源清單。每項資源都是指包含不同時間範圍資料的報表。

  • 資源的 startTimeendTime 屬性可指出報表資料涵蓋的時間範圍。
  • 資源的 downloadUrl 屬性會指出可擷取報表的網址。

  • 資源的 createTime 屬性會指定產生報表的日期和時間。您的應用程式應儲存這個值,並使用其判斷先前下載的報表是否已變更。

步驟 4:下載報表

將 HTTP GET 要求傳送至步驟 4 中取得的 downloadUrl,即可擷取報表。

處理報表

最佳做法

使用 YouTube Reporting API 的應用程式「一律」應遵循下列做法:

  • 使用報表的標題列決定報表欄的順序。舉例來說,請勿假設「觀看次數」就會是報表傳回的第一個指標,因為它是報表說明中列出的第一個指標。請改用報表的標題列來決定包含該資料的資料欄。

  • 保留已下載的報表記錄,避免重複處理相同的報表。下列清單提供幾種方法建議。

    • 呼叫 reports.list 方法時,使用 createdAfter 參數只會擷取在特定日期之後建立的報表。(首次擷取報表時省略 createdAfter 參數)。

      每次擷取並成功處理報表時,請儲存最新報表的建立時間所在日期和時間。接著,在每次呼叫 reports.list 方法時更新 createdAfter 參數值,確保每次呼叫 API 時只會擷取新報表,包括含有補充資料的新報表。

      為了安全起見,也請在擷取報表前,確認報表的ID 未列出資料庫。

    • 儲存您下載並處理過的每份報表的 ID。您也可以儲存其他資訊,例如每份報表產生的日期和時間,或是報表的 startTimeendTime,藉此識別報表包含資料的時間範圍。如果報表會擷取 YouTube 數據分析的大量資料,由於每份報表都包含 24 小時內的資料,因此每項工作都可能有許多報表。如果系統管理的工作涵蓋較長時間範圍,所回報的報表會較少。

      使用報表 ID 找出仍須下載及匯入的報表。不過,如果有兩份新報表的 startTimeendTime 屬性值相同,請只匯入含有新版 createTime 值的報表。

報表特性

API 報表是 .csv (逗號分隔值) 版本檔案,具有以下特性:

  • 每份報表包含特定期間的資料,其時間範圍為報表結束日期的太平洋時間凌晨 12:00 到報表結束日期的太平洋時間晚上 11:59。

  • 報表資料未排序。