YouTube Analytics API - Data Model

YouTube Analytics API 可讓您產生含有 YouTube 數據分析資料的自訂報表。這個 API 支援頻道和內容擁有者的報表。報表欄位的特徵是維度或指標：

• 維度是指用來匯總資料的常見條件，例如操作發生的日期或使用者所在的國家/地區。

  在報表中，每一列都有不重複的維度值組合。因此，您選擇的報表維度將決定 YouTube 計算報表中指標值的方式。

• 指標是指與使用者活動、廣告成效或預估收益相關的個別評估項目。使用者活動指標包括影片觀看次數和評分 (喜歡與不喜歡的人數) 等。

Analytics API 提供篩選和排序參數，因此呼叫應用程式不需要原生支援這些函式。另外，這個 API 也能擷取 YouTube 數據分析群組的資料。自訂群組最多可包含 500 部影片、播放清單、頻道或資產。

選擇報表參數

使用報表的 reports.query 方法提出報表要求時，API 請求包含五個參數，用來決定報表值的計算方式：

• startDate 和 endDate 參數會指定報表包含資料的時間範圍。實際上，API 回應包含的資料，直到查詢的最後一天為止，才有查詢中所有的指標。

• metrics 參數會指定要納入報表的指標。在頻道報表中，指標會評估使用者活動，並納入觀看次數和喜歡次數等值。部分指標也會評估廣告成效或預估收益。

• dimensions 參數會說明這些指標的分組方式。

• filters 參數會說明篩選報表資料的方式。因此，相較於只傳回特定頻道的所有資料，報表可能會經過篩選，只納入特定國家/地區、影片或影片群組的指標。

  注意事項：這個 API 可讓您為影片、播放清單和頻道篩選器指定多個值。這樣，您也可以在篩選器清單中加入這個篩選器，以便按照影片、播放清單或頻道來將傳回的指標分組。

報表選項選項

舉例來說，假設某個頻道擁有者想擷取一個影片裝置類型報表，以判斷該頻道的影片在行動裝置、遊戲主機、電視等裝置上的觀看次數。

• 頻道擁有者會將 startDate 參數設為 2015-06-01，並將 endDate 參數設為 2015-07-31。根據這些值，報表會包含兩個月的資料。

• 裝置類型報表支援 views 和 estimatedMinutesWatched 指標，因此頻道擁有者會將 metrics 參數設為 views,estimatedMinutesWatched。

• 對於 dimensions 參數，頻道擁有者有多種選擇。其中兩個類別列於下方清單，第三部分將於 filters 參數值的解說中討論。

  • 如果將參數值設為 deviceType，表示報表涵蓋整個期間的收視次數和觀看時間都會依裝置類型分組。因此，報表資料會顯示以下問題：

    • 在 2015 年 6 月 1 日至 2015 年 7 月 31 日期間，這個頻道的影片在行動裝置上有多少次觀看？
    • 2015 年 6 月 1 日至 2015 年 7 月 31 日期間，這個頻道在遊戲主機上的影片觀看次數達到多少次？

    報表實際上會列出每種裝置類型的總觀看次數和觀看時間。

  • 如果將參數值設為 day,deviceType，表示在報表統計期間內每天的裝置類型與觀看時間會由系統計算。因此，報表資料會顯示以下問題：

    • 2015 年 6 月 1 日，這個頻道的影片在行動裝置上有多少次觀看？
    • 頻道的影片在 2015 年 7 月 14 日是在電視上觀看過幾次？

• 最後，filters 參數可讓頻道擁有者限制報表只納入符合特定篩選器值的資料。報表使用過多篩選選項來解讀所有選項，因此這些範例僅代表系統產生的報表的一部分。

  • 頻道擁有者可以篩選要求，只傳回 Android 作業系統的值。(報表統計期內 Android 行動裝置獲得多少次觀看？)

  • 頻道擁有者可以篩選要求，只傳回特定國家/地區的值。(報表統計期內，在加拿大每天觀看過幾次影片？)

  • 頻道擁有者可以篩選要求，只傳回特定影片的值。不過，「影片」篩選器支援以逗號分隔的清單值，因此報表可以含有許多影片的資料。

    此外，如果影片篩選器指定多個值，則可將影片指定為維度。這表示 dimensions 參數也支援 deviceType,video 和 day,deviceType,video 值。

    • 如果頻道擁有者在維度清單中包含「影片」，則指標會為每個影片指定個別的值。(2015 年 6 月 1 日，XYZ 影片在遊戲主機上的觀看次數為何？)
    • 如果頻道擁有者在維度清單中沒有包含「影片」，則指標會指定所有指定影片的總計值。(2015 年 6 月 1 日，遊戲主機上的 ABC、DEF 與 XYZ 影片有多少次？)

擷取報表

如要擷取報表，請將已取得的 GET 要求傳送至 API 的 reports.query 方法，並指定您要擷取報表的參數。

如需 API 支援的報表清單，請參閱頻道報表和內容擁有者報表說明文件。每個報表定義都能識別報表允許 metrics、dimensions 和 filters 參數使用的值。

最佳做法

使用 YouTube Analytics API 的應用程式必須遵循下列做法：

• 使用回應的標題列來判斷報表欄的順序。舉例來說，不要假設 view 是回應中傳回的第一個指標，因為它是報表說明中列出的第一個指標。請改用回應的標題列來判斷該包含哪些資料欄的資料。
• 使用 YouTube Data API 擷取 YouTube Analytics API 回應中所識別資源的其他中繼資料。如 YouTube API 服務開發人員政策 (II.E.4.b 至 III.E.4.d 節) 所述，API 用戶端必須在 30 天後刪除或重新整理該 API 中儲存的資源中繼資料。

匯總指標和已刪除的項目

YouTube Analytics API 回應中不含已刪除項目的指標明細。例如，如果頻道擁有者刪除影片，那麼對於個別影片所回傳指標的 API 回應，影片將不再列在清單中。不過，匯總一組資源指標的報表仍會納入與已刪除項目相關的指標。

舉例來說，假設頻道擁有者擷取了兩份報表。第一份報表會列出頻道在特定時間範圍內的所有影片總觀看次數。第二份報表則列出同一影片在不同時間範圍內的每日總觀看次數，

在這種情況下，第一份報表中的數字將包含因為第一份報表含有每日匯總資料而遭刪除的影片觀看次數。不過，第二份報表不會包含已刪除項目的相關觀看次數，因為第二份報表會依影片列出觀看次數。因此，如果頻道在報表統計期內刪除了影片，第一份報表中顯示的每日觀看次數總計可能會高於第二份報表中每日特定影片的觀看次數總和。

資料去識別化

當部分指標未達特定門檻時，系統會限制部分 YouTube 數據分析資料。這類報表可能出現在各種報表中。在實務上，這指的是，在下列情況下，報表可能不會包含全部或全部的資料。

1. 影片或頻道在指定時間範圍內的流量有限

   或

2. 您選用的篩選器或維度 (例如流量來源或國家/地區) 值未達到特定門檻。

如果資料有限，不同報表中的報表總數可能會有所差異，取決於報表匯總資料的方式。

舉例來說，假設頻道擁有者擷取了兩份報表。第一份報表可列出特定影片的總觀看次數，第二份報表則是依國家/地區顯示影片的總觀看次數。在指定時間範圍內，假設影片觀看次數為 1000 次，美國發生 500 次觀看次數，加拿大發生 590 次觀看次數，加拿大發生 498 次觀看次數。

在這個例子中，第一份報表指出這部影片的觀看次數為 1000 次，第二份報表只會指出該影片在美國獲得了 500 次觀看，在加拿大則佔了 498 次。因此兩份報表中的總觀看次數會有所差異。請注意，第二份報表不會納入其他發生的兩筆收視 (或法國發生的任何收視)。

限制資料的真實門檻，不會發布，且 YouTube 有權隨時變更。

限制資料類型

YouTube 數據分析報表可能提供下列資料：

• 客層資料，例如年齡和性別。
• 地理位置資料，包括與觀眾所在國家/地區相關的指標或維度，例如國家/地區。不過請注意，報表並不會將收益門檻套用至收益指標。
• 特定流量來源的相關指標，例如將使用者導向影片的觀看次數或外部網址。舉例來說，如果搜尋字詞和網址帶來的觀看次數過少，報表就不會顯示該內容，但您還是會看到能為觀眾帶來大量內容的詞彙和網址。

如要進一步瞭解 YouTube 數據分析報表的資料有限，請參閱 YouTube 說明中心。

配額使用量

您發出的所有 API 要求都會計為 API 用量配額的一個單位。您可以到 Google API 控制台的配額面板查看配額限制。