Reports: Query

重要事項：這個方法的 API 要求現在需要存取 https://www.googleapis.com/auth/youtube.readonly 範圍。

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

  • 指標是使用者活動的個別測量結果，例如影片觀看次數或評分 (喜歡和不喜歡)。
  • 維度是常見的資料匯總條件，例如使用者活動發生的日期或使用者所在的國家/地區。在報表中，每一列的資料都有不重複的維度值組合。
  • 「篩選器」是指定所要擷取資料的維度值。 例如擷取特定國家/地區、特定影片或一組影片的資料。

注意：只有已加入 YouTube 合作夥伴計畫的 YouTube 內容合作夥伴才能查看內容擁有者報表。

常見用途

要求

HTTP 要求

GET https://youtubeanalytics.googleapis.com/v2/reports

所有 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 數據分析群組和群組項目。

參數

下表列出 API 要求擷取查詢報表的必要及選用的查詢參數。表格中列出的標準查詢參數是選用項目，許多 Google API 都支援這些參數。

參數
必要參數
endDate string
YouTube Analytics 資料的擷取結束日期。值的格式必須為 YYYY-MM-DD。

API 回應包含截至查詢時最後一天的資料，查詢中的所有指標皆可使用。舉例來說，如果要求指定結束日期為 2017 年 7 月 5 日，且所有要求指標的值都只提供到 2017 年 7 月 3 日為止，該日期就是回應中涵蓋資料的最後一天。(即使已要求的部分指標資料可於 2017 年 7 月 4 日顯示，也是如此)。
注意：在第 1 版 API 中，這個參數的名稱為 end-date。
ids string
指明你要擷取「YouTube Analytics」資料的 YouTube 頻道或內容擁有者。

  • 如要請求 YouTube 頻道的資料，請將 ids 參數值設為 channel==MINE 或 channel==CHANNEL_ID，其中 CHANNEL_ID 會識別目前已驗證使用者的 YouTube 頻道。
  • 如果想請求 YouTube 內容擁有者的資料，請將 ids 參數值設為 contentOwner==OWNER_NAME，其中 OWNER_NAME 是使用者的 content owner ID。

metrics string
以逗號分隔的 YouTube Analytics 指標清單，例如 views 或 likes,dislikes。如要瞭解可擷取的報表以及每份報表提供的指標，請參閱頻道報表或內容擁有者報表的說明文件。(指標文件包含所有指標的定義)。
startDate string
YouTube Analytics 資料的擷取開始日期。值的格式必須為 YYYY-MM-DD。
注意：在第 1 版 API 中，這個參數的名稱為 start-date。
選用參數
currency string
API 會使用下列貨幣指定下列預估收益指標：estimatedRevenue、estimatedAdRevenue、estimatedRedPartnerRevenue、grossRevenue、cpm、playbackBasedCpm。API 針對這些指標傳回的值，都是根據每日變動的匯率計算而得。如果沒有要求這些指標，系統就會忽略參數。

參數值為 ISO 4217 貨幣代碼 (請見下方幣別清單)。如果您指定不支援的貨幣，API 會傳回錯誤。預設值為 USD。
dimensions string
以半形逗號分隔的 YouTube 數據分析維度清單，例如 video 或 ageGroup,gender。如要瞭解可擷取的報表以及這些報表的維度，請參閱頻道報表或內容擁有者報表的說明文件。(維度文件包含所有維度的定義)。
filters string
擷取 YouTube Analytics 資料時應套用的篩選器清單。頻道報表和內容擁有者報表的說明文件指出可用於篩選每份報表的維度，「維度」文件則定義這些維度。

如果廣告請求使用多個篩選器，請用半形分號 (;) 合併這些維度，產生的結果表格就能滿足這兩種篩選器。舉例來說，如果 filters 參數值是 video==dMH0bHeiRNg;country==IT，結果集會限制結果集納入義大利特定影片的資料。

為篩選器指定多個值

這個 API 支援為 video、playlist 和 channel 篩選器指定多個值。方法是指定一份分隔的清單，列出應篩選 API 回應的影片、播放清單或頻道 ID。舉例來說，如果 filters 參數值是 video==pd1FJh59zxQ,Zhawgd0REhA;country==IT，結果集會限制結果集只包含義大利境內特定影片的資料。參數值最多可指定 500 個 ID。

如果要為同一個篩選器指定多個值，也可以在您為要求指定的維度清單中加入該篩選器。即使該篩選器未列為特定報表支援的維度也是如此。如果您在維度清單中加入篩選器，API 也會使用該篩選器值將結果分組。

舉例來說，假設您擷取頻道的流量來源報表，其中根據觀眾收看頻道影片內容的方式，匯總了觀看統計資料。另外，假設您要求的 filters 參數要求指定了 10 部應傳回資料的影片清單。
  • 如果在 dimensions 參數值中加入 video，API 回應就會針對這 10 部影片提供個別的流量來源統計資料。
  • 如果您未在 dimensions 參數值中加入 video，則 API 回應會匯總這 10 部影片的流量來源統計資料。
includeHistoricalChannelData boolean
注意：這項參數僅適用於內容擁有者報表。

指出 API 回應是否應包含頻道連結至內容擁有者之前這段期間的觀看時間和觀看資料。預設的參數值為 false，代表 API 回應僅包含頻道與內容擁有者連結當天的觀看時間和觀看資料。

另外提醒你，不同的頻道可能會在不同的日期連結至內容擁有者。如果 API 要求正在擷取多個管道的資料，而參數值為 false，則 API 回應會包含以每個管道的連結日期為依據的資料。如果參數值為 true，則 API 回應會包含 API 要求中指定日期的資料。
注意：在第 1 版 API 中，這個參數的名稱為 include-historical-channel-data。
maxResults integer
要納入回應的資料列數量上限。
注意：在第 1 版 API 中，這個參數的名稱為 max-results。
sort string
用以決定 YouTube 數據分析資料排序順序的維度或指標清單 (以半形逗號分隔)。預設是遞增排序。- 前置字串會導致排序順序。
startIndex integer
要擷取的第一個實體的 1 索引。(預設值為 1)。請將這個參數當做分頁機制和 max-results 參數使用。
注意：在第 1 版 API 中，這個參數的名稱為 start-index。
標準參數
access_token 目前使用者的 OAuth 2.0 權杖。
alt 第 2 版的 API 不支援這個參數，但僅支援 JSON 回應。API 回應的資料格式。
  • 有效的值：json、csv
  • 預設值為 json。
callback 回呼函式。
  • 負責處理回應的 JavaScript 回呼函式名稱。
  • 用於 JavaScript JSON-P 要求。
prettyPrint

傳回包含縮排和分行符號的回應。

  • 如果為 true，則以使用者可理解的格式傳回回應。
  • 預設值為 true。
  • 當這個值為 false 時，可以降低迴應酬載大小，在某些環境中提升效能。
quotaUser 此參數在現已淘汰的 API 第 1 版支援。第 2 版 API 不支援這個參數。
userIp 此參數在現已淘汰的 API 第 1 版支援。第 2 版 API 不支援這個參數。

要求主體

呼叫此方法時，不要傳送要求主體。

回應

如同 alt 參數定義所述，API 可以傳回 JSON 或 CSV 格式的回應。每種類型的回應主體相關資訊如下：

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
屬性
kind string
這個值會指定 API 回應中包含的資料類型。對於 query 方法，kind 屬性值為 youtubeAnalytics#resultTable。不過，如果 API 新增支援其他方法，這些方法的 API 回應可能會引入其他 kind 屬性值。
columnHeaders[] list
這個值可指定 rows 欄位中傳回的資料相關資訊。columnHeaders 清單中的每個項目都識別 rows 值傳回的欄位，其中包含以半形逗號分隔的資料清單。

columnHeaders 清單的開頭為 API 要求中指定的維度，後面接著 API 要求中指定的指標。維度和指標的順序與 API 要求中的順序相符。

舉例來說，如果 API 要求包含 dimensions=ageGroup,gender&metrics=viewerPercentage 參數，API 回應就會按照以下順序傳回資料欄：ageGroup、gender、viewerPercentage。
columnHeaders[].name string
維度或指標的名稱。
columnHeaders[].columnType string
資料欄的類型 (DIMENSION 或 METRIC)。
columnHeaders[].dataType string
資料欄中的資料類型 (STRING、INTEGER、FLOAT 等)。
rows[] list
這份清單包含結果資料表的所有資料列。清單中的每個項目都是陣列，其中包含對應單一資料列的資料 (以半形逗號分隔)。以半形逗號分隔的資料欄位順序，會與「columnHeaders」欄位中列出的資料欄順序相符。

如果指定的查詢沒有可用資料，回應中會省略 rows 元素。

採用「day」維度的查詢回應不會包含最近日期的資料列。

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

範例

注意：下列程式碼範例可能不是所有支援的程式設計語言。如需支援的語言清單，請參閱用戶端程式庫說明文件。

JavaScript

這個範例呼叫 YouTube Analytics API 以擷取 2017 年授權使用者頻道的每日觀看次數和其他指標。這個範例使用 Google API JavaScript 用戶端程式庫。

首次在本機執行這個範例之前，您必須先為專案設定授權憑證：
  1. 在 Google API 控制台中建立或選取專案。
  2. 為專案啟用 YouTube Analytics API。
  3. 選取「憑證」頁面頂端的「OAuth 同意畫面」分頁標籤。選取電子郵件地址，輸入產品名稱 (如果尚未設定)，然後按一下「儲存」按鈕。
  4. 在「憑證」頁面上，按一下「建立憑證」按鈕，然後選取「Oauth 用戶端 ID」。
  5. 選取「網頁應用程式」應用程式類型。
  6. 在「已授權的 JavaScript 來源」欄位中，輸入要提供程式碼範例的來源網址。例如，您可以使用 http://localhost:8000 或 http://yourserver.example.com 等名稱。您可以將「Authorized 重新導向 URIs」欄位留空。
  7. 按一下「建立」按鈕完成憑證建立程序。
  8. 關閉對話方塊前，請複製用戶端 ID，您需要在程式碼範例中填入此 ID。

然後將範例儲存至本機檔案。請在範例中找出以下這行程式碼，並將 YOUR_CLIENT_ID 換成您在設定授權憑證時取得的用戶端 ID。

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

現在，您可以開始實際測試範例：

  1. 透過網路瀏覽器開啟本機檔案，然後在瀏覽器中開啟偵錯控制台。您應該會看到顯示兩個按鈕的頁面。
  2. 按一下「授權並載入」按鈕，啟動使用者授權流程。如果您授權應用程式擷取頻道資料，瀏覽器控制台中應會顯示下列幾行文字： 
    Sign-in successful
GAPI client loaded for API
  3. 如果您看到錯誤訊息，而非上述幾行程式碼，請確認您是從為專案設定的已授權重新導向 URI 載入指令碼，且已將用戶端 ID 加入上述程式碼中。
  4. 按一下「execute」execute按鈕呼叫 API。您應該會在瀏覽器中看到 response 物件列印到控制台。在該物件中，result 屬性會對應至包含 API 資料的物件。
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

這個範例呼叫 YouTube Analytics API 以擷取 2017 年授權使用者頻道的每日觀看次數和其他指標。這個範例使用 Google API Python 用戶端程式庫。

首次在本機執行這個範例之前，您必須先為專案設定授權憑證：
  1. 在 Google API 控制台中建立或選取專案。
  2. 為專案啟用 YouTube Analytics API。
  3. 選取「憑證」頁面頂端的「OAuth 同意畫面」分頁標籤。選取電子郵件地址，輸入產品名稱 (如果尚未設定)，然後按一下「儲存」按鈕。
  4. 在「憑證」頁面上，按一下「建立憑證」按鈕，然後選取「Oauth 用戶端 ID」。
  5. 選擇「其他」應用程式類型，輸入「YouTube Analytics API 快速入門導覽課程」，再按一下「建立」按鈕。
  6. 按一下「OK」關閉產生的對話方塊。
  7. 按一下用戶端 ID 右側的 (下載 JSON) 按鈕。
  8. 將下載的檔案移至工作目錄。

此外，您還需要安裝 Google API Python 專用用戶端程式庫和其他一些程式庫：

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

現在，您可以開始實際測試範例：

  1. 請將下方的程式碼範例複製到您的工作目錄。
  2. 在範例中，將 CLIENT_SECRETS_FILE 變數的值更新為您在設定授權憑證後下載的檔案位置。
  3. 在終端機視窗中執行程式碼範例： 
    python yt_analytics_v2.py
  4. 完成授權流程。瀏覽器可能會自動載入驗證流程，或者您可能需要將驗證網址複製到瀏覽器視窗中。在授權流程的結尾，視需要將瀏覽器中顯示的授權碼貼到終端機視窗中，然後按一下 [Return]。
  5. 系統會執行 API 查詢，並將 JSON 回應輸出至終端機視窗。
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

試試看！

使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。