API Reference

有了 YouTube Analytics API，你就能擷取 YouTube 頻道或內容擁有者的 YouTube 數據分析資料。這個 API 支援即時查詢，並根據 API 要求參數產生報表。

此 API 支援兩種函式：

  • 擷取報表：API 的 reports.query 方法可擷取 YouTube 數據分析報表。

  • YouTube 數據分析群組管理：YouTube 數據分析群組是最多可加入 500 個頻道、影片、播放清單或資產的自訂集合。這個 API 支援多種方法，可用來建立、擷取及更新 YouTube 數據分析群組。頻道和內容擁有者可以使用 reports.query 方法，擷取群組中所有項目的匯總資料，以利進行成效分析。

本頁面簡要說明可啟用這些函式的 API 資源和方法。

授權

所有 YouTube Analytics API 要求皆須獲得授權。授權指南說明如何使用 OAuth 2.0 通訊協定擷取授權權杖。

YouTube Analytics API 要求會使用下列授權範圍：

範圍
https://www.googleapis.com/auth/yt-analytics.readonly 查看 YouTube 內容的 YouTube 數據分析報表。這個範圍可存取使用者活動指標，例如觀看次數和評分次數。
https://www.googleapis.com/auth/yt-analytics-monetary.readonly 查看 YouTube 內容的 YouTube 數據分析營利報表。這個範圍可存取使用者活動指標，以及預估收益和廣告成效指標。
https://www.googleapis.com/auth/youtube 管理 YouTube 帳戶。在 YouTube Analytics API 中，頻道擁有者可使用這個範圍管理 YouTube 數據分析群組和群組項目。
https://www.googleapis.com/auth/youtubepartner 查看及管理 YouTube 素材資源和相關內容。在 YouTube Analytics API 中，內容擁有者可使用這個範圍管理 YouTube Analytics 群組和群組項目。

檢索報表

您可以使用 API 的 reports.query 方法擷取多種不同的 YouTube 數據分析報表。每個要求都會使用查詢參數指定管道 ID 或內容擁有者、開始日期、結束日期，以及至少一項指標。您也可以提供其他查詢參數，例如維度、篩選器和排序指示。

方法 HTTP 要求 說明
相對於 https://youtubeanalytics.googleapis.com/v2 的 URI
query GET /reports 擷取 YouTube 數據分析報表。每個 API 要求都會使用查詢參數指定頻道 ID 或內容擁有者、開始日期、結束日期，以及至少一個指標。您也可以提供其他查詢參數，例如維度、篩選器或排序指示。
  • 指標是指使用者活動的個別評估，例如影片觀看次數或評分 (喜歡和不喜歡)。
  • 維度是用來匯總資料的常見條件，例如使用者活動發生的日期或使用者所在國家/地區。在報表中，每列資料都包含不重複的維度值組合。
  • 篩選器是指定要擷取的資料的維度值。舉例來說，您可以擷取特定國家/地區、特定影片或一組影片的資料。
支援的頻道報表和內容擁有者報表清單會定義指標、維度和篩選器的有效組合。

群組管理

這個 API 提供兩種資源，可用來建立及管理 YouTube 數據分析群組：

群組

group 資源代表 YouTube 數據分析群組，這是最多可加入 500 個頻道、影片、播放清單或資產的自訂集合。

群組中的所有項目都必須代表相同類型的資源。舉例來說，你無法建立包含 100 部影片和 100 個播放清單的群組。

數據分析群組只能包含您上傳或聲明擁有權的資源，或是已連結至您管理的頻道。因此，頻道擁有者可以建立影片和播放清單群組。內容擁有者可以建立影片、播放清單、頻道或資產群組。

如要進一步瞭解這項資源，請參閱其資源表示法和屬性清單。

方法 HTTP 要求 說明
相對於 https://youtubeanalytics.googleapis.com/v2 的 URI
list GET /groups 傳回符合 API 要求參數的群組清單。舉例來說，您可以擷取已驗證使用者擁有的所有群組，也可以根據群組的專屬 ID 擷取一或多個群組。
insert POST /groups 建立 YouTube 數據分析群組。建立群組後，請使用 groupItems.insert 方法將項目新增至群組。
update PUT /groups 修改群組的中繼資料。目前，您只能更新群組的名稱。(使用 groupItems.insert 和 groupItems.delete 新增及移除群組項目)。
delete DELETE /groups 刪除群組。

GroupItems

groupItem 資源代表 YouTube 數據分析群組中的項目。

如要進一步瞭解這項資源，請參閱其資源表示法和屬性清單。

方法 HTTP 要求 說明
相對於 https://youtubeanalytics.googleapis.com/v2 的 URI
list GET /groupItems 傳回符合 API 要求參數的群組項目集合。
insert POST /groupItems 建立群組項目。
delete DELETE /groupItems 從群組中移除項目。