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 月 3 日。(即使系統提供 2017 年 7 月 4 日的部分指標資料,也是如此)。
注意:在 API 第 1 版中,這個參數的名稱為 end-date
ids string
識別要擷取資料的 YouTube 頻道或內容擁有者。 YouTube Analytics

  • 如要要求 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 用來指定下列預估收益指標的幣別:estimatedRevenueestimatedAdRevenueestimatedRedPartnerRevenuegrossRevenuecpmplaybackBasedCpm。API 為這些指標傳回的值是估計值,計算時使用的匯率每天都會變動。如果未要求任何這類指標,系統會忽略該參數。

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

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

如果要求使用多個篩選器,請以半形分號 (;) 將篩選器合併,傳回的結果表格就會同時符合這兩個篩選器。舉例來說,filters 參數值為 video==dMH0bHeiRNg;country==IT 時,結果集只會包含義大利境內指定影片的資料。

為篩選器指定多個值

API 支援為 videoplaylistchannel 篩選器指定多個值。如要這麼做,請指定以分隔符號區隔的影片、播放清單或頻道 ID 清單,藉此篩選 API 回應。舉例來說,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 要求中指定日期相符的資料。
注意:在 API 第 1 版中,這個參數的名稱為 include-historical-channel-data
maxResults integer
要納入回應的資料列數量上限。
注意:在 API 第 1 版中,這個參數的名稱為 max-results
sort string
以半形逗號分隔的維度或指標清單,用於決定 YouTube 數據分析資料的排序順序。預設是遞減排序。- 前置字元會導致遞減排序順序。
startIndex integer
要擷取的第一個實體的索引 (從 1 開始)。(預設值為 1)。請搭配 max-results 參數,將這個參數做為分頁機制。
注意:在 API 第 1 版中,這個參數的名稱為 start-index
標準參數
access_token 目前使用者的 OAuth 2.0 權杖。
alt API 第 2 版不支援這個參數,只支援 JSON 回應。API 回應的資料格式。
  • 有效的值:jsoncsv
  • 預設值為 json
callback 回呼函式。
  • 負責處理回應的 JavaScript 回呼函式名稱。
  • 用於 JavaScript JSON-P 要求。
prettyPrint

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

  • 如果為 true,則以使用者能夠理解的格式傳送回應。
  • 預設值為 true
  • 當這個值是 false 時,可以縮減回應的酬載大小,在某些環境中或許可提升效能。
quotaUser 這個參數在 API 第 1 版中受到支援,但該版本現已淘汰。API 第 2 版不支援這項參數。
userIp 這個參數在 API 第 1 版中受到支援,但該版本現已淘汰。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 支援其他方法,這些方法的回應可能會導入其他 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 Analytics API,擷取授權使用者頻道在 2017 年的每日觀看次數和其他指標。這個範例使用 Google API JavaScript 用戶端程式庫

首次在本機執行這個範例前,請先設定專案的授權憑證:
  1. Google API 控制台中建立或選取專案。
  2. 為專案啟用 YouTube Analytics API
  3. 在「憑證」頁面頂端,選取「OAuth 同意畫面」分頁標籤。選取電子郵件地址,輸入產品名稱 (如尚未設定),然後按一下「儲存」按鈕。
  4. 在「憑證」頁面中,按一下「建立憑證」按鈕,然後選取「Oauth 用戶端 ID」
  5. 選取應用程式類型「網頁應用程式」。
  6. 在「授權的 JavaScript 來源」欄位中,輸入您提供程式碼範例的網址。舉例來說,您可以使用 http://localhost:8000http://yourserver.example.com。您可以將「已授權的重新導向 URI」欄位留空。
  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」按鈕呼叫 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 Analytics API,擷取授權使用者頻道在 2017 年的每日觀看次數和其他指標。這個範例使用 Google API Python 用戶端程式庫

首次在本機執行這個範例前,請先設定專案的授權憑證:
  1. Google API 控制台中建立或選取專案。
  2. 為專案啟用 YouTube Analytics API
  3. 在「憑證」頁面頂端,選取「OAuth 同意畫面」分頁標籤。選取電子郵件地址,輸入產品名稱 (如尚未設定),然後按一下「儲存」按鈕。
  4. 在「憑證」頁面中,按一下「建立憑證」按鈕,然後選取「Oauth 用戶端 ID」
  5. 選取「Other」(其他) 應用程式類型,輸入「YouTube Analytics API Quickstart」名稱,然後按一下「Create」按鈕。
  6. 按一下「確定」關閉隨即顯示的對話方塊。
  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 要求和回應。