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