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 屬性值。

「報表」文件會列出可用的報表、報表類型的編號,以及其中所含的欄位。您也可以使用 reportTypes.list 方法擷取支援的報表類型清單。

步驟 3:擷取報表的下載網址

呼叫 jobs.reports.list 方法,以擷取為工作建立的報表清單。在請求中,將 jobId 參數設為您想擷取的報表工作編號。

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

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

  • 使用 startTimeBefore 參數表示 API 回應只應包含指定日期之前的最早資料。createdAfter 參數與報表建立時間有關,但此日期適用於報表中的資料。

  • 使用 startTimeAtOrAfter 參數表示 API 回應只應包含指定日期當天或之後的報表資料。這個參數值與 startTimeBefore 參數一樣,會對應報表中的資料,而非報表建立時間。

API 回應包含該工作的 Report 資源清單。每項資源都指的是一份內含特定期間資料的報表。

  • 資源的 startTimeendTime 屬性可識別報表涵蓋資料的時間範圍。
  • 資源的 downloadUrl 屬性可識別報表擷取來源的網址。

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

步驟 4:下載報表

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

處理報表

最佳做法

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

  • 使用報表標題列來判斷報表欄的順序。舉例來說,不要假設「資料檢視」會是報表傳回的第一個指標,因為它只是報表說明中列出的第一個指標。請改用報表的標題列,判斷哪些資料欄包含這些資料。

  • 請保留已下載的報表,以免重複處理相同的報表。以下建議幾種做法。

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

      每次擷取並成功處理報表時,請儲存與這些報表最近一次建立日期和時間對應的時間戳記。接著,在對 reports.list 方法的每個連續呼叫上更新 createdAfter 參數值,以確保每次呼叫 API 時,您只會擷取新的報表,包括含補充資料的新報表。

      為了保障您的安全,在擷取報表前,請先檢查資料庫中並未列出報表的 ID

    • 針對您下載並處理過的每份報表,儲存 ID。您也可以儲存其他資訊,例如每份報表的產生日期和時間,或報表的 startTimeendTime,這些報表會標明報表含有哪一段期間的資料。對於擷取 YouTube 數據分析大量資料的報表,由於每項報表都包含 24 小時內的資料,因此每次工作可能會有許多報表。涵蓋較早時間範圍的系統管理工作,報表數量較少。

      使用報表 ID 找出您仍然需要下載及匯入的報表。但是,如果兩份新報表具有相同的 startTimeendTime 屬性值,請只匯入較新的 createTime 值的報表。

報表特性

API 報表是具有下列特性的 .csv (版本分隔) 檔案版本:

  • 每份報表都包含資料從報表開始日期的凌晨 12 點到太平洋時間晚上 11 點 59 分內的某段時間,以及報表結束日期的太平洋時間。

  • 報表資料未經排序。