YouTube Reporting API - Get Bulk Data Reports

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（逗号分隔值）的文件，具有以下特征：

• 每份报告都包含一个特定时间段的数据，该时间段从报告开始日期当天太平洋时间凌晨 12:00 开始，到报告结束日期当天太平洋时间晚上 11:59 结束。

• 报告数据未排序。