針對可存取創作者工作室中相關報表的內容擁有者,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
資源清單。每項資源都指的是一份內含特定期間資料的報表。
- 資源的
startTime
和endTime
屬性可識別報表涵蓋資料的時間範圍。 - 資源的
downloadUrl
屬性可識別報表擷取來源的網址。 - 資源的
createTime
屬性會指定產生報表的日期和時間。應用程式應儲存這個值,並使用這個值判斷先前下載的報表是否有變更。
步驟 4:下載報表
將 HTTP GET 要求傳送至步驟 4 中的 downloadUrl
,以擷取報表。
處理報表
最佳做法
使用 YouTube Reporting API 的應用程式應一律遵循以下做法:
-
使用報表標題列來判斷報表欄的順序。舉例來說,不要假設「資料檢視」會是報表傳回的第一個指標,因為它只是報表說明中列出的第一個指標。請改用報表的標題列,判斷哪些資料欄包含這些資料。
-
請保留已下載的報表,以免重複處理相同的報表。以下建議幾種做法。
-
呼叫
reports.list
方法時,使用 createafter 參數,只擷取在特定日期之後建立的報表。(第一次擷取報表時請省略createdAfter
參數)。每次擷取並成功處理報表時,請儲存與這些報表最近一次建立日期和時間對應的時間戳記。接著,在對
reports.list
方法的每個連續呼叫上更新createdAfter
參數值,以確保每次呼叫 API 時,您只會擷取新的報表,包括含補充資料的新報表。為了保障您的安全,在擷取報表前,請先檢查資料庫中並未列出報表的 ID。
-
針對您下載並處理過的每份報表,儲存 ID。您也可以儲存其他資訊,例如每份報表的產生日期和時間,或報表的
startTime
和endTime
,這些報表會標明報表含有哪一段期間的資料。對於擷取 YouTube 數據分析大量資料的報表,由於每項報表都包含 24 小時內的資料,因此每次工作可能會有許多報表。涵蓋較早時間範圍的系統管理工作,報表數量較少。使用報表 ID 找出您仍然需要下載及匯入的報表。但是,如果兩份新報表具有相同的
startTime
和endTime
屬性值,請只匯入較新的createTime
值的報表。
-
報表特性
API 報表是具有下列特性的 .csv
(版本分隔) 檔案版本:
-
每份報表都包含資料從報表開始日期的凌晨 12 點到太平洋時間晚上 11 點 59 分內的某段時間,以及報表結束日期的太平洋時間。
-
報表資料未經排序。