API Reference

您可以使用 YouTube Analytics API 来检索 YouTube 频道或内容所有者的 YouTube 数据分析数据。该 API 支持实时查询，并根据 API 请求参数生成报告。

该 API 支持两种类型的函数：

  • 报告检索 – API 的 reports.query 方法可检索 YouTube 数据分析报告。

  • YouTube 数据分析组管理 - YouTube 数据分析组是一个由多达 500 个频道、视频、播放列表或资产组成的自定义集合。该 API 支持多种创建、检索和更新 YouTube 数据分析组的方法。然后，频道所有者和内容所有者可以使用 reports.query 方法检索群组中所有项目的汇总数据，这有助于分析效果。

本页面简要介绍了启用这些函数的 API 资源和方法。

授权

所有 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 的 reports.query 方法检索许多不同的 YouTube 数据分析报告。每个请求均使用查询参数指定渠道 ID 或内容所有者、开始日期、结束日期和至少一个指标。您还可以提供其他查询参数，例如维度、过滤条件和排序说明。

方法 HTTP 请求 说明
相对于 https://youtubeanalytics.googleapis.com/v2 的 URI
query GET /reports 检索 YouTube 数据分析报告。每个 API 请求都使用查询参数指定渠道 ID 或内容所有者、开始日期、结束日期和至少一个指标。您还可以提供其他查询参数，例如维度、过滤条件或排序说明。
  • 指标是对用户活动情况的单独衡量，例如视频观看次数或评分（顶和踩）。
  • 维度是用于汇总数据的常见条件，例如用户活动发生的日期或用户所在的国家/地区。在报表中，每行数据都有一个唯一的维度值组合。
  • 过滤条件是用来指定待检索数据的维度值。 例如，您可以检索特定国家/地区、特定视频或一组视频的数据。
受支持的频道报告和内容所有者报告列表定义了指标、维度和过滤条件的有效组合。

群组管理

该 API 提供了两种用于创建和管理 YouTube 数据分析组的资源：

群组

group 资源表示 YouTube 数据分析组，这是一个包含最多 500 个频道、视频、播放列表或资产的自定义集合。

同一组中的所有项必须代表相同类型的资源。例如，您无法创建一个包含 100 个视频和 100 个播放列表的群组。

Analytics（分析）群组只能包含已上传或已声明版权的资源，或包含与您管理的频道关联的资源。因此，频道所有者可以创建视频和播放列表组。内容所有者可以创建视频、播放列表、频道或资产组。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法 HTTP 请求 说明
相对于 https://youtubeanalytics.googleapis.com/v2 的 URI
list GET /groups 返回与 API 请求参数匹配的组列表。例如，您可以检索经过身份验证的用户拥有的所有群组，也可以按唯一 ID 检索一个或多个群组。
insert POST /groups 创建 YouTube 数据分析组。创建群组后，请使用 groupItems.insert 方法将内容添加到群组。
update PUT /groups 修改群组的元数据。目前，唯一可以更新的属性是群组标题。（使用 groupItems.insert 和 groupItems.delete 添加和移除群组项。）
delete DELETE /groups 删除群组。

群组

groupItem 资源表示 YouTube 数据分析组中的一项。

如需详细了解此资源，请参阅其资源表示形式和属性列表。

方法 HTTP 请求 说明
相对于 https://youtubeanalytics.googleapis.com/v2 的 URI
list GET /groupItems 返回与 API 请求参数匹配的组项集合。
insert POST /groupItems 创建组项。
delete DELETE /groupItems 从群组中移除某项内容。