Reports: Query

重要提示:对此方法的 API 请求现在需要访问 https://www.googleapis.com/auth/youtube.readonly 范围。

通过这种方法,您可以检索多个不同的 Google Analytics(分析)报告。每个请求均使用查询参数指定渠道 ID 或内容所有者、开始日期、结束日期和至少一个指标。您还可以提供其他查询参数,例如维度、过滤条件和排序说明。

  • 指标是对用户活动情况的单独衡量,例如视频观看次数或评分(顶和踩)。
  • 维度是用于汇总数据的常见条件,例如用户活动发生的日期或用户所在的国家/地区。在报表中,每行数据都有一个唯一的维度值组合。
  • 过滤条件是用来指定待检索数据的维度值。 例如,您可以检索特定国家/地区、特定视频或一组视频的数据。

注意:只有参与 YouTube 合作伙伴计划的 YouTube 内容合作伙伴才能访问内容所有者报告。

常见使用场景

请求

HTTP 请求

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

所有 YouTube Analytics API 请求都必须获得授权。授权指南介绍了如何使用 OAuth 2.0 协议检索授权令牌。

YouTube 数据分析 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。请参阅渠道报告内容所有者报告的文档,了解您可以检索到的报告及每个报告中可用的指标列表。(Metrics 文档包含所有指标的定义。)
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 数据时应该应用的过滤条件列表。渠道报告内容所有者报告的文档指出了可用于过滤各个报告的维度。维度文档定义了这些维度。

如果请求使用多个过滤器,请使用英文分号 (;) 将它们连接起来,返回的结果表格将同时满足这两个过滤器的要求。例如,如果 filters 参数值为 video==dMH0bHeiRNg;country==IT,则结果集会仅包含意大利给定视频的数据。

为过滤条件指定多个值

API 支持为 videoplaylistchannel 过滤条件指定多个值。为此,请指定一个单独的视频、播放列表或频道 ID 列表,并据此过滤 API 响应。例如,如果 filters 参数值为 video==pd1FJh59zxQ,Zhawgd0REhA;country==IT,则结果集会仅包含意大利给定视频的数据。该参数值最多可指定 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 开始)。(默认值为 1。)将此参数与 max-results 参数一起用作分页机制。
注意:在 API 版本 1 中,此参数名为 start-index
标准参数
access_token 当前用户的 OAuth 2.0 令牌。
alt API 第 2 版仅支持此参数,而 JSON 响应仅支持 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 添加了对其他方法的支持,则针对这些方法的 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. 选择 Web 应用类型。
  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. 点击执行按钮以调用该 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. 选择应用类型其他,输入名称“YouTube Analytics API 快速入门”,然后点击“创建”按钮。
  6. 点击 OK 关闭生成的对话框。
  7. 点击客户端 ID 右侧的 (下载 JSON)按钮。
  8. 将下载的文件移动到工作目录。

您还需要安装 Python 版 Google API 客户端库和一些其他库:

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 请求和响应。