YouTube Analytics API - Data Model

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

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

    在報表中，每列資料都有不重複的維度值組合。因此，您為報表選擇的維度會決定 YouTube 如何計算該報表中的指標值。

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

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

選擇報表參數

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

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

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

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

  • filters 參數說明如何篩選報表資料。舉例來說，報表可以經過篩選，只包含特定國家/地區、影片或影片群組的指標，而不是傳回頻道的所有資料。

    注意：API 允許您為影片、播放清單和頻道篩選器指定多個值。如果這麼做，您也可以在維度清單中加入該篩選器，這樣傳回的指標也會依影片、播放清單或頻道分組。

檢舉選項範例

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

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

  • 裝置類型報表支援「觀看次數」和「預估觀看時間 (分鐘)」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 的應用程式「一律」應遵循下列做法：

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

匯總指標和已刪除的項目

YouTube 數據分析 API 回應不會提供已刪除項目的指標細目。舉例來說，如果頻道擁有者刪除影片，API 回應就不會再列出該影片 (API 會逐一傳回影片的指標)。不過，如果報表匯總一組資源的指標，仍會納入與已刪除項目相關聯的指標。

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

在這種情況下，第一份報表會包含後來刪除的影片觀看次數，因為第一份報表包含每日匯總資料。不過，第二份報表不會列出與已刪除項目相關的觀看次數，因為第二份報表會列出各影片的觀看次數。因此，如果頻道在報表涵蓋的時間範圍內刪除影片，第一份報表中的每日總觀看次數，可能會高於第二份報表中的每日影片觀看次數總和。

資料去識別化

如果指標未達特定門檻，部分 YouTube 數據分析資料可能會受到限制，這類情況可能會發生在各種報表中。實務上，這表示如果發生下列情況，報表可能不會包含所有 (或任何) 資料：

  1. 影片或頻道在特定時間範圍內的流量不足。

    或

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

此時，不同報表可能會出現不同的總計資訊，實際差異取決於報表匯總資料的方式。

舉例來說，假設頻道擁有者擷取了兩份報表。第一份報表列出特定影片的總觀看次數，第二份報表則列出該影片在各國家/地區的總觀看次數。該報表顯示在指定時間範圍內，影片獲得 1,000 次觀看，其中 500 次來自美國、498 次來自加拿大，2 次來自法國。

在本例中，第一份報表會顯示影片有 1, 000 次觀看，第二份報表則只會顯示影片在美國和加拿大分別獲得 500 次和 498 次觀看。因此，這兩份報表的總觀看次數會有所不同。請注意，第二份報表不會顯示來自法國的 2 次觀看。

YouTube 不會公布實際的資料限制門檻，且會視情況調整。

資料類型有限

YouTube 數據分析報表可能只會顯示部分資料：

  • 受眾特徵資料，例如年齡和性別。
  • 地理資料，包括與觀眾所在國家/地區相關的指標或維度，例如觀眾的國家/地區。但請注意，報表不會對收益指標套用地理位置門檻。
  • 與特定流量來源相關的指標，例如搜尋字詞或外部網址，這些來源會為你的影片帶來觀看次數。舉例來說，如果搜尋字詞和網址帶來的觀看次數極少，就不會顯示在報表中，但如果搜尋字詞和網址能吸引大量觀眾觀看你的內容，就會顯示在報表中。

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

配額使用量

您發出的每項 API 要求都會計為一個 API 用量配額單位。配額限制會顯示在 Google API 控制台的「配額」面板中。