YouTube Reporting API - Get Bulk Data 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 資源。每個資源都代表一份報表，內含特定時間範圍的資料。

• 資源的 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 分。

• 報表資料未排序。