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 月 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 将用于指定以下估计收入指标的币种: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 响应将为每个视频提供单独的流量来源统计信息。
  • 如果您未将 video 添加到 dimensions 参数的值中,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 添加了对其他方法的支持,这些方法的 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,您需要将其放入代码示例中。

然后,将示例保存到本地文件。在示例中,找到以下行,并将 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. 点击确定以关闭生成的对话框。
  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 请求和响应。