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 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==MINE 或 channel==CHANNEL_ID，其中 CHANNEL_ID 用于标识当前经过身份验证的用户的 YouTube 频道。
  • 如需请求 YouTube 内容所有者的数据，请将 ids 参数值设为 contentOwner==OWNER_NAME，其中 OWNER_NAME 是用户的 content owner ID。

metrics string
以英文逗号分隔的 YouTube Analytics 指标列表，例如 views 或 likes,dislikes。请参阅频道报告或内容所有者报告的相关文档，了解您可以检索的报告列表以及每个报告中可用的指标。（Metrics 文档包含所有指标的定义）。
startDate string
提取 YouTube Analytics 数据的开始日期。该值应采用 YYYY-MM-DD 格式。
注意：在 API 版本 1 中，此参数名为 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 请求中指定的日期相匹配的数据。
注意：在 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 不支持此参数，因为版本 2 仅支持 JSON 响应。API 响应的数据格式。
  • 有效值：json、csv
  • 默认值：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 响应会按以下顺序返回列：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. 选择“Web 应用”应用类型。
  6. 在“已获授权的 JavaScript 来源”字段中，输入您将提供代码示例的网址。例如，您可以使用 http://localhost:8000 或 http://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>

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. 将下载的文件移动到您的工作目录。

您还需要安装 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. 完成授权流程。身份验证流程可能会在浏览器中自动加载，或者您可能需要将身份验证网址复制到浏览器窗口中。在授权流程结束时，如有必要，请将浏览器中显示的授权代码粘贴到终端窗口中，然后点击 [返回]。
  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 请求和响应。