YouTube 会自动为有权访问创作者工作室中相应报告的内容所有者生成一组由系统管理的广告收入报告。这些报告旨在让您以编程方式访问数据。您也可以通过 YouTube 创作者工作室的“报告”菜单，手动下载一份报告。
注意：您可以通过 API 访问与创作者工作室不同的一组报告，不过报告中包含类似数据。API 报告可能具有与创作者工作室报告不同的字段，所使用的字段名称也不同。
由于 YouTube 会自动生成系统管理的报告，因此获取这些报告的流程与通过 API 获取的 YouTube 数据分析批量数据报告的流程有所不同。
检索报告
以下步骤说明了如何通过 API 获取系统管理的报告。
第 1 步：获取授权凭据
所有 YouTube Reporting API 请求都必须获得授权。授权指南介绍了如何使用 OAuth 2.0 协议检索授权令牌。
YouTube Reporting API 请求使用以下授权范围：
| 作用域 | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics.readonly | 查看有关您的 YouTube 内容的 YouTube 数据分析报告。此范围可让您访问用户活动指标，例如观看次数和评分次数。 |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | 查看 YouTube 分析工具为您的 YouTube 内容出具的财务报表。通过此范围，您可以查看用户活动指标以及估算收入和广告效果指标。 |
第 2 步：检索所需报告的作业 ID
调用 jobs.list 方法以检索系统管理的作业列表。将 includeSystemManaged 参数设置为 true。
每个返回的 Job 资源中的 reportTypeId 属性用于标识与该作业关联的系统管理的报告的类型。在以下步骤中，您的应用需要同一资源的 id 属性值。
报告文档列出了可用的报告、其报告类型 ID 以及它们包含的字段。您还可以使用 reportTypes.list 方法来获取受支持的报告类型的列表。
第 3 步：检索报告的下载网址
调用 jobs.reports.list 方法可检索为该作业创建的报告列表。在该请求中，将 jobId 参数设置为您要检索的报告的作业 ID。
您可以使用以下任何或所有参数过滤报告列表：
-
您可以使用
createdAfter参数来指明该 API 应仅返回在指定时间之后创建的报告。此参数可用于确保 API 仅返回您尚未处理的报告。 -
您可以使用
startTimeBefore参数指明仅当报告中的最早数据在指定日期之前时，API 响应才应包含报告。createdAfter参数与报告的创建时间有关，而此日期则与报告中的数据相关。 -
使用
startTimeAtOrAfter参数可以指明，仅当报告中的最早数据在指定日期当天或之后，API 响应才应包含报告。与startTimeBefore参数一样，此参数值对应于报告中的数据，而不是报告的创建时间。
API 响应包含该作业的 Report 资源列表。每种资源都指向包含特定时期数据的报告。
- 资源的
startTime和endTime属性用于标识报表中的数据所涵盖的时间段。 - 资源的
downloadUrl属性用于标识可以从中提取报告的网址。 - 资源的
createTime属性用于指定报告生成的日期和时间。您的应用应存储此值，并使用它来确定之前下载的报告是否已更改。
第 4 步：下载报告
向在第 4 步中获得的 downloadUrl 发送 HTTP GET 请求，以检索报告。
处理报告
最佳实践
使用 YouTube Reporting API 的应用应始终遵循以下做法：
-
使用报表的标题行可以确定报表各列的排列顺序。例如，不要仅仅因为“观看次数”是报告说明中列出的第一个指标就假定“观看次数”是报告中返回的第一个指标。不过，您可以使用报告的标题行来确定哪列中包含相应数据。
-
记录您下载的报告，以免重复处理同一报告。以下列表介绍了几种实现此目的的方法。
-
调用
reports.list方法时，使用 createdAfter 参数，仅获取在特定日期之后创建的报告。（首次检索报告时省略createdAfter参数。）每次检索并成功处理报告时，请存储与最近一次创建报告时的日期与时间相对应的时间戳。然后，在每次连续调用
reports.list方法时更新createdAfter参数值，以确保您每次调用该 API 时都只检索新报告，包括带有回填数据的新报告。作为一项保护措施，在检索报告之前，请同时检查以确保您的数据库中尚未列出相应报告的 ID。
-
存储您下载和处理的每个报告的 ID。您还可以存储其他信息，例如生成每个报告的日期和时间或报告的
startTime和endTime，这些信息共同标识了报告包含的时间段。对于为 YouTube 数据分析提取批量数据的报告，由于每个报告包含 24 小时内的数据，因此每个作业都可能会有多个报告。如果作业的时间范围较长，则由系统管理的作业产生的报告会较少。使用报告 ID 识别您仍然需要下载和导入的报告。不过，如果两个新报告具有相同的
startTime和endTime属性值，则仅导入较新的createTime值的报告。
-
报告特征
API 报告是带有版本编号的 .csv（逗号分隔值）文件，具有以下特征：
-
每个报告包含从报告开始日期凌晨 00:00（太平洋时间）到报告结束日期晚上 11:59（太平洋时间）的唯一时间段的数据。
-
报告数据未排序。