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 上的相關內容。內容擁有者可以在 YouTube Analytics API 中使用這個範圍來管理 YouTube 數據分析的群組和群組項目。

報表擷取

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 個播放清單。

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

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

方法 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 刪除群組。

群組項目

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

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

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