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

參數

下表列出 API 要求擷取查詢報表的必要和選用查詢參數。表格中列出的標準查詢參數也是選用項目,受到許多 Google API 支援。

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

API 回應包含截至查詢日為止,所有查詢中所有指標可用為止的資料。舉例來說,如果請求指定結束日期是 2017 年 7 月 5 日,而所有要求指標的值都是到 2017 年 7 月 3 日為止,那麼這將會是資料中回應所包含的最後一天。(即使有 2017 年 7 月 4 日,部分要求的指標資料也是如此)。
注意:在 API 版本 1 中,此參數的名稱為 end-date
ids string
指出您要擷取 YouTube Analytics 資料的 YouTube 頻道或內容擁有者。

  • 如要要求 YouTube 頻道的資料,請將 ids 參數值設為 channel==MINEchannel==CHANNEL_ID,其中 CHANNEL_ID 代表目前已驗證使用者的 YouTube 頻道。
  • 如要要求 YouTube 內容擁有者的資料,請將 ids 參數值設為 contentOwner==OWNER_NAME,其中 OWNER_NAME 是使用者的 content owner ID

metrics string
以逗號分隔的 YouTube Analytics 指標清單,例如 viewslikes,dislikes。請參閱頻道報表內容擁有者報表的說明文件,瞭解您可以擷取的報表以及每份報表中的指標。(指標文件包含所有指標的定義)。
startDate string
擷取 YouTube Analytics 資料的開始日期。這個值必須採用 YYYY-MM-DD 格式。
注意:在 API 第 1 版中,這個參數的名稱為 start-date
選用參數
currency string
API 用來指定以下預估收益指標的貨幣:estimatedRevenueestimatedAdRevenueestimatedRedPartnerRevenuetotalRevenuecpmplaybackBasedCpm。API 為這些指標傳回的值,是根據每日變更的匯率計算得出。如未要求這些指標,系統會忽略這個參數。

參數值是採下列三個字母的 ISO 4217 貨幣代碼,貨幣清單如下。如果您指定不支援的貨幣,API 會傳回錯誤。預設值為 USD

dimensions string
YouTube 數據分析維度的逗號分隔清單,例如 videoageGroup,gender。如需可擷取的報表以及這些報表所使用的維度清單,請參閱頻道報表內容擁有者報表的說明文件。(維度文件包含所有維度的定義)。
filters string
擷取 YouTube Analytics 資料時應套用的篩選器清單。頻道報表內容擁有者報表的說明文件可用來找出可用於篩選每份報表的維度,維度文件則會定義這些維度。

如果要求使用多個篩選器,請結合半形分號 (;),而傳回的結果表將符合這兩個篩選器。例如,video==dMH0bHeiRNg;country==ITfilters 參數值會限制結果集,以納入義大利影片的資料。

為篩選器指定多個值

這個 API 支援為 videoplaylistchannel 篩選器指定多個值。做法是指定影片、播放清單或頻道 ID 的逗號分隔清單,以便篩選 API 回應。例如,video==pd1FJh59zxQ,Zhawgd0REhA;country==ITfilters 參數值會限制結果集,以納入義大利影片的資料。參數值最多可指定 500 個 ID。

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

舉例來說,假設您擷取了頻道的流量來源報表,其中會根據觀眾收看頻道影片內容的方式彙整觀看次數統計資料。此外,假設您的 filters 參數要求也指出了 10 部需要傳回資料的影片,
  • 如果將 video 參數加入 dimensions 參數的值,API 回應將針對這 10 部影片分別提供流量來源。
  • 如果您沒有在 dimensions 參數的值中加入 video,API 回應就會匯總這 10 部影片的流量來源統計資料。
includeHistoricalChannelData boolean
注意:這個參數僅適用於內容擁有者報表

指出 API 回應是否包含頻道的觀看時間,以及將頻道連結至內容擁有者之前的收視資料。預設值為 false,表示 API 回應只包含觀看時間,以及頻道與內容擁有者相連結日期的相關資料。

提醒你,如果你的頻道在不同日期連結至不同的內容擁有者,如果 API 要求擷取多個管道的資料,且參數值為 false,則 API 回應包含根據每個管道的連結日期提供的資料。如果參數值為 true,API 回應就會包含與 API 要求中指定的日期相符的資料。
注意:在 API 版本 1 中,此參數的名稱為 include-historical-channel-data
maxResults integer
要包含在回應中的列數上限。
注意:在 API 版本 1 中,此參數的名稱為 max-results
sort string
以逗號分隔的維度或指標清單,用來決定 YouTube 數據分析資料的排序順序。根據預設,排序順序會遞增。- 前置字元會導致遞減排序。
startIndex integer
第一個要擷取的實體索引。(預設值為 1。使用這個參數做為 max-results 參數的分頁機制。
注意:在 API 版本 1 中,此參數的名稱為 start-index
標準參數
access_token 目前使用者的 OAuth 2.0 憑證。
alt API 版本 2 不支援這個參數,而此 API 僅支援 JSON 回應。API 回應的資料格式。
  • 有效的值:jsoncsv
  • 預設值:json
callback 回呼函式。
  • 負責處理回應的 JavaScript 回呼函式名稱。
  • 用於 JavaScript JSON-P 要求。
prettyPrint

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

  • 如果 true,則以使用者可理解的格式傳回回應。
  • 預設值:true
  • 設定為 false 可以縮減回應酬載大小,進而改善在某些環境中的效能。
quotaUser API 第 1 版已支援這個參數,這個 API 現已淘汰。API 版本 2 不支援這個參數。
userIp API 第 1 版已支援這個參數,這個 API 現已淘汰。API 版本 2 不支援這個參數。

要求主體

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

回應

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 回應會以下列順序傳回資料欄:ageGroupgenderviewerPercentage
columnHeaders[].name string
維度或指標的名稱。
columnHeaders[].columnType string
欄類型 (DIMENSIONMETRIC)。
columnHeaders[].dataType string
資料欄中的資料類型 (STRINGINTEGERFLOAT 等)。
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 數據分析 API,擷取 2017 年度使用者授權頻道的每日觀看次數和其他指標。本範例使用 Google API JavaScript 用戶端程式庫

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

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

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

現在,您可以開始實際測試範例了:

  1. 透過網路瀏覽器開啟本機檔案,然後在瀏覽器中開啟偵錯控制台。您應該會看到一個顯示兩個按鈕的網頁。
  2. 按一下 [Authorize and load] (授權並載入) 按鈕,啟動使用者授權流程。如果您授權應用程式擷取您的頻道資料,系統會在瀏覽器中顯示以下幾行內容:
    Sign-in successful
    GAPI client loaded for API
  3. 如果您看到錯誤訊息 (而不是上述幾行內容),請確認您是透過為專案設定的授權重新導向 URI 載入指令碼,而且已經按照上述說明將用戶端 ID 加到程式碼中。
  4. 按一下「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>

Python

這個範例使用 YouTube 數據分析 API,擷取 2017 年度使用者授權頻道的每日觀看次數和其他指標。本範例使用 Google API Python 用戶端程式庫

首次在本機執行此範例前,請先為您的專案設定授權憑證:
  1. Google API 控制台中建立或選取專案。
  2. 為您的專案啟用 YouTube 數據分析 API
  3. 憑證 頁面頂端,選取 OAuth 同意畫面 標籤。選取電子郵件地址,輸入產品名稱 (如果尚未設定),然後按一下 [儲存] 按鈕。
  4. 在「憑證」頁面上,按一下 [建立憑證] 按鈕,然後選取 [Oauth Client ID]
  5. 選取「Other」(其他) 應用程式,輸入「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'
  )

試試看!

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