修订历史记录

本页面列出了 YouTube Reporting API 和 YouTube Analytics API 的 API 变更和文档更新。这两种 API 都可让开发者通过不同的方式访问 YouTube 数据分析数据。订阅此更改日志订阅

2023 年 12 月 4 日

YouTube Analytics(定位查询)API 已更新,以合并两个 insightTrafficSourceType 维度值。以前,此维度会区分在播放列表中播放的视频 (PLAYLIST) 和源自列出播放列表中的所有视频的页面的观看次数 (YT_PLAYLIST_PAGE)。今后,这两种类型的观看都将与 PLAYLIST 维度值相关联。

2022 年 12 月 15 日

YouTube Analytics(定位查询)API 支持两种新的维度和一种新报告:

  • 新报告按城市提供用户活动。此报告可供频道内容所有者使用。 此报告包含新增的 city 维度,该维度用于标识 YouTube 对用户活动发生地的城市估算值。

  • 新增的 creatorContentType 维度可标识与数据行中的用户活动指标相关联的 YouTube 内容的类型。支持的值包括 LIVE_STREAMSHORTSSTORYVIDEO_ON_DEMAND

    对于所有频道和内容所有者视频报告,支持将 creatorContentType 维度作为可选维度。

  • YouTube Analytics API 示例请求指南现在同时提供了这两个新维度的示例。

  • 从文档中移除了对 7DayTotals30DayTotals 维度的引用。我们已于 2019 年 10 月宣布弃用这些维度。

2022 年 8 月 26 日

YouTube Analytics(定位查询)API 和 YouTube Reporting(批量报告)API 都支持新的流量来源详情值:

2022 年 2 月 11 日

gender”维度的有效值集将于 2022 年 8 月 11 日当天或之后发生变化。这可能使您的 API 实现向后不兼容的更改。根据 YouTube API 服务的服务条款中的向后不兼容的更改部分,我们会在生效前六个月公布这项变更。请在 2022 年 8 月 11 日之前更新您的 API 实现方式,以确保无缝过渡到新的一组值。

具体更改如下:

  • 在 YouTube Analytics(定位查询)API 中,gender 维度目前支持两个值:femalemale。2022 年 8 月 11 日当天或之后,该维度将支持三个值:femalemaleuser_specified
  • 在 YouTube Reporting (Bulk Reports) API 中,gender 维度目前支持三个值:FEMALEMALEGENDER_OTHER。 在 2022 年 8 月 11 日当天或之后,受支持的值集将更改为 FEMALEMALEUSER_SPECIFIED

2022 年 2 月 9 日

自 2021 年 12 月 13 日起,我们更新了两个指标,以排除循环剪辑流量。这项变更会影响 YouTube Analytics(定位查询)API 和 YouTube Reporting(批量报告)API。

2022 年 2 月 2 日

此 YouTube Reporting (Bulk Reports) API 支持新的流量来源维度值,该值指示观看源自直播重定向

对于此流量来源类型,traffic_source_detail 维度用于指定观看者的来源频道 ID。

2020 年 9 月 23 日

此 YouTube Analytics(定位查询)API 和 YouTube Reporting(批量报告)API 都支持新的流量来源维度值,该值表示观看者是通过在 YouTube Shorts 观看体验中纵向滑动而引荐的:

对于这种新的流量来源类型,系统不会填充流量来源详细信息维度(YouTube Analytics API 中的 insightTrafficSourceDetail 或 YouTube Reporting API 中的 traffic_source_detail)。

2020 年 7 月 20 日

此更新包含两项会影响 YouTube Analytics(分析)(定位查询)API 的更改:

  • YouTube 数据分析报告组的规模上限从 200 个实体增加到了 500 个。
  • reports.query 方法的 filters 参数用于标识在检索 YouTube 数据分析数据时应该应用的过滤器列表。该参数支持为 videoplaylistchannel 过滤器指定多个值,并且可为这些过滤器指定的 ID 数量上限从 200 个增加到了 500 个。

2020 年 2 月 13 日

此更新包含以下与 YouTube Analytics(分析)(定位查询)API 和 YouTube Reporting(批量报告)API 相关的更改。如需详细了解相关变更,请访问 YouTube 帮助中心

在这两个 API 中,通知的可能的流量来源详细信息值集都会发生变化。在有针对性的查询中,通知会被报告为 insightTrafficSourceType=NOTIFICATION。在批量报告中,通知以 traffic_source_type=17 的形式显示。

新值将与上传的视频和直播相关的通知(之前报告为 uploaded)分为两类:

  • uploaded_push - 观看次数源自视频上传时向订阅者发送的推送通知
  • uploaded_other - 观看次数是由视频上传时发送给订阅者的非推送通知(例如电子邮件或收件箱通知)产生的。

系统会针对从 2020 年 1 月 13 日(2020 年 1 月 13 日)开始的时间范围返回这些值。

另请注意,这些值并不代表通知本身,而是代表带来某些 YouTube 观看次数的流量来源。例如,如果报告行指示 views=3traffic_source_type=17 (NOTIFICATION) 和 traffic_source_detail=uploaded_push,则该行表示观看者点击视频上传时发送的推送通知带来了 3 次观看。

2019 年 10 月 15 日

此更新包含与 YouTube Analytics(分析)(定位查询)API 相关的以下更改:

  • 注意:这是弃用公告。

    YouTube 将不再支持 7DayTotals30DayTotals 维度。在 2020 年 4 月 15 日之前,您仍然可以使用这些维度检索数据。在该日期当天或之后,如果尝试使用 7DayTotals30DayTotals 维度获取报告,则会返回错误。

    请注意,用户可以使用 day 维度进行查询,并汇总或得出 7 天或 30 天的数据,从而重现这些维度的部分数据。例如:

    • 对 7 天内每天的观看次数进行汇总即可计算出这 7 天内的观看次数。
    • 七天的观看者百分比可以用每天的观看次数乘以该日的观看者百分比计算得出,从而得到当天在观看视频时登录的观看者人数。然后,可将整个时段的已登录观看者人数除以该时段的总观看次数,从而得出整个时段的观看者百分比。
    • 系统无法计算七天的唯一身份观看者人数,因为系统可能会将同一观看者计算为在不同日期的唯一身份观看者。不过,您或许可以使用 month 维度(而非 30DayTotals 维度)来推断 30 天内的唯一身份观看者人数数据。请注意,month 维度是指日历月,而 30DayTotals 维度根据指定的开始日期和结束日期计算 30 天的时间段。

2019 年 6 月 27 日

此更新包含与 YouTube Analytics(分析)(定位查询)API 相关的以下更改:

  • 由于该 API 的版本 1 现已完全弃用,我们更新了相关文档,移除了对该版本的引用,包括弃用通知以及说明如何更新到版本 2 的迁移指南。

2018 年 11 月 1 日

此更新包含与 YouTube Analytics(分析)(定位查询)API 相关的以下更改:

  • API 版本 1 现已弃用。如果您尚未更新 API 客户端,请尽快将其更新为使用 API 版本 2,以尽可能减少服务中断。如需了解详情,请参阅迁移指南

    请注意,此次弃用的时间表最初已于 2018 年 4 月 26 日公布。

2017 年 9 月 17 日

此更新包含与 YouTube Analytics(分析)(定位查询)API 相关的以下更改:

  • 数据模型概览文档中新增的数据匿名化部分指出,当指标未达到特定阈值时,某些 YouTube 数据分析中的数据会受到限制。这种情况可能在多种情况下发生。实际上,这意味着在以下情况下,报告可能不会包含全部(或部分)数据:

    1. 视频或频道在特定时间段内的流量有限

    2. 您所选过滤条件或维度(例如流量来源或国家/地区)的值未达到特定阈值。

    这一新增部分还讨论了 YouTube 数据分析报告中可能会受限的数据类型。

  • 频道报告内容所有者报告文档进行了更新,以反映播放位置、流量来源和设备类型/操作系统报告不再支持 redViewsestimatedRedMinutesWatched 指标。

2018 年 6 月 18 日

此更新包含对 YouTube Analytics(分析)(定位查询)API 的以下更改:

  • 以下方法的范围要求已更改:
    • reports.query 方法的请求必须有权访问 https://www.googleapis.com/auth/youtube.readonly 范围。
    • groupItems.list 方法的请求必须有权访问:
      • https://www.googleapis.com/auth/youtube 范围
      • https://www.googleapis.com/auth/youtube.readonly 范围

        https://www.googleapis.com/auth/yt-analytics.readonly 范围

      第一个选项使用一个范围(恰好是读写范围),而第二个选项使用两个只读范围。

2018 年 5 月 23 日

此更新包含对 YouTube Analytics(分析)(定位查询)API 的以下更改:

  • API 概览中新增了汇总指标和已删除的内容部分,其中说明了 API 响应如何处理与已删除资源(例如视频、播放列表或频道)关联的数据。
  • “API 概览”的最佳做法部分已作如下更新:您可以使用 YouTube Data API 为 YouTube Analytics API 响应中标识的资源检索其他元数据。根据 YouTube API 服务开发者政策(第 III.E.4.b 至 III.E.4.d 节)的规定,API 客户端必须在 30 天后从该 API 中删除或刷新存储的资源元数据。

2018 年 5 月 22 日

此更新包含与 YouTube Reporting (Bulk Reports) API 相关的以下更改:

  • 目前,以下变更计划于 2018 年 7 月生效,新政策将在全球范围内应用于所有报告和报告作业。
    • 更改之后,大多数 API 报告(包括补余广告报告)将在生成之日后保留 60 天。不过,包含历史数据的报告将在生成之日后保留 30 天。

      在发布此公告之前,所有 API 报告均可使用 180 天(自生成之时起算)。需要说明的是,当此政策变更生效后,保存时间超过 30 天的历史数据报告也无法再通过该 API 访问。生成时间已超过 60 天的所有其他报告也将无法再访问。因此,文档现在指出,在政策更改之前创建的报告最多可以保留 180 天。

    • 更改生效后,当您安排报告作业时,YouTube 会从当天开始生成相关报告,并涵盖安排报告作业前 30 天内的数据。在更改之前,当您安排一个报告作业时,YouTube 会生成涵盖该作业预定前 180 天的报告。

  • 最佳实践部分已更新,以提醒你您可以使用 YouTube Data API 检索报告中所标识资源的其他元数据。根据 YouTube API 服务开发者政策(第 III.E.4.b 至 III.E.4.d 节)的规定,API 客户端必须在 30 天后从该 API 中删除或刷新存储的资源元数据。

  • “报告特征”部分已作如下更新:即使报告数据未过滤,包含 2018 年 6 月 1 日当天或之后时间段的数据的报告也不会包含任何在报告生成前至少 30 天内删除的 YouTube 资源的引用。

  • API 概览的历史数据部分已作如下更新:安排新的报告作业时,历史报告通常会在几天内发布。以前,相关文档指出最多可能需要 30 天才能提供此类报告。

  • 我们更新了 API 概览的回填数据部分,以便更明确地将回填数据定义为用于替换之前投放的集合的数据集。

2018 年 4 月 26 日

YouTube Analytics(定位查询)API 第 2 版 (v2) 现已公开发布。以下列表列出了与新 API 版本相关的产品和文档更改:

  • v2 API 与 v1 API 几乎完全相同。不过,您可能需要更新代码以反映下列更改。新版迁移指南中详细介绍了所有这些更改。

    • API 的版本已从 v1 更改为 v2
    • API 请求的基准网址已从 https://www.googleapis.com/youtube/analytics/v1 更改为 https://youtubeanalytics.googleapis.com/v2
    • reports.query 方法的多个参数更新了名称。具体而言,包含连字符的参数名称(例如 v1 API 中的 end-date 采用驼峰式大小写形式 (endDate))而不是连字符 v2 API 中。此更改使参数名称在整个 API 中保持一致,因为 API 的创建和管理群组方法已经使用驼峰式大小写格式表示参数名称。
    • v2 API 不支持向 Google 的全球 HTTP 批量端点 (www.googleapis.com/batch) 发送批量请求。如果您在 v2 API 中发送批量请求,则需要改用端点 https://youtubeanalytics.googleapis.com/v2

    此外,有几个 v1 功能在 v2 API 中也不受支持:

    • reports.query 方法不再支持 altquotaUseruserIp 请求参数。
    • v2 API 不提供支持由对不同 API 的请求组成的批次的批次端点。(不过,一个批次可能包含对同一 API 的不同方法的请求。)这次弃用不是针对 YouTube Analytics API 的,因为 Google 即将弃用其所有 API 中的全球批量端点。
    • v2 API 不支持 API v1 中支持的 JSON-RPC 协议。再次强调,这次弃用不是专门针对 YouTube Analytics API 的。

  • 注意:这是弃用公告。

    API 第 1 版 (v1) 现已弃用,支持将于 2018 年 10 月 31 日结束。在该日期之后,对 v1 API 的所有请求都将停止运行。因此,请务必在 2018 年 10 月 31 日之前升级到 API 第 2 版,以免无法正常通过该 API 访问 YouTube 数据分析数据。

2018 年 2 月 21 日

此更新包含对 YouTube Analytics(分析)(定位查询)API 的以下更改:

  • 根据观看者的年龄段和性别汇总观看统计信息的观看者受众特征报告已不再支持 youtubeProduct 维度(该维度用于识别发生用户活动的 YouTube 服务)。

2018 年 1 月 18 日

此更新包含以下更改:

  • YouTube Reporting API(批量报告)

    • operating_system 维度用于标识发生观看的设备的软件系统,现在支持以下值:
      • 25:KaiOS
  • YouTube Analytics API(定位查询)

2017 年 12 月 20 日

此更新包含与 YouTube Reporting API 相关的两项更改:

  • 现在,对于下载报告的请求,API 服务器支持 gzip 压缩。请注意,其他类型的 API 请求不支持 gzip 压缩。启用 gzip 压缩,可减少每个 API 响应所需的带宽。此外,虽然您的应用将需要额外的 CPU 时间来解压缩 API 响应,但消耗较少网络资源的好处通常已超过了该成本。

    要接收 gzip 编码的响应,请将 Accept-Encoding HTTP 请求标头设置为 gzip,如以下示例所示:

    Accept-Encoding: gzip

    如需了解此功能,请参阅 API 概览report 资源的 downloadUrl 属性定义。

  • 更正了 age groupgender 维度的文档,以显示 API 针对这些维度返回的实际值。请注意,这是文档更正,并不反映 API 功能或行为的变化。具体而言,以下值已更改:

    • age_group”维度的值使用大写字母,在单词 AGE 和年龄段的数字之间添加下划线,并使用下划线代替连字符。因此,age13-17age18-24 等值已分别更正为 AGE_13_17AGE_18_24
    • gender”维度的值使用大写字母。因此,值 femalemalegender_other 已更正为 FEMALEMALEGENDER_OTHER

2017 年 8 月 10 日

2016 年 8 月 10 日,本文档宣布弃用 YouTube Analytics API 的 earnings 指标。(同时,该 API 增加了对一个名为 estimatedRevenue 的新指标的支持,该指标提供了相同的数据。)

由于“earnings”指标是核心指标,因此从公告之日起一年内支持该指标。不过,由于这一年的期限已结束,earnings 指标不再受支持。因此,指定 earnings 指标的 API 请求现在会返回 400 HTTP 响应代码。如果您尚未更新应用以使其使用 estimatedRevenue 指标(而非 earnings 指标),请尽快完成更新。

API 文档已更新,移除了对 earnings 指标的其余引用。

2017 年 7 月 6 日

此更新包含以下更改:

  • YouTube Analytics API(定位查询)

    • API 文档已更新,以体现以下事实:API 响应包含截至所请求日期范围最后一天的数据,且所有要查询的指标均可用。

      例如,如果请求指定的结束日期为 2017 年 7 月 5 日,而所有所请求的指标的值都只在 2017 年 7 月 3 日之前提供,那么这就是在响应中包含数据的最后日期。(即使所请求的部分指标有 2017 年 7 月 4 日的数据,也是如此)。

    • adType 维度现在支持值 reservedBumperInstream,该值表示最长为 6 秒的不可跳过的视频广告,在用户观看视频前播放。广告格式与 auctionBumperInstream 广告相同,但此类型是指通过预订而不是竞价方式销售的广告。

  • YouTube Reporting API(批量报告)

    • ad_type 维度现在支持值 20,该值是指通过预订方式出售的导视广告。导视广告是一种最长 6 秒钟的不可跳过的视频广告,在用户观看视频之前播放。请注意,此维度的值 19 也指通过竞价(而非预订方式)销售的导视广告。

    • 以下 YouTube Reporting API 报告的报告作业已被删除:

      • channel_basic_a1
      • channel_province_a1
      • channel_playback_location_a1
      • channel_traffic_source_a1
      • channel_device_os_a1
      • channel_subtitles_a1
      • channel_combined_a1
      • content_owner_basic_a2
      • content_owner_province_a1
      • content_owner_playback_location_a1
      • content_owner_traffic_source_a1
      • content_owner_device_os_a1
      • content_owner_subtitles_a1
      • content_owner_combined_a1
      • content_owner_asset_basic_a1
      • content_owner_asset_province_a1
      • content_owner_asset_playback_location_a1
      • content_owner_asset_traffic_source_a1
      • content_owner_asset_device_os_a1
      • content_owner_asset_combined_a1

      我们已于 2016 年 9 月 15 日宣布已弃用这些报告类型,并于 2016 年 12 月 15 日之后不再针对这些报告类型生成报告。之前生成的报告仍可在 180 天内使用。因此,某些报告在 2017 年 6 月 15 日才可供访问。但是,由于报告不再可用,也不需要与报告关联的作业。

2017 年 5 月 24 日

以下 YouTube Reporting API 报告的所有报告作业均已删除:

  • content_owner_ad_performance_a1
  • content_owner_asset_estimated_earnings_a1
  • content_owner_estimated_earnings_a1

我们已在 2016 年 6 月 22 日宣布弃用这些报表类型,自 2016 年 9 月 22 日起,系统将不再为这些报表类型生成报表。之前生成的报告仍可在 180 天内使用。因此,某些报告可追溯至 2017 年 3 月 22 日。但是,由于报告不再可用,也不需要与报告关联的作业。

2017 年 5 月 22 日

此更新包含以下更改:

  • YouTube Reporting API(批量报告)

    • sharing_service 维度(用于标识用于分享视频的服务)现在支持以下值:

      • 85:YouTube Music
      • 86:YouTube 游戏
      • 87:YouTube Kids
      • 88:YouTube TV

      此外,文档中用于标识值 52 的名称已更新为 Kakao (Kakao Talk),以便更明确地将其与值 73 (Kakao Story) 区分开来。此变更并不反映与这些服务共享的视频的 API 行为或分类的任何变化。

  • YouTube Analytics API(定位查询)

    • sharingService 维度现在支持以下值:

      • YOUTUBE_GAMING
      • YOUTUBE_KIDS
      • YOUTUBE_MUSIC
      • YOUTUBE_TV

2017 年 3 月 28 日

如果频道所有者可以通过创作者工作室中的 YouTube 数据分析查看收入数据,那么现在也可以通过 YouTube Analytics API 查看这些收入数据:

2017 年 3 月 17 日

此更新包含以下更改:

2017 年 3 月 3 日

此更新包含以下更改:

  • YouTube Reporting API(批量报告)

    • 更正了 date 维度的定义,以注意到该维度值是指从太平洋时间凌晨 12:00 开始,到指定日期、月份和年份的晚上 11:59(太平洋时间)结束的时间段。根据一年中的不同时间,太平洋时间可以是 UTC-7 或 UTC-8。

      虽然日期通常表示 24 小时时间段,但将时钟向前调的日期表示 23 小时的时间段,而向后调整的日期表示 25 小时时间段。(以前,相关文档指出每个日期代表一个唯一的 24 小时时间段,并且太平洋时间始终为 UTC-8。)

      请注意,这一更正并不代表实际 API 行为的变化。

    • operating_system 维度用于标识发生观看的设备的软件系统,它现在支持以下值:
      • 22:Tzen
      • 23:Firefox
      • 24:RealMedia
    • 已删除“content_owner_basic_a1”报告类型的所有报告作业。自 2016 年 8 月 19 日起,这种类型的报表已被完全弃用,但之前生成的 content_owner_basic_a1 报表仍可在生成后的 180 天内使用。因此,某些报告可追溯至 2017 年 2 月 19 日。但是,由于报告不再可用,也不需要与报告关联的作业。

  • YouTube Analytics API(定位查询)

    • time periods 相关的维度说明已更正,以指出维度值是指从太平洋时间凌晨 12:00 开始,到指定日期、月份和年份的晚上 11:59(太平洋时间)结束的时间段。根据一年中的不同时间,太平洋时间可以是 UTC-7 或 UTC-8。

      虽然日期通常表示 24 小时时间段,但将时钟向前调的日期表示 23 小时的时间段,而向后调整的日期表示 25 小时时间段。(之前,相关文档指出太平洋时间是 UTC-8,并未提及一天可能并非代表 24 小时时间段。)

      请注意,这一更正并不代表实际 API 行为的变化。

    • 渠道报告文档进行了更新,以表明渠道报告目前不包含收入或广告效果指标。因此,https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围目前不授予对渠道报告中的货币数据的访问权限。

    • operatingSystem 维度支持以下三种新的维度值:
      • FIREFOX
      • REALMEDIA
      • TIZEN

2017 年 2 月 8 日

YouTube Analytics API 现在支持可选的 include-historical-channel-data 参数。请注意,此参数仅在检索内容所有者报告时才相关。

通过该参数,内容所有者可以指明 API 响应应包含相应频道与内容所有者关联之前的时间段内的观看时长和观看次数数据。默认参数值为 false,这意味着,默认情况下,API 响应仅包含自频道关联到内容所有者以来的观看时长和观看次数数据。

如果 API 请求检索多个渠道的数据,这些规则同样适用:

  • 如果参数值为 false,则系统针对任何指定频道返回的观看时长和观看次数数据都是以该频道与内容所有者相关联的日期为基准。

    请务必注意,不同的频道可能在不同的日期关联到同一内容所有者。如果 API 请求要检索多个频道的数据,且参数值为 false,则 API 响应会包含基于每个频道关联日期的观看时长和观看次数数据。
  • 如果参数值为 true,则响应会根据 API 请求中指定的开始日期和结束日期返回所有频道的观看时长和观看数据。

2016 年 12 月 15 日

以下 YouTube Reporting API 报告已不再受支持,并已从相关文档中移除。每个报告都有更新的版本。(我们于 2016 年 9 月 15 日发布了弃用公告公告。)

API 参考文档中的当前报告类型列表也已更新。

2016 年 11 月 11 日

此更新包含以下更改:

    YouTube Reporting API 支持三种新的片尾画面报告,以及这些报告的新维度和指标。报告可提供视频停止播放后显示的片尾画面的展示和点击统计信息。

    2016 年 11 月 8 日

    此更新包含对 YouTube Analytics API 的以下更改:

    • 以下列表中的指标已完全弃用,不再受支持。正如我们在 2016 年 8 月 10 日所宣布的那样,已支持引用相同数据的新指标。下表显示了已弃用的指标名称和新指标名称:

      已弃用的指标 新指标
      adEarnings estimatedAdRevenue
      impressionBasedCpm cpm
      impressions adImpressions
      redPartnerRevenue estimatedRedPartnerRevenue

    2016 年 10 月 27 日

    现在,YouTube 会针对可在 YouTube 创作者工作室的报告部分中访问相应报告的内容所有者自动生成一组由系统管理的广告收入报告。新的由系统管理的 API 报告旨在以编程方式访问数据,这些数据在可手动下载的创作者工作室报告中也提供。

    系统管理的报告概览简要介绍了新报告,并说明了通过 API 获取这些报告的过程。此流程与批量获取 YouTube 数据分析报告的流程略有不同,因为合作伙伴不需要安排任务来生成报告。

    reportType 资源的 id 属性已更新,以包含您可以通过 API 访问的系统管理的报告列表:

    • 每个视频的全球每月广告收入
    • 每个国家/地区每个视频的每日广告收入
    • 全球每月广告收入(每项资产)
    • 每个国家/地区每项资产的每日广告收入
    • 版权主张(此报告不包含收入数据)

    2016 年 9 月 27 日

    注意:这是弃用公告。

    YouTube Analytics API 的“uniques”指标已弃用。这不是核心指标,在 2016 年 10 月 31 日之前仍受支持。

    2016 年 9 月 15 日

    此更新包含以下 YouTube Reporting API 更改:

    2016 年 8 月 19 日

    此更新包含以下 YouTube Reporting API 更改:

    2016 年 8 月 11 日

    此更新包含以下更改:

    • 新发布的 YouTube API 服务的《服务条款》(以下简称“更新后的条款”),YouTube 工程和开发者博客上对此进行了详细讨论,其中介绍了一系列针对现行服务条款的丰富更新。除将于 2017 年 2 月 10 日生效的更新后的条款外,本更新还包含一些支持文档,用于说明开发者必须遵守哪些政策。

      如需了解全部新文档,请参阅更新后的条款修订历史记录。此外,后续对更新后的条款或支持文档所做的变更也会在修订历史记录中进行说明。您可以通过该文档中的链接订阅列有该修订历史记录中各项更改的 RSS Feed。

    2016 年 8 月 10 日

    此更新包含以下更改:

    • YouTube Analytics API(定位查询)

      • 注意:这是弃用公告。

        下表中的指标即将弃用。同时,我们还引入了引用相同数据的新指标。实际上,这意味着对旧指标进行了重命名,但 YouTube Analytics API 会在表格中列出的弃用日期之前支持这两个指标名称。

        旧指标名称 新指标名称 支持日期
        earnings estimatedRevenue 2017 年 8 月 10 日
        adEarnings estimatedAdRevenue 2016 年 11 月 4 日
        redPartnerRevenue estimatedRedPartnerRevenue 2016 年 11 月 4 日
        impressionBasedCpm cpm 2016 年 11 月 4 日
        impressions adImpressions 2016 年 11 月 4 日

        请注意,earnings 指标属于核心指标,因此支持期限为本公告发布之日起一年。其他不属于核心指标的指标将继续使用三个月,直到 2016 年 11 月 4 日为止。

        例如,在 2016 年 11 月 4 日之前,API 请求可以指定 impressionBasedCpm 指标和/或 cpm 指标。不过,在该日期之后,系统将仅支持 cpm 指标。

      • insightTrafficSourceType 维度支持两个新的维度值:
        • CAMPAIGN_CARD:只有内容所有者报告支持此流量来源。它表明观看次数源自已声明版权的用户上传视频,而内容所有者利用这些视频宣传了播放过的内容。
        • END_SCREEN:此数据与源自另一个视频的片尾画面的观看次数有关。

        对于这两种新流量来源,您还可以检索 traffic source detail 报告。在这两种情况下,insightTrafficSourceDetail 维度都会标识引荐观看者的视频。

      • adType 维度现在支持值 auctionBumperInstream,该值表示最长为 6 秒的不可跳过的视频广告,在用户观看视频前播放。

    • YouTube Reporting API(批量报告)

      • traffic_source_type 维度现在支持以下值:
        • 19:只有内容所有者报告支持此流量来源。它表明观看次数源自已声明版权的用户上传视频,而内容所有者利用这些视频宣传了播放过的内容。
        • 20:此数据与源自另一个视频的片尾画面的观看次数有关。

        对于这两种新流量来源,traffic_source_detail 维度用于标识引荐观看者的视频。

      • 已更正该 API 的核心指标列表,将 estimated_partner_revenue 列为核心指标,并从该列表中移除 earnings。(YouTube Reporting API 中从不支持 earnings 指标。)

      • ad_type 维度现在支持值 19 来指代导视广告。导视广告是一种最长 6 秒钟的不可跳过的视频广告,在用户观看视频之前播放。

    2016 年 7 月 18 日

    此更新包含以下更改:

    • YouTube Analytics API(定位查询)

      • 以下渠道报告支持的指标列表已更新,现在包含卡片指标。实际上,自 2016 年 6 月 28 日起,我们在这些报告中新增了对卡片指标的支持。相应日期的修订历史记录条目详细介绍了相关变更。报告包括:
        • 美国各州的基本用户活动
        • 特定时间段内美国各州的用户活动
        • 用户活动(按省份)
        • 按订阅状态细分的用户活动
        • 按订阅状态细分的用户活动(按省份)
        • 热门视频(按州)
        • 订阅或未订阅观看者的热门视频
      • 已更正频道观众黏度报告内容所有者观众黏度报告的过滤条件列表,以反映必须使用 video 过滤条件且不支持 group 过滤条件。

        以前,有关这两种报告的文档都错误地指出,可以通过使用这两种过滤器之一或不使用过滤器来检索报告。

    • YouTube Reporting API(批量报告)

      • API 概述中,我们更正了介绍如何获取报告下载网址的部分,指出 YouTube 会在没有可用数据的日期生成可下载的报告。这些报告包含标题行,但不包含其他数据。此信息已于 2016 年 4 月 12 日在同一文档的报告特征部分更新。
      • 更正了 content_owner_asset_cards_a1 报告中的维度列表,以反映该报告使用 card_id 维度。之前,文档错误地将维度名称列为 card_title

    2016 年 6 月 28 日

    YouTube Analytics API 文档进行了更新,以反映众多频道内容所有者报告中对卡片指标的支持。新增支持的指标包括:

    以下类型的报告支持这些指标:

    2016 年 6 月 22 日

    此更新包含以下 YouTube Reporting API 更改。第一个更改通常与 API 相关,其余更改仅影响内容所有者报告

    • 我们更新了 API 概览的报告特征部分,以阐明在报告生成后的 180 天内,可通过 API 获取报告。

      之前,该文档指出,报告最长可保留 180 天内(从 API 请求发出之日算起)。虽然从技术层面来说,原始文字至少也相当混乱。

    • 该 API 支持三种报告的新版本。其中两个报告中也包含新指标和重命名后的指标:

      • content_owner_ad_rates_a1 报告是 content_owner_ad_performance_a1 报告的新版本。新重命名的报告与之前的版本完全相同。

      • 重命名了两个具有新版本的报告:

        • 新版 content_owner_estimated_earnings_a1 报告命名为 content_owner_estimated_revenue_a1
        • 新版 content_owner_asset_estimated_earnings_a1 报告命名为 content_owner_asset_estimated_revenue_a1

        新重命名的两种报告与前身报告在以下方面有所不同:

      请注意,如果您已经有用于创建这些旧版报告的任何作业,则需要为重命名的报告创建新作业。随着新版报告版本的发布,content_owner_ad_performance_a1content_owner_estimated_earnings_a1content_owner_asset_estimated_earnings_a1 报告也已弃用。

      如果您有用于其中任一报告的作业,YouTube 在 2016 年 9 月 22 日之后应该不会再生成这些作业的新报告。生成的报表仍会保留 180 天(自生成之时起算)。

    • 更新了 reportType 资源的 id 属性的定义,以反映当前可用的报告集。

    • 我们已在相关文档中更正了两个指标的名称,使其与报告中显示的名称一致。这纯粹是为了修复文档,并不反映实际报告内容的变化:

      • estimated_partner_adsense_revenue”指标的名称已更新为“estimated_partner_ad_sense_revenue”。但请注意,此指标仅显示在此次更新后即将弃用的两个报告中。如上所述,此指标在这类报告的较新版本中已重命名为 estimated_partner_ad_auction_revenue
      • estimated_partner_doubleclick_revenue”指标的名称已更新为“estimated_partner_double_click_revenue”。另请注意,该指标仅显示在此次更新后即将弃用的两个报告中。如上所述,此指标在这类报告的较新版本中已重命名为 estimated_partner_ad_reserved_revenue

    • Reporting API 的维度文档已更新,不再列出 elapsed_video_time_percentageaudience_retention_type 属性。目前,该 API 生成的任何报告都不支持这些维度。

    2016 年 5 月 19 日

    此更新包含以下 YouTube Reporting API 更改:

    • 此 API 支持新版面向内容所有者的用户活动报告。新报表的报表类型 ID 为 content_owner_basic_a2。与旧版报告 content_owner_basic_a1 不同,新版本支持 likesdislikes 指标。

      如果您已有可用于创建 content_owner_basic_a1 报告的作业,则仍需要为 content_owner_basic_a2 报告创建新作业。YouTube 不会自动将内容所有者迁移到新报告版本,也不会自动创建作业来生成新的报告版本。在某些实现中,出现意外的新作业可能是一项重大更改。

      随着新报告的发布,content_owner_basic_a1 报告已被弃用。如果您拥有一份相关报告,YouTube 在 2016 年 8 月 19 日之后应该不会再为该招聘信息生成新报告。生成的报表仍会保留 180 天(自生成之时起算)。

    • reportTypejobreport 资源均支持一个新属性,用于标识关联的资源是否代表已弃用的报告类型:

      • reportType 资源的 deprecateTime 属性用于指定弃用报告类型的日期和时间。此属性仅适用于已宣布为“已弃用”的报告,且该值表示 YouTube 停止生成相应类型的报告的日期。

        在宣布弃用某种类型的报告后,YouTube 会在接下来的 3 个月内生成该类型的报告。例如,我们在 2016 年 5 月 19 日进行的这次更新宣布弃用 content_owner_basic_a1 报告。因此,该报告类型的 deprecateTime 指定了在 2016 年 8 月 19 日这一天,之后 YouTube 将停止生成此类型的报告。

      • job 资源的 expireTime 属性用于指定招聘信息过期或即将过期的日期和时间。如果与作业关联的报告类型已弃用,或者为作业生成的报告长时间没有下载,则此属性具有值。该日期是指 YouTube 在此之后不再针对该作业生成新的报告的时间。

      • report 资源的 jobExpireTime 属性用于指定与报告关联的作业已过期或即将到期的日期和时间。此属性包含的值与 job 资源中的 expireTime 属性相同,如本列表中的上一项所述。

    • 如果您尝试为已弃用的报告创建作业,jobs.create 方法现在会返回 400 HTTP 响应代码 (Bad Request)。此外,该方法的文档现在列出了导致 API 请求失败的几种其他原因。

    2016 年 4 月 12 日

    本次更新包含以下更改,所有这些更改都只影响 YouTube Reporting API:

    • YouTube 现在可生成涵盖首次安排报告作业之前的 180 天的数据。以前,Reporting API 不提供任何历史数据。这项变更会影响所有作业,包括在此公告之前创建的作业。

      历史报表一经发布,便会立即发布,但大约需要一个月的时间才能发布一个作业的所有历史数据。因此,在安排报告作业一个月后,您将可以访问大约七个月的数据。(在此公告之前创建的招聘信息的所有历史数据都应在该公告发布的一个月内发布。)

      请注意,我们仅提供自 2015 年 7 月 1 日起的历史数据。因此,对于在 2015 年 12 月 28 日之前创建的作业,其历史数据将会少于 180 天。

      如需了解这些变化,请参阅 Reporting API 概览的新历史数据部分。

    • YouTube Reporting API 概览的报告特征部分已更新,包含以下更改:

      • 现在,文档说明,报告在生成后 180 天内可供访问,因此可供 API 客户端下载。以前,相关文档指出,报告可在 API 请求发送之日前最多六个月内提供。

      • 本文档已更新,以体现 API 现在针对没有数据的日期生成可下载的报告。这些报告将包含标题行,但不包含其他数据。

    • YouTube Reporting API 很快将支持一组由系统管理、自动生成的报告,其中包含广告收入数据或 YouTube Red 订阅收入数据。这些报告将可供内容所有者在 YouTube 创作者工作室中查看可手动下载的收入报告。因此,新的 API 功能将提供对这些数据的程序化访问。

      为了迎接系统管理的报告的发布工作,我们即将公布以下 API 变更:

      • job 资源的新 systemManaged 属性指示该资源是否描述的是生成系统管理报告的作业。YouTube 会自动为 YouTube 内容所有者生成系统管理的报告,并且内容所有者无法修改或删除创建这些报告的作业。

      • jobs.list 方法的新 includeSystemManaged 参数用于指明 API 响应是否应包含系统管理报告的作业。该参数的默认值为 false

      • jobs.reports.list 方法新增的 startTimeAtOrAfter 参数指明,仅当报告中最早的数据不早于指定日期时,API 响应才应包含报告。同样,startTimeBefore 参数用于指明仅当报告中的最早数据在指定日期之前时,API 响应才应包含报告。

        该方法的 createdAfter 参数与报告的创建时间相关,而新参数则与报告中的数据相关。

      • reportType 资源的新 systemManaged 属性用于指明该资源是否描述的是系统管理的报告。

      • reportTypes.list 方法的新 includeSystemManaged 参数用于指明 API 响应是否应包含系统管理的报告。该参数的默认值为 false

    2016 年 3 月 28 日

    YouTube Reporting API 和 YouTube Analytics API 现在会返回一些其他分享服务的观看统计信息。

    • 在 YouTube Reporting API 中,sharing_service 维度支持以下新值:
      • 82:iOS 系统 activity 对话框
      • 83:Google 收件箱
      • 84:Android Messenger
    • 在 YouTube Analytics API 中,sharingService 维度支持以下新值:
      • ANDROID_MESSENGER:Android Messenger
      • INBOX:Google 收件箱
      • IOS_SYSTEM_ACTIVITY_DIALOG:iOS 系统 activity 对话框

    2016 年 3 月 16 日

    此次更新包含以下变更,这些变更对 YouTube Reporting API 和 YouTube Analytics API 都有影响:

    YouTube Reporting API

    • playback_location_type 维度支持两个新的维度值:
      • 7:此数据与 YouTube 首页或主屏幕上、用户的“订阅”Feed 或其他 YouTube 浏览功能中的观看次数有关。
      • 8:此数据与直接在 YouTube 搜索结果页上发生的观看有关。
    • traffic_source_type 维度现在支持 18 作为维度值。此值表示视频观看次数源自列有播放列表中的所有视频的网页。此来源与来源类型 14 不同,后者表示观看次数是在视频作为播放列表中的一部分播放时发生的。

    YouTube Analytics API

    • insightPlaybackLocationType 维度支持两个新的维度值:
      • BROWSE:此数据与 YouTube 首页或主屏幕上、用户的“订阅”Feed 或其他 YouTube 浏览功能中的观看次数有关。
      • SEARCH:此数据与直接在 YouTube 搜索结果页上发生的观看有关。
    • insightTrafficSourceType 维度现在支持 YT_PLAYLIST_PAGE 作为维度值。此值表示视频观看次数源自列有播放列表中的所有视频的网页。此来源不同于 PLAYLIST 来源类型,后者表示观看次数是在视频作为播放列表中的一部分播放时发生的。

    2016 年 2 月 8 日

    YouTube Analytics API 支持的指标列表已更新,卡片指标不再列为该 API 支持的指标。(该 API 的所有报告均未记录为支持任何卡片指标)。

    请注意,您仍然可以使用 YouTube Reporting API 检索卡片指标,YouTube Reporting API 支持众多频道内容所有者报告中的这些指标。

    2016 年 1 月 6 日

    YouTube Reporting API 和 YouTube Analytics API 现在可专门识别通过 Chromecast 设备产生的观看次数。

    • 在 YouTube Reporting API 中,operating_system 维度使用值 21 来识别通过 Chromecast 发生的观看。
    • 在 YouTube Analytics API 中,operatingSystem 维度使用值 CHROMECAST 来识别通过 Chromecast 发生的观看。

    2015 年 12 月 21 日

    在该文档中,annotation_clickable_impressionsannotation_closable_impressions 指标的名称已更新,以与报告中返回的名称保持一致。以前,这两个名称记录为 clickable_annotation_impressionsclosable_annotation_impressions

    2015 年 12 月 18 日

    根据欧盟 (EU) 法律,您必须向欧盟境内的最终用户披露相关信息并征得其同意。因此,对于欧盟境内的最终用户,您必须遵守欧盟地区用户意见征求政策。我们已在 YouTube API 服务条款中添加了关于此要求的通知。

    2015 年 12 月 15 日

    此更新包含以下更改,所有这些更改都会影响 YouTube Analytics API:

    • YouTube Analytics API 现在支持 3 种新的播放详情维度,这些维度可用于各种频道和内容所有者报告中:

      • liveOrOnDemand:此维度用于指明报告中的数据是否描述了直播期间发生的用户活动。
      • subscribedStatus:此维度用于指明数据中的用户活动指标是否与订阅了视频或播放列表频道的观看者相关联。
      • youtubeProduct:此维度用于标识发生用户活动的 YouTube 媒体资源。可能的值包括核心 YouTube 网站(或 YouTube 应用)、YouTube Gaming 和 YouTube Kids。

      本文档进行了更新,以确定适用于频道内容所有者的新播放详情报告。此外,许多其他报告也进行了更新,以指明这些维度中的一个或多个可以选择用作这些报告中的维度和/或过滤条件。

    • 报告表格的格式发生了变化,让您能更轻松地确定可用于检索每个报告的有效维度、指标和过滤条件组合。下表介绍了渠道的“设备类型”报告,其中展示了新格式:

      目录
      尺寸:
      必需 deviceType
      使用 0 项或更多项 dayliveOrOnDemandsubscribedStatusyoutubeProduct
      指标:
      使用 1 项或更多项 viewsestimatedMinutesWatched
      过滤器:
      使用 0 或 1 countryprovince都不会subContinent
      使用 0 或 1 videogroup
      使用 0 项或更多项 operatingSystemliveOrOnDemandsubscribedStatusyoutubeProduct

      频道内容所有者报告文档中介绍了用于描述必填字段和选填字段的术语。

    • YouTube Analytics API 现在会自动删除 API 用户无法从支持多个值(videoplaylistchannel)的过滤器中获取数据的实体。以前,如果 API 用户无法访问至少一个指定项的数据,则 API 服务器会返回错误。

      例如,假设某位用户提交了一个 API 请求,其中 video 过滤条件列出了 20 个视频 ID。用户拥有其中 18 个视频。但是,一个视频 ID 用于标识归其他频道拥有的视频,另一个 ID 用于标识已删除且已不存在的视频。在此情况下,API 服务器现在不会返回错误,而是会丢弃用户无法访问的两个视频,并且 API 响应会包含 API 用户拥有的 18 个视频的数据。

    • 如果您请求空 YouTube 数据分析 group 的数据,API 现在会返回空数据集,而不是错误。

    • 现在,如果您尝试向群组添加实体,但您无权访问该实体,YouTube Analytics API 的 groupItems.insert 方法就会返回“未授权”(403 HTTP 响应代码)错误。以前,API 允许您将实体添加到群组,但之后当您尝试检索该群组的报告数据时,会返回未经授权的错误。

    • YouTube Analytics API 的 groups.list 方法现在支持分页。如果 API 响应未包含所有可用的组,则响应的 nextPageToken 参数会指定可用于检索下一页结果的令牌。将该方法的 pageToken 形参设置为该值,以检索其他结果。

    2015 年 11 月 10 日

    此更新包含以下更改:

    2015 年 10 月 29 日

    此更新包含以下更改:

    • 更正了 YouTube Reporting API 中 date 维度的相关文档,以反映从太平洋时间 (UTC-8) 午夜 12:00 开始的 24 小时时间段。以前,相关文档指出该日期的开始时间为格林尼治标准时间 (GMT) 凌晨 12:00。

      此外,YouTube Analytics API 文档已更新,以注明所有与日期相关的维度(day7DayTotals30DayTotalsmonth)都是指从太平洋时间 (UTC-8) 凌晨 12:00 开始的日期。

    • YouTube Reporting API 的 jobs.reports.list() 方法现在支持 createdAfter 查询参数。如果指定,此参数就指示 API 响应应仅列出在指定日期和时间后创建的报告,包括含有回填数据的新报告。请注意,该参数值与报告的创建时间有关,而不是与返回数据的日期相关。

      此参数值是采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式的时间戳,精确到微秒。示例:"2015-10-02T15:01:23.045678Z"

      YouTube Reporting API 最佳做法也已更新,介绍了如何使用 createdAfter 参数避免重复处理同一报告。

    • job 资源的 createTime 属性以及 report 资源的 startTimeendTimecreateTime 属性的定义都已更正,请注意属性值精确到微秒,而非纳秒。此外,所有定义现在都会准确反映属性值是时间戳。

    2015 年 10 月 8 日

    此更新包含以下更改:

    • 更新了 YouTube Analytics API 的 sharingService 维度文档,添加了一系列可能的维度值。该列表包含一些新支持的服务。

      YouTube Reporting API 的 sharing_service 维度的定义也已更新,以列出新支持的值。大于 59 的枚举值是列表中的新值。

    2015 年 9 月 24 日

    此更新包含以下更改:

    • 新的 YouTube Reporting API 可以检索包含频道或内容所有者的 YouTube 数据分析数据的批量数据报告。它专为可导入大型数据集并提供用于对数据进行过滤、排序和挖掘所用工具的应用而设计。

      每个 YouTube Reporting API 报告都包含一组预定义的维度和指标。(YouTube Analytics API 报告也使用指标和维度。)在报告中,每一行数据都有唯一的维度值组合。您可以根据维度值汇总多行数据,以计算各个视频、国家/地区、直播视频、订阅的用户等的指标。

      您可以使用 API 安排报告作业,每个作业用于标识 YouTube 应生成的报告。设置好任务后,YouTube 会生成可异步下载的每日报告。每个报告包含 24 小时内唯一数据。

    • 虽然是不同的 API,但 YouTube Analytics API 和 YouTube Reporting API 都允许开发者检索 YouTube 数据分析数据。由于两种 API 均提供对类似数据集的访问,因此我们将针对这两种 API 的文档将作为单个文档集进行发布。

      • 文档集的指南标签页包含这两个 API 的通用信息,包括有关如何向 API 请求授权的说明。
      • 批量报告标签页包含专门针对 YouTube Reporting API 的参考文档和其他内容。
      • 定向查询标签页包含专门针对 YouTube Analytics API 的参考文档和其他内容。
      • 示例标签页列出了这两种 API 中任意一个可用的代码示例。
      • 工具标签页列出了可供开发者实现这两种 API 中任一种 API 的其他资源。

    2015 年 8 月 20 日

    此更新包含以下更改:

    • 为使 API 更易于理解,我们调整了 API 文档的结构。因此,这些更改并不涉及新功能:

      • 现在,该文档包含两个页面:一个列出所有可用的频道报告,另一个列出所有可用的内容所有者报告。以前,这些文档针对频道视频报告、频道播放列表报告等分别提供了单独的页面。

      • 新的数据模型概览旨在更清晰地介绍该 API 的工作原理。具体而言,本文档试图更好地解释 YouTube 如何使用指标、维度和过滤条件计算报告值。

      • 现在,我们在单独记录了 API 的 reports.query 方法(可用于获取报告)。该网页上的信息以前在其他某些网页上。新页面旨在帮助您更轻松地识别检索报告时需要发送的信息。

    2015 年 7 月 22 日

    此更新包含多项更改,所有更改仅适用于内容所有者:

    • 新增的“adEarnings”指标涵盖了来自 Google 出售的所有广告来源的总估算收入(净收入)。这不是核心指标。对于已支持earnings指标的任何报告,该 API 都支持adEarnings指标。

      此外,“earnings”指标的定义已更正,以体现其值包括所有 Google 出售的广告来源以及来自非广告来源的总估算收入。以前,该定义错误地指出该指标仅包括来自广告来源的收入。

    • primaryAdGrossRevenue 指标已弃用。请改用 grossRevenue 指标来检索收入数据。

    • 除了已弃用的 primaryAdGrossRevenue 指标之外,广告效果报告不再支持 monetizedPlaybacksplaybackBasedCpm 指标。不过,一些视频报告仍支持这些指标。

    2015 年 6 月 1 日

    此更新包含以下更改:

    • 该 API 现在支持两个新的视频报告指标:videosAddedToPlaylistsvideosRemovedFromPlaylists。我们更新了频道内容所有者的视频报告列表,以确定支持这些新指标的报告。

      • videosAddedToPlaylists - 查询范围内视频添加到任何 YouTube 播放列表的次数。这些视频可能已添加到视频所有者的播放列表或其他频道的播放列表中。
      • videosRemovedFromPlaylists – 查询范围中的视频从所有 YouTube 播放列表中移除的次数。相关视频可能已从视频所有者的播放列表或其他频道的播放列表中移除。

      这两个指标都包含“稍后观看”播放列表之类的默认播放列表。但是,系统不会统计自动添加视频的播放列表,例如频道的上传视频播放列表或用户的观看记录。另请注意,这些指标反映的是添加和移除操作的绝对数量。因此,如果用户将视频添加到播放列表,然后移除,然后又重新添加,则该指标表示该视频已添加到两个播放列表,并从一个播放列表中移除。

      这些指标的数据自 2014 年 10 月 1 日起提供。

    2015 年 3 月 31 日

    此更新包含以下更改:

    2015 年 3 月 16 日

    此更新包含以下更改:

    • 新增的 currency 参数可让您以美元 (USD) 以外的货币检索收入指标。如果已设置该参数,则 API 会将 earningsgrossRevenueplaybackBasedCpmimpressionBasedCpm 指标的值转换为指定币种。返回的值是根据每天变化的汇率计算得出的估算值。

      此参数值是三个字母的 ISO 4217 货币代码。默认值为 USD。参数定义中列出了支持的货币代码。

    2015 年 2 月 25 日

    此更新包含以下更改:

    • API 现在支持创建和管理 YouTube 数据分析组,以及检索这些组的报告数据。

      • 创建和管理群组

        此更新引入了用于创建和管理群组的 groupgroupItem 资源。

        • group 资源代表一个 Analytics(分析)群组,即一个包含最多 200 个频道、视频、播放列表或资产的自定义集合。API 支持对此资源使用 listinsertupdatedelete 方法。
        • groupItem 资源表示 Google Analytics(分析)组中的项目。API 支持对此资源使用 listinsertdelete 方法。

        例如,您可以使用 groups.insert 方法创建一个组,然后使用 groupItems.insert 方法向该组添加项。

      • 检索群组的报告数据

        维度文档已更新,添加了 group 维度,该维度可用作许多频道报告内容所有者报告的过滤条件。当您使用 group 过滤条件时,API 会返回该组中所有项的数据。请注意,该 API 目前不支持为素材资源组创建报告。

      如需详细了解 YouTube 数据分析组,请访问 YouTube 帮助中心

    2015 年 2 月 13 日

    此更新包含以下更改:

    • API 不再支持 show 维度。

    2014 年 8 月 28 日

    此更新包含以下更改:

    • API 现在支持为 videoplaylistchannelshow 维度指定多个值(当这些维度用作过滤条件时)。如需指定多个值,请将 filters 参数值设为一个逗号分隔列表,其中包含应过滤其 API 响应的视频、播放列表、频道或节目 ID。此参数值最多可指定 200 个 ID。

      如果您为同一个过滤条件指定了多个值,则也可以将该过滤条件添加到您为请求指定的维度列表中。即使相应过滤条件未被列为特定报告支持的维度,情况也是如此。如果您将过滤条件添加到维度列表,则 API 还会使用过滤条件值对结果进行分组。

      如需详细了解此功能,请参阅 filters 参数定义。

    2014 年 7 月 16 日

    此更新包含以下更改:

    • 在检索渠道报告时,您现在可以通过将 ids 参数的值设置为 channel==MINE 来检索经过身份验证的用户的渠道的数据。(您还可以将 ids 参数设置为 channel==CHANNEL_ID 以检索指定渠道的数据。)

    • 现在,API 支持播放列表报告,其中包含与播放列表中的视频观看次数相关的统计信息。我们为频道内容所有者提供了播放列表报告。

      所有播放列表报告都支持 viewsestimatedMinutesWatched 指标,部分报告还支持 averageViewDuration 指标。

      此外,所有播放列表报告均支持以下新指标。请注意,这些指标仅反映网络上发生的播放列表观看次数。

      • playlistStarts:观看者开始播放播放列表的次数。
      • viewsPerPlaylistStart:每次播放列表启动时发生的平均视频观看次数。
      • averageTimeInPlaylist:观看者在播放列表启动后观看播放列表中的视频的估算平均时长(以分钟为单位)。

      任何检索播放列表报告的请求都必须使用 isCurated 过滤条件,该过滤条件必须设置为 1 (isCurated==1)。

    • 该 API 现在支持观众黏度报告。此报告用于衡量视频留住观众的能力。报告中新增的 elapsedVideoTimeRatio 维度会根据相应的指标值来衡量视频的已播放时长:

      • audienceWatchRatio 指标标识在视频的指定时间点观看视频的观看者的绝对比率。该比率的计算方式是将视频播放一部分的次数与视频的总观看次数进行比较。

        请注意,在一次视频观看过程中,视频的某一部分可能会被多次观看(或根本无法观看)。例如,如果用户快退并观看同一视频的同一部分,则该部分的绝对比率可能会大于 1

      • relativeRetentionPerformance指标显示的是,与所有时长相近的 YouTube 视频相比,某视频在播放期间留住观看者的能力如何。值为 0 表示此视频留住观看者的比率低于任何其他时长相近的视频,而值为 1 则表示此视频留住观看者的留存率优于任何其他时长相近的视频。中间值为 0.5 表示在时长相近的视频中,有一半的视频留住观看者的效果较好,而一半的视频留住观看者的效果较差。

      您还可以使用 audienceType 过滤条件,让报表仅返回与自然观看次数、TrueView 插播广告或 TrueView 展示广告带来的观看次数相关联的数据。(自然观看次数是用户操作(例如搜索视频或点击推荐视频)的直接结果。

    • 该 API 支持多个与注释相关的新指标。下列指标可通过之前支持 annotationClickThroughRateannotationCloseRate 指标的任何报告进行检索。

      所有新指标都是核心指标,受弃用政策约束。但请注意,新指标自 2013 年 7 月 16 日起才可供使用。(自 2012 年 6 月 10 日起,annotationClickThroughRateannotationCloseRate 指标数据可供使用。)

    • 不再将“GOOGLE_SEARCH”报告为“insightTrafficSourceType”维度的单独值。相反,来自 Google 搜索结果的引荐现在会归因于 EXT_URL 流量来源类型。因此,您也无法再检索将 insightTrafficSourceType 过滤条件设置为 GOOGLE_SEARCHinsightTrafficSourceDetail 报告。

    2014 年 1 月 31 日

    此更新包含以下更改:

    2014 年 1 月 16 日

    此更新包含以下更改:

    • 示例请求文档已经过重新设计,按照类别对示例进行分组,并使用与最近针对频道和内容所有者报告发布的标签格式类似的标签格式。在新设计中,示例分为以下几个类别:

      • 基本统计信息
      • 基于时间
      • 地理位置
      • 播放位置
      • 流量来源
      • 设备/操作系统
      • 受众特征
      • 社交媒体
      • 收入/广告(仅限内容所有者报告)

    • 示例请求文档现在添加了在频道报告或内容所有者报告中检索特定省级数据的新示例。

      • 美国各州和华盛顿特区的各省级指标:此报告会检索按省份统计的频道视频的观看次数明细和其他统计信息。数据涵盖美国各州和华盛顿特区。该示例不仅使用了 province 维度,还使用了 filters 参数来限定响应结果,使其仅包含针对美国的搜索结果。

      • 加利福尼亚州的观看者受众特征(年龄段和性别):此报告检索与加利福尼亚州观看频道的视频的观看者的年龄段和性别相关的统计信息;如果内容所有者报告的是内容所有者收到版权主张的内容,则此报告会检索这些观看者的统计信息。此示例使用 filters 参数来确保响应仅包含特定省份的数据。

    • province 维度的定义已更新,请注意,当 dimensions 参数值中包含 province 时,请求还必须将数据限制到美国,方法是在 filters 参数值中包含 country==US

    2014 年 1 月 6 日

    此更新包含以下更改:

    • 我们重新设计了列出受支持的频道内容所有者报告的文档。每个文档都会将报告分组为不同的类别,而不是列出所有可能的报告:

      • 基本统计信息
      • 基于时间
      • 地理位置
      • 播放位置
      • 流量来源
      • 设备/操作系统
      • 受众特征
      • 社交媒体
      • 热门视频

      每个文档都会以标签列表的形式显示这些类别,您可以点击任意标签来查看该类别中受支持的报告。

    • 该 API 现在支持三个新的地理位置维度:provincecontinentsubContinent

      • 利用 province 维度,您可以检索美国各州和哥伦比亚特区的统计信息。该 API 支持该维度的两种用途:

        • 该 API 支持按状态细分统计信息的两种报告。这两种报告均适用于频道内容所有者

          • 核心统计信息报告可提供几种统计信息,包括观看次数和估计观看时长。
          • 基于时间的报告提供相同的统计信息,但会每天、7 天、30 天或每月汇总数据。

        • 您可以使用 filters 查询参数限制报告,使其仅包含特定州的统计信息。有些报告支持这种类型的过滤,包括地理位置报告、播放位置报告、流量来源报告、设备报告、操作系统报告、受众特征报告和热门视频报告。

      • continent 维度用于指定用于标识大洲的联合国 (UN) 统计地区代码。此维度只能用作过滤条件

      • subContinent 维度可指定用于标识大洲次级区域的联合国 (UN) 统计区域代码。此维度只能用作过滤条件。

        由于每个子区域仅与一个大洲相关联,因此在使用 subContinent 过滤器时无需同时使用 continent 过滤器。(实际上,如果请求同时使用这两个维度,API 会返回错误)。

    • 更正了文档,使 insightTrafficSourceDetail 维度未将 insightTrafficSourceTypePROMOTED 添加为有效的过滤条件值。

    2013 年 9 月 30 日

    此更新包含以下更改:

    • YouTube Analytics API 现在需遵循服务条款中所述的弃用政策。不过,该 API 的非核心维度和非核心指标不受弃用政策的约束。维度metrics页面已更新,现在列出了核心维度和指标。此外,这些页面上的定义已更新,可明确指出核心维度和指标。

    • API 现在支持 EXTERNAL_APP 作为 insightPlaybackLocationType 维度的值。结合此更新,自 2013 年 9 月 10 日起,播放将不再归类为 MOBILE 播放次数,但在此日期之前发生的移动设备播放仍将按该值进行分类。

      经过此次更新,移动设备播放现在可分为 WATCHEMBEDDEDEXTERNAL_APP 播放,具体取决于发生播放的应用的类型。

    • API 现在支持 PLAYLIST 作为 insightTrafficSourceType 维度的值。该值表示视频观看次数源自播放列表。以前,应使用维度的 YT_OTHER_PAGE 类别对这些数据视图进行分类。

    2013 年 7 月 16 日

    此更新包含以下更改:

    • 该 API 现在支持按多个维度和指标对报告进行排序。示例请求文档包含一个新示例,即按多个维度/指标对请求进行排序,该示例演示了此功能。请求会检索流量来源数据,并且 sort 参数值为 day,-views。结果按时间顺序排列,但在每天的结果集中,第一行包含带来最多观看次数的流量来源的数据,第二行包含带来观看次数第二高的来源的数据,以此类推。

    • 该 API 现在支持 deviceTypeoperatingSystem 这两个新维度,这些维度可用于检索观看者通过何种设备观看您的视频的数据。该 API 支持使用其中一个维度或两个维度的报告。

      • 通过 deviceType 报告,您可以检索不同类型的设备(包括桌面设备、移动设备和平板电脑设备)的观看次数和估算观看时长。您还可以使用 operatingSystem 过滤器将设备类型报告限制为仅包含运行特定操作系统(例如 AndroidiOS)的设备的统计信息。

      • 通过 operatingSystem 报告,您可以检索不同操作系统(例如 Android、iOS、Linux 等)的观看次数和估算观看时长。您还可以使用 deviceType 过滤器将操作系统报告限制为仅包含特定类型的设备(如移动设备或平板电脑)的统计信息。

      新的设备类型报告和操作系统报告现已面向频道内容所有者推出。

    • 示例请求文档已更新,现在包括 3 个针对频道的设备报告和 3 个针对内容所有者的设备报告。

    • insightPlaybackLocationType”维度可能会返回值“YT_OTHER”,该值用于标识尚未使用此维度的某个其他值进行分类的数据视图。

    2013 年 5 月 23 日

    此更新包含以下更改:

    • 内容所有者报告文档已更新,以体现您可以按收入的降序对排名靠前的视频报告进行排序,找出收入最高的视频。此报告是用户活动和收入报告部分第二个表格中列出的第一个报告。

    2013 年 5 月 10 日

    此更新包含以下更改:

    2013 年 5 月 6 日

    此更新包含以下更改:

    • 该 API 现在支持检索观看时长指标(estimatedMinutesWatchedaverageViewDurationaverageViewPercentage)以及其他指标,包括观看指标、互动指标、收入指标和广告效果指标。

      我们更新了可用的频道报告内容所有者报告的列表,以反映这一变更。(由于观看时长指标可以作为其他所列报告的一部分进行检索,因此这些列表现在实际上有所缩短。)

      示例 API 请求文档也已更新。

    • 使用insightPlaybackLocationDetailinsightTrafficSourceDetail维度的报告在以下方面得到了增强:

      • 它们现在支持可选的 country 过滤器。

      • 内容所有者现在可以使用以下任一新的filter组合检索这些报告。请注意,所有这些组合也支持可选的 country 过滤器。

        • 播放位置详情

          • channel,insightPlaybackLocationType==EMBEDDED
          • show,insightPlaybackLocationType==EMBEDDED
          • claimedStatus,insightPlaybackLocationType==EMBEDDED
          • uploaderType,insightPlaybackLocationType==EMBEDDED
          • uploaderType,claimedStatus,insightPlaybackLocationType==EMBEDDED

        • 流量来源详情

          • channel,insightTrafficSourceType
          • show,insightTrafficSourceType
          • claimedStatus,insightTrafficSourceType
          • uploaderType,insightTrafficSourceType
          • uploaderType,claimedStatus,insightTrafficSourceType

    2013 年 5 月 3 日

    此更新包含以下更改:

    • 新的 API 请求示例文档中提供了相关示例,展示了如何使用 YouTube Analytics API 获取各种不同类型的报告。每个示例都包含请求所提取报告的简要说明,然后显示请求的维度、指标、过滤条件和排序参数。

    • insightTrafficSourceType 维度现在支持 SUBSCRIBER 作为有效值。此值用于标识源自 YouTube 首页的 Feed 或 YouTube 订阅功能的视频观看次数。如果您根据此流量来源进行过滤,insightTrafficSourceDetail字段将会指定首页 Feed 或从中引荐浏览的其他网页。

    2013 年 3 月 28 日

    此更新包含以下更改:

    2013 年 3 月 21 日

    此更新包含以下更改:

    • API 现在支持收入和广告效果指标,并支持新的广告效果报告。只有参与了 YouTube 合作伙伴计划的 YouTube 内容合作伙伴才能访问这些指标和报告。

      • 新支持的报告支持基于播放的广告效果指标和基于展示的广告效果指标。如需详细了解广告效果报告,请参阅内容所有者报告文档。

      • 下面列出了新增支持的指标。内容所有者报告列表已更新,以确定支持这些指标的报告(包括两种新报告)。

        • earnings – 来自 Google 出售的所有广告来源的总估算收入。
        • grossRevenue – 来自 Google 或 DoubleClick 合作伙伴的估算总收入。
        • primaryAdGrossRevenue - 来自 Google 或 DoubleClick 合作伙伴、针对报告涵盖的视频播放的主要广告类型的估算收入总和。
        • monetizedPlaybacks - 展示了至少一次广告展示的播放次数。
        • playbackBasedCpm - 每千次播放的估算总收入。
        • impressions - 经过验证的所投放广告的展示次数。
        • impressionBasedCpm - 每千次广告展示的估算总收入。

        注意:如需了解完整详情,请参阅指标定义

      • 任何检索收入或广告效果指标的请求都必须发送一个授权令牌,用于使用新的 https://www.googleapis.com/auth/yt-analytics-monetary.readonly 范围授予访问权限。

    • API 文档进行了重新整理,不同类型的报告分别放在不同的页面上。因此,我们现在为不同的页面分别介绍了不同类型的频道报告内容所有者报告

    2013 年 2 月 4 日

    此更新包含以下更改:

    • API 的参考指南现在有一个示例部分,其中包含的代码示例演示了如何使用 Java、JavaScript、Python 和 Ruby 客户端库调用 API。JavaScript 代码示例与示例应用文档中详细讨论的代码示例相同。

    2012 年 11 月 14 日

    此更新包含以下更改:

    • 现在,API 参考指南介绍了 APIs Explorer,您可以通过它来调用 API、查看 API 请求以及检索响应中的实际数据。

    • 该 API 支持多种适用于频道和内容所有者的新报告,具体如下所述。每种报告都可以生成频道报告内容所有者报告维度metrics页面也已进行相应更新。

      • 播放位置报告会指明不同类型的网页或应用上发生的视频观看次数。

      • 播放位置详情报告可找出为指定视频带来最多观看次数的嵌入式播放器。与播放位置报告相比,该工具可确定与表现最好的嵌入式播放器相关联的网址,从而提供更细致的视图。

      • 流量来源报告可以标识源自不同类型的引荐来源网址的视频观看次数。

      • 流量来源详情报告可标识为指定视频和特定流量来源类型带来最多观看次数的引荐来源网址。例如,您可以通过此报告了解为某个特定视频带来最多流量的相关视频。此报告支持多个流量来源

      • 观看时长报告提供了观看者观看您的内容的时间长度。报告可以汇总特定时间范围(一天、过去 7 天、过去 30 天等)或国家/地区的数据。如果报告按日期或国家/地区汇总数据,则还可以指定每次视频观看的平均时长,以及用户观看的每个视频的平均百分比。

    2012 年 10 月 2 日

    此更新包含以下更改:

    • YouTube Analytics API 现已面向所有开发者推出。您可以通过 APIs console 中的服务面板为项目激活 API,而无需先请求访问权限。

    • 新的使用入门部分概述了构建使用 YouTube Analytics API 的应用所需满足的前提条件和基本步骤。

    2012 年 9 月 12 日

    此更新包含以下更改:

    • 新的了解配额使用情况部分提供了有关如何优化 API 配额使用情况的指南。API 服务器会计算每个请求的查询费用,这笔费用会从您的 API 使用配额中扣除。由于不同类型的报告的查询费用可能相差很大,因此您应该计划高效地使用配额,并且您的应用应仅请求其实际需要的指标和数据。

    • 时间维度部分已更新,以说明这些维度会指明 Google Analytics(分析)报告应根据特定时间段来汇总数据。API 现在支持下列额外的时间维度:

      • 7DayTotals - 报告中的数据将会汇总在一起,因此每一行都包含七天的数据。
      • 30DayTotals - 报告中的数据将会汇总在一起,因此每一行都包含 30 天的数据。
      • month - 报告中的数据将按日历月汇总。

      同样,可用报告部分也进行了更新,以反映该 API 支持使用这些维度的报告。

    • 报告实体维度部分已作如下更新:用于检索内容所有者报告的 API 请求必须使用其中一个维度(videochannelshow)或受支持的 claimedStatusuploaderType 维度组合来过滤数据。

    • API 现在支持针对热门视频报告使用两种新的排序选项。这些报告以频道报告或内容所有者报告的形式提供,包含按国家/地区划分的指标(观看次数、评论数、赞的次数等),并会按视频对这些指标进行细分。现在,您可以根据在视频的观看页面上订阅或退订某个频道的用户数对这些报告进行排序。

    • 我们更新了 subscribersGainedsubscribersLost metrics的定义,以说明频道在多个位置(包括视频观看页面、频道页和 YouTube 首页上显示的导视)可能会增加或减少订阅者。当这些指标显示在视频专用报告中时,它们仅包含来自指定视频的观看页面的统计信息。