修订历史记录

本页面列出了 YouTube Data API (v3) 变更和文档更新。订阅此更新记录。订阅

2024 年 4 月 30 日

注意：这是弃用通知。

此更新包含以下更改：

该 API 不再支持插入或检索频道讨论的功能。这一变更与 YouTube 网站支持的功能一致，不支持向频道发布评论。

2024 年 3 月 13 日

注意：这是弃用通知。

此更新包含以下更改：

sync 参数的 captions.insert和 captions.update 方法 已弃用。YouTube 将不再支持 参数。

由于这一变化，开发者必须在插入或 否则上传将失败。

2024 年 3 月 12 日

此更新包含以下更改：

captions 资源的文档已更新，以指明 snippet.name 允许的长度上限 字段长度为 150 个字符。该 API 会返回 nameTooLong 错误。

2024 年 3 月 7 日

注意：这是弃用通知。

channel 资源属性 已废弃 brandingSettings.channel.moderateComments。YouTube 将停止运行 自 2024 年 3 月 7 日起支持此参数。

2024 年 1 月 31 日

此更新包含以下更改：

channels.list 方法的新 forHandle 参数，您可以通过指定频道的 YouTube 标识名来检索频道的相关信息。

2023 年 11 月 9 日

对 Comments 下 videoId 资源的所有引用 已移除，因为未使用 API 调用返回 videoId 资源。

2023 年 9 月 12 日

注意：这是弃用通知。

comments.markAsSpam 方法 该 API 已经被弃用了几年。此方法在 YouTube 上不受支持，并且是 也不再受 API 支持。

在所有引用 comments.markAsSpam 方法结合使用。

2023 年 8 月 22 日

search.list 方法现在支持 videoPaidProductPlacement 参数。你可以使用此参数对搜索结果进行过滤，以便只包含 创作者已标注了付费宣传内容。

2023 年 8 月 18 日

video 资源的定义 liveStreamingDetails.concurrentViewers 已更新为 YouTube 数据 API 返回的同时观看人数 与 YouTube 提供的已处理的、不含垃圾内容的同时观看人数不同 Google Analytics。通过 YouTube 帮助中心 提供了有关直播指标的更多信息。

2023 年 8 月 7 日

正如我们在 2023 年 6 月 12 日发布的公告所述， search.list 方法的 relatedToVideoId 参数已弃用。该参数不再 且对该参数的引用已从 API 文档中删除。

2023 年 6 月 28 日

thumbnails.set 方法现在支持 uploadRateLimitExceeded错误，表示频道上传的内容过多 缩略图，请稍后重试。

2023 年 6 月 12 日

注意：这是弃用通知。

search.list 方法的 relatedToVideoId 参数已废弃。YouTube 将不再支持 参数。

目前，search.list 方法的 文档。此参数将从 search.list 文档中完全移除 2023 年 8 月 7 日当天或之后。

此外，还有一个示例演示了如何检索相关视频 已从 API 实现指南中移除。

2022 年 8 月 22 日

更正了 video.statistics 的类型注释 从无符号长整型转换为字符串。

2022 年 8 月 5 日

YouTube 更改了字幕 ID 的生成方式，并且， 向所有字幕轨道分配新的字幕 ID。此更改可能不向后兼容 存储数据 caption_id 值（虽然它不会 影响不存储 caption_id 值。

从现在到 2022 年 12 月 1 日， captions.list, captions.update, captions.download和 captions.delete方法 同时支持新旧字幕轨道 ID。不过，在 2022 年 12 月 1 日当天或之后， 将停止支持旧的字幕轨道 ID。届时，调用上述任一 API 方法 将会导致 captionNotFound 个错误。

为了针对这项变更做好准备，您应计划完全替换存储的所有字幕轨道数据 至 2022 年 12 月 1 日。也就是说，对于任何存储了字幕轨道的视频 数据，则应删除当前存储的数据，然后调用 captions.list 方法检索 视频的当前字幕轨道集，并将数据存储在 API 响应中， 。

2022 年 7 月 12 日

YouTube API 服务的服务条款已更新。请 请参阅 YouTube API 服务的服务条款 - 修订 历史记录。

2022 年 4 月 27 日

videos.insert 方法说明已更新，以指明上传的视频的文件大小上限已从 128GB 提高到 256GB。

2022 年 4 月 8 日

subscriptions.list 方法的 myRecentSubscribers 和 mySubscribers 形参定义 两者都已更新，以指出 API 返回的最大订阅者数量可能会有限制。 此更改是对文档的更正，而不是 API 行为的更改。

2021 年 12 月 15 日

正如我们在 2021 年 11 月 18 日公布的那样， 使视频得到不喜欢的更改 会计入整个 YouTube 平台中的私有数据，则 video 资源的 statistics.dislikeCount 属性现已设为不公开。

您可以访问 YouTube 官方博客，详细了解此次变更。

2021 年 11 月 18 日

结合对 在整个 YouTube 平台上不公开对视频的“不喜欢”次数，则 video 资源的 statistics.dislikeCount 媒体资源将于 2021 年 12 月 13 日被设为不公开。这意味着 包含在来自 videos.list 端点的 API 响应中（如果 API 请求是 必须经过视频所有者身份验证。

videos.rate 端点不受影响 更改。

如果开发者不公开显示“踩”的次数，但仍需要“踩”的次数 API 客户端可申请列入豁免许可名单。如需申请豁免，您需要 必须完成此项 申请表。

您可以访问 YouTube 官方博客，详细了解此次变更。

2021 年 7 月 2 日

注意：这是弃用通知。

commentThreads.update 端点已弃用，不再受支持。 此端点重复了通过其他 API 端点提供的功能。相反，您可以 打电话给comments.update

方法 如果您的代码需要 commentThreads 资源，请对 commentThreads.list 方法。

2021 年 7 月 1 日

所有使用 YouTube API 服务的开发者都必须完成 API 合规性审核，才能获得超过 10,000 个单元的默认配额分配。迄今为止，合规性审核流程和额外配额单元分配申请都是由开发者填写并提交《YouTube API 服务 - 审核和配额扩展表单》完成的。

为了阐明这些流程，并更好地满足使用我们 API 服务的开发者的需求，我们将添加三种新表单和一份用于填写这些表单的指南：

  • 经过审核的开发者请求表单：已通过 API 合规性审核的开发者可以填写并提交这个较短的表单，以请求延长分配的配额。
  • 申诉表单：如果 API 项目未通过合规性审核（或配额增加单元申请遭拒），开发者可以填写并提交此表单。
  • 控制权变更表单：如果开发者或代表开发者运营 API 客户端的任何一方遇到与 API 项目相关的控制权变更（例如，通过股票买卖、合并或其他形式的公司交易），必须填写并提交此表单。这让 YouTube 的 API 团队能够更新我们的记录、审核新 API 项目用例的合规性，以及验证开发者当前的配额分配情况。

每份新表单都会告知我们您打算使用 YouTube 的 API，以便我们更好地为您提供帮助。

如需了解更多详情，请参阅全新的 API 合规性审核指南。

2021 年 5 月 12 日

注意：这是弃用通知。

此更新涉及以下 API 变更：

  • channel 资源的 contentDetails.relatedPlaylists.favorites 属性已弃用。我们已弃用 2016 年 4 月 28 日 历史记录条目。

    在此次更新之前，如果 API 客户端尝试 将视频添加到不存在的收藏播放列表中。以后，播放列表将不再 则 API 会返回错误。尝试修改收藏播放列表 也将被弃用（根据之前的公告）， 可能随时开始返回错误。

  • 以下 channel 资源 已弃用的属性。YouTube 工作室界面已不支持这些属性 以及 YouTube 上。因此，该 API 也不再支持这些方法。

    • brandingSettings.channel.defaultTab
    • brandingSettings.channel.featuredChannelsTitle
    • brandingSettings.channel.featuredChannelsUrls[]
    • brandingSettings.channel.profileColor
    • brandingSettings.channel.showBrowseView
    • brandingSettings.channel.showRelatedChannels

    所有属性均已从 channel 并且它们的定义已经从资源的 属性列表。此外，还有错误 已从方法专属文档中移除。

  • 以下 channelSection 资源 已弃用的属性。YouTube 工作室界面已不支持这些属性 以及 YouTube 上。因此，该 API 也不再支持这些方法。

    • snippet.style
    • snippet.defaultLanguage
    • snippet.localized.title
    • localizations
    • localizations.(key)
    • localizations.(key).title
    • targeting
    • targeting.languages[]
    • targeting.regions[]
    • targeting.countries[]

    在进行这项更改后，channelSection.list 方法的 hl 参数还具有 已弃用，因为其支持的功能不受支持。

    所有属性均已从 channelSection 并且它们的定义已经从资源的 属性列表。此外，还有错误 已从方法专属文档中移除。

  • 对于 channelSection 资源的 snippet.type 个媒体资源， 以下值已被弃用。YouTube 已不支持这些值 频道页也因此不再支持通过 API 访问这些功能。

    • likedPlaylists
    • likes
    • postedPlaylists
    • postedVideos
    • recentActivity
    • recentPosts

  • playlist 资源的 snippet.tags[] 属性已弃用。此属性已不受支持 因此，我们不再支持通过 API 上传。

2021 年 2 月 9 日

playlistItem 资源支持两个新属性：

2021 年 1 月 28 日

此更新包含以下更改：

  • playlistItems.delete、 playlistItems.insert, playlistItems.list, playlistItems.update, playlists.delete, playlists.list和 全部支持 playlists.update 方法 新的 playlistOperationUnsupported 错误。如果请求试图 执行特定播放列表不允许的操作。例如，用户不能 从他们上传的视频播放列表中删除视频，或删除播放列表本身。

    在所有情况下，此错误都会返回一个 400 HTTP 响应代码（错误请求）。

  • playlistItems.list 方法的 watchHistoryNotAccessible 和 watchLaterNotAccessible 个错误 已从文档中移除。而用户的“观看记录”和“稍后观看”列表的确 无法通过 API 访问，因此该 API 不会返回这些特定错误。

2020 年 10 月 15 日

我们在“开发者”部分 政策：

  • 新的第 III.E.4.i 条提供了以下 有关通过 YouTube 嵌入式播放器收集和发送的数据的其他信息。您 对您通过任何 YouTube 嵌入式播放器向我们发送的任何用户数据负责， 用户与播放器互动，表明播放意图。您可以限制分享的数据 将自动播放设置为 false，在用户与播放器互动之前与 YouTube 互动。
  • 新的第 III.E.4.j 条与 在将内容嵌入到您的网站之前，先检查该内容是否属于面向儿童的内容 (MFK) 状态； 。你有责任知道自己嵌入到 API 客户端中的视频何时制作完成。 并相应地处理从嵌入式播放器收集的数据。因此，您必须 先使用 YouTube Data API 服务检查内容的状态，然后再将这些内容嵌入你的 API 客户端通过任意 YouTube 嵌入式播放器播放。

新增的查找视频的面向儿童的内容的状态 指南介绍了如何使用 YouTube Data API 服务。

为了实现这些更改，我们还在 嵌入式播放器参数文档，介绍了 如果您启用了自动播放，则用户无需与播放器进行任何互动即可播放内容；播放 因此，数据收集和共享将在网页加载时进行。

2020 年 10 月 8 日

本次更新介绍了与 Responsible AI 相关的三项小更改 channel 资源：

  • snippet.thumbnails 对象用于标识频道缩略图，对于新创建的对象，此对象可能为空 渠道，最多可能需要一天时间才能填充完毕。
  • statistics.videoCount 属性仅反映频道的公开视频数，即使面向所有者。此行为 与 YouTube 网站上显示的数量一致。
  • 频道关键字，在 brandingSettings.channel.keywords 属性，如果它们超过允许的长度上限（500 个字符或），则可能会被截断 如果它们包含未转义的引号 (")，则会发生该错误。请注意，500 个字符的 限制并不是针对每个关键字的限制，而是对所有关键字的总长度的限制。 此行为与 YouTube 网站上的一致。

2020 年 9 月

注意：这是弃用通知。

此更新涉及以下 API 变更。所有变更将于以下日期或之后生效 2020 年 9 月 9 日，即本公告的发布日期。有鉴于此，开发者不应再 依赖于下列任何 API 功能。

  • 以下 API 资源、方法、参数和资源属性已弃用 并在本公告发布日期当天或之后停止处理： <ph type="x-smartling-placeholder">
      </ph>
    • 以下 channel 资源 属性： <ph type="x-smartling-placeholder">
        </ph>
      • statistics.commentCount 属性
      • brandingSettings.image 对象及其所有子属性
      • brandingSettings.hints 列表及其所有子属性
    • channels.list 方法的 categoryId 个过滤条件参数
    • guideCategories 资源 和guideCategories.list 方法
  • API 响应的 channels.list 方法否 不再包含 prevPageToken 属性（如果 API 请求将 managedByMe 参数 发送至 true。这项变更不会影响 prevPageToken 属性 并且不会影响channels.list nextPageToken 属性。
  • channel 资源的 contentDetails.relatedPlaylists.watchLater 和contentDetails.relatedPlaylists.watchHistory的属性 已于 2016 年 8 月 11 日弃用。通过 playlistItems.insert 方法和 playlistItems.delete 方法的支持情况 现已完全弃用，并且这两个属性已移除 。
  • channels.list 方法的 mySubscribers 参数，即 于 2013 年 7 月 30 日宣布弃用的功能已 已从文档中移除。使用 subscriptions.list 方法和 其 mySubscribers 参数，用于检索 身份验证的用户的频道。
  • channel 资源的 invideoPromotion 对象及其所有子级 这些媒体资源已在 2017 年 11 月 27 日）已从文档中移除。

2020 年 7 月 29 日

我们简化了收取 API 请求配额的流程，删除了额外的 与 part 参数关联的费用。此更新立即生效，我们将仅收取 所调用方法的基本费用。如需详细了解 配额此处.

这一变化的影响是，大多数 API 调用的配额费用略低一些，而 一些 API 调用的费用仍将保持不变。这项变更不会增加任何 API 的费用 调用。总体而言，可能的影响是分配的配额，如 Google Cloud 控制台将更进一步。

我们强烈建议所有开发者 针对客户的合规性审核 项目，以确保能持续访问 YouTube API 服务。

此修订历史记录条目最初于 2020 年 7 月 20 日发布。

2020 年 7 月 28 日

通过 videos.insert上传的所有视频 2020 年 7 月 28 日之后创建的未经验证的 API 项目中的端点将仅限于 以便进行私密观看模式要解除此限制，每个项目都必须 接受审核以验证 遵守 服务条款。

如果创作者使用未经验证的 API 客户端上传视频，则会收到一封电子邮件，说明 他们的视频被锁定为私享，并且可以通过聘请官方频道来避免这一限制 或审核的客户。

2020 年 7 月 28 日之前创建的 API 项目将 目前未受此更改影响。不过，我们强烈建议所有开发者 完成合规性审核 以确保他们可以继续访问 YouTube API 服务。

2020 年 7 月 21 日

[更新时间：2020 年 7 月 28 日。]此修订版本中引用的文档更新 历史记录条目已于 2020 年 7 月 28 日重新发布。

昨天，我们发布了与配额收费流程相关的文档更新。 不过，由于不可预见的情况，配额更改尚未生效。因此， 为保证准确性，文档已还原。为了避免混淆 说明更改的历史记录条目已删除，并会在不久的将来重新发布。

2020 年 7 月 7 日

注意：这是弃用通知。

videos.insert 方法的 autoLevels 和 stabilize 参数现已废弃， 参数已从文档中删除。这些参数的值会被忽略，且不会影响 新上传的视频的处理方式。

2020 年 6 月 15 日

新的遵守 YouTube 开发者 政策指南提供了相关指导和示例，旨在帮助您确保 API 客户端遵循 YouTube API 服务的特定部分 条款和 政策 (API TOS)。

本指南深入介绍了 YouTube 如何实施《API 服务条款》的某些方面，但 不会替换任何现有文档。该指南介绍了一些最常见的问题， 开发者在 API 合规性审核期间会提出的要求。我们希望这能简化您的功能开发工作。 来帮助您了解我们如何解读和执行政策。

2020 年 6 月 4 日

注意：这是对上一弃用公告的更新。

频道公告功能现已完全弃用。这项变更最初公布于 并已生效。因此， activities.insert 方法不是 受支持的应用， activities.list 方法不再返回频道公告。有关详情，请参阅 YouTube 帮助中心。

2020 年 4 月 17 日

注意：这是弃用通知。

YouTube 即将弃用频道公告功能。因此， activities.insert 方法将会 已弃用，activities.list 方法停止返回频道公告。这些更改将在 API 中于 或 2020 年 5 月 18 日之后有关详情，请参阅 YouTube 帮助中心。

2020 年 3 月 31 日

此更新包含以下更改：

  • 新资源和方法

    • 新的 member 资源代表 是 YouTube 频道的频道会员。成员需要定期为 并享受特别福利。例如，成员可以 创作者为聊天开启了会员专享模式。

      此资源会替换 sponsor 资源（相关介绍为 YouTube Live Streaming API 的一部分）。通过 sponsor 资源现已弃用，API 客户端应更新对 sponsors.list 方法，以使用 members.list 方法。

    • 全新 membershipsLevel 资源标识由授权 API 请求的创建者管理的价格水平。 membershipsLevels.list 方法检索创建者的所有会员级别的列表。

2020 年 1 月 10 日

该 API 现在支持识别面向儿童的内容，YouTube 将这种内容称为 “面向儿童的内容”详细了解 “面向儿童的内容”内容。

channel 和 video 资源支持两个新属性， 让内容创作者和观看者能够识别出面向儿童的内容：

  • 借助 selfDeclaredMadeForKids 属性，内容创作者可以指定 channel 或 视频属于面向儿童的内容。

    对于渠道，可以在调用 channels.update 方法。对于视频 可以在调用 videos.insert 或 videos.update 方法。

    请注意，此属性仅包含在包含 channel 或 video 资源（如果频道所有者授权了 API 请求）。
  • madeForKids 属性可让任何用户检索“面向儿童的内容”状态 某个频道或 视频。例如，状态可能是 取决于 selfDeclaredMadeForKids 属性的值。请参阅 如需了解详情，请访问 YouTube 帮助中心 了解有关为频道、视频或广播设置观众群的信息。

我们还更新了 YouTube API 服务的服务条款和开发者政策。请 请参阅 YouTube API 服务的服务条款 - 修订 历史记录。YouTube API 服务的《服务条款》和 开发者政策将于 2020 年 1 月 10 日（太平洋时间）生效。

2019 年 9 月 10 日

API 参考文档已更新，以反映订阅者 计数会计入 YouTube 上，因此也会在 API 响应中显示。受此更改影响 YouTube Data API 服务返回的订阅人数会四舍五入为三显著 以及订阅人数超过 1000 时的相关数据。这项变更会影响 channel 个资源的 statistics.subscriberCount 属性。

注意：即使在用户 发送经授权的请求，索取有关自己频道的数据。频道所有者仍能看到 YouTube 工作室中的订阅人数。

例如，如果一个频道拥有 123,456 位订阅者， statistics.subscriberCount 属性将包含值 123000。 下表中的示例展示了 API 响应中订阅人数的四舍五入和 缩写词在其他公开显示的 YouTube 界面中：

订阅人数示例 YouTube Data API 公开显示的 YouTube 界面
1,234,000 1230 1230
12,345 12300 1.23 万
123,456,000 123000 12.3 万
1,234,567,000 1230000 123 万
12,345,678 12300000 1230 万
123,456,789 123000000 1.23 亿

2019 年 4 月 4 日

此更新包含以下更改：

  • API 参考文档已更新，以更好地解释每种方法的常见用例，并通过 API Explorer 微件提供动态的高质量代码示例。如需查看示例，请参阅 channels.list 方法的文档。现在，描述 API 方法的页面上有两个新元素：

    • 利用 API Explorer 微件，您可以选择授权范围，输入示例参数和属性值，然后发送实际的 API 请求并查看实际的 API 响应。该微件还提供显示完整代码示例的全屏视图，该示例会动态更新以使用您输入的范围和值。

    • 常见用例部分介绍了本页所介绍方法的一个或多个常见用例。例如，您可以调用 channels.list 方法来检索有关特定频道的数据，或者检索有关当前用户频道的数据。

      您可以使用该部分中的链接，以适用于您的用例的示例值填充 API Explorer，或打开已填充这些值的全屏 API Explorer。这些变更旨在让您更轻松地查看直接适用于您尝试在自己的应用中实现的用例的代码示例。

    目前支持 Java、JavaScript、PHP、Python 和 curl 的代码示例。

  • 代码示例工具也已更新，添加了一个新界面，该界面提供上述所有功能。使用该工具，您可以探索不同方法的用例，将值加载到 API Explorer 中，并打开全屏 API Explorer，以获取 Java、JavaScript、PHP 和 Python 的代码示例。

    由于这项变更，之前列出的适用于 Java、JavaScript、PHP 和 Python 的代码示例页面已被移除。

  • 我们更新了 Java、JavaScript、PHP 和 Python 的快速入门指南。修订后的指南介绍了如何使用 APIs Explorer 中的代码示例运行一个使用 API 密钥的示例和另一个使用 OAuth 2.0 客户端 ID 的示例。

请注意，上述更改取代了一个交互式工具，该工具于 2017 年添加到该 API 文档中。

2018 年 7 月 9 日

此更新包含以下更改：

  • channel 资源的 snippet.thumbnails 属性的定义已更新，以指明在应用中显示缩略图时，代码应使用与 API 响应中返回的图片网址完全相同的网址。例如，在 API 响应中返回的网址中，您的应用不应使用 http 网域，而不应使用 https 网域。

    从 2018 年 7 月开始，频道缩略图网址只能在 https 网域中使用，这也是这些网址在 API 响应中的显示方式。此时间过后，如果应用尝试从 http 网域加载 YouTube 图片，您可能会看到损坏的图片。

  • 注意：这是弃用通知。

    video 资源的 recordingDetails.location.altitude 属性已弃用。我们无法保证视频会返回此属性的值。同样，即使 API 请求尝试设置该属性的值，系统也可能不会存储传入的数据。

2018 年 6 月 22 日

实现指南（以前称为 实施和迁移指南已更新，从 v2 API 升级到 v3 API。此外，我们还删除了 例如收藏的视频。

2017 年 11 月 27 日

此更新包含以下更改：

  • 注意：这是弃用通知。

    YouTube 即将停止支持精选视频和精选网站功能，这两项功能在 API 中通过 channel 资源的 invideoPromotion 对象得到支持。因此，该对象及其所有子属性将被弃用。

    在 2017 年 12 月 14 日之前，您仍然可以检索和设置 invideoPromotion 数据。在付款日期后：

    • 如果在调用 channels.list 时尝试检索 invideoPromotion 部分，系统将返回一个空的 invideoPromotion 或根本不会返回任何 invideoPromotion 数据。
    • 如果尝试在调用 channels.update 时更新 invideoPromotion 数据，则至少在 2018 年 5 月 27 日之前将会返回成功响应，但它们将被视为空操作，这意味着它们实际上不会执行更新。

    2018 年 5 月 27 日之后，这些请求可能会返回错误消息，以指明 invalidPromotion 是无效部分。

2017 年 11 月 16 日

此更新包含以下更改：

  • 交互式代码段工具现在支持 Node.js 代码示例。此外，在几乎所有 API 方法（例如 channels.list 方法）的文档中，您也可以查看这些示例。

    可自定义的示例旨在为您提供特定于用例的 Node.js 应用的起点。该功能类似于 Node.js 快速入门指南中的代码。不过，这些示例确实包含快速入门中未包含的一些实用函数：

    • removeEmptyParameters 函数会获取与 API 请求参数对应的键值对列表，并移除不含值的参数。
    • createResource 函数接受与 API 资源中的属性相对应的键值对列表。然后，它会将属性转换为可在 insert 和 update 操作中使用的 JSON 对象。以下示例展示了一组属性名称和值，以及代码为它们创建的 JSON 对象： 
      # Key-value pairs:
{'id': 'ABC123',
 'snippet.title': 'Resource title',
 'snippet.description': 'Resource description',
 'status.privacyStatus': 'private'}

# JSON object:
{
 'id': 'ABC123',
 'snippet': {
   'title': 'Resource title',
   'description': 'Resource description',
 },
 'status': {
   'privacyStatus': 'private'
 }
}

    所有这些示例都旨在下载和在本地运行。如需了解详情，请参阅代码段工具说明中在本地运行完整代码示例的前提条件。

2017 年 10 月 25 日

此更新包含以下更改：

  • 交互式代码段工具中的 Python 代码示例已更新为使用 google-auth 和 google-auth-oauthlib 库，而不是 oauth2client 库，后者现已废弃。

    除了这项更改之外，该工具现在还提供已安装的 Python 应用和 Python 网络服务器应用的完整代码示例，它们使用的授权流程略有不同。如需查看完整示例（以及此变更），请执行以下操作：

    1. 转到交互式代码段工具或任意 API 方法（例如 channels.list 方法）的文档。
    2. 点击代码示例上方的 Python 标签页。
    3. 点击标签页上方的切换开关，可从查看摘要切换为查看完整示例。
    4. 该标签页现在应显示使用 InstalledAppFlow 授权流程的完整代码示例。该示例上面的描述对此进行了解释，并且还提供了一个 Web 服务器应用示例的链接。
    5. 点击链接可切换到网络服务器示例。该示例使用 Flask Web 应用框架和不同的授权流程。

    所有这些示例都旨在下载和在本地运行。如果您想运行示例，请参阅代码段工具说明中有关在本地运行完整代码示例的说明。

2017 年 8 月 29 日

此更新包含以下更改：

  • search.list 方法的 forContentOwner 参数的定义已更新，以指明该参数设置为 true 时，type 参数必须设置为 video。
  • search.list 方法的 regionCode 参数的定义已更新，明确指出该参数会将搜索结果限制为可在指定地区观看的视频。
  • YouTube 更新了品牌徽标和图标。新增“使用 YouTube 开发”您可以从品牌推广指南页面下载徽标。该页面还会显示其他新的 YouTube 徽标和图标，您可以从 YouTube 品牌网站下载这些徽标和图标。

2017 年 7 月 24 日

此更新包含以下更改：

  • 我们新推出了适用于 iOS 的 YouTube Data API 快速入门指南。本指南介绍如何在以 Objective-C 或 Swift 编写的简单 iOS 应用程序中使用 YouTube 数据 API。
  • 现在，YouTube Data API 的交互式代码段工具包含介绍该工具部分功能的文档： <ph type="x-smartling-placeholder">
      </ph>
    • 执行 API 请求
    • 在代码段和完整代码示例之间切换
    • 使用样板函数
    • 加载现有资源（适用于更新方法）

    注意：该工具也嵌入在 API 方法的 API 参考文档（示例）中。

2017 年 6 月 1 日

此更新包含以下更改：

2017 年 5 月 17 日

此更新包含以下更改：

  • API 参考文档已更新，使代码段更普遍且更具互动性。介绍 API 方法的页面（例如 channels.list 或 videos.rate）现在包含一个交互式工具，让您可以查看和自定义 Java、JavaScript、PHP、Python、Ruby、Apps 脚本和 Go 中的代码段。

    对于任何给定的方法，该工具会显示一个或多个用例的代码段，并且每个用例都会描述调用该方法的常用方法。例如，您可以调用 channels.list 方法来检索有关特定频道或当前用户频道的数据。

    您还可以与代码示例进行交互：

    • 修改参数和属性值，并且代码段会动态更新以反映您提供的值。

    • 在代码段和完整示例之间切换。代码段显示了调用 API 方法的代码部分。完整示例包含该代码段以及用于授权和发送请求的样板代码。您可以从命令行或本地网络服务器复制并运行完整示例。

    • 点击按钮执行请求。（若要执行请求，您需要授权该工具代表您调用该 API。）

    请注意，此工具已取代推出此工具的网页上的 APIs Explorer。（每个页面都会显示一个链接，因此您还可以选择在 API Explorer 中加载正在处理的请求。）

  • Data API 代码段工具也已更新，采用的新界面提供了上述所有功能。此页面上提供的主要新功能包括：

    • 支持写入数据的 API 请求。
    • 支持 Java 示例。
    • 更灵活、更全面的样板代码，用于向用户授权和构建 API 请求。

2017 年 4 月 27 日

此更新包含以下更改：

2017 年 3 月 30 日

此更新包含以下更改：

  • channel 资源的新 topicDetails.topicCategories[] 属性包含描述频道内容的维基百科网址列表。这些网址与资源的 topicDetails.topicIds[] 属性中返回的主题 ID 相对应。
  • playlistItem 资源的新 contentDetails.videoPublishedAt 属性用于标识视频发布到 YouTube 的时间。该资源已包含 snippet.publishedAt 属性，该属性用于标识向播放列表添加项的时间。
  • 与 channel 资源一样，video 资源现在会返回 topicDetails.topicCategories[] 属性，其中包含描述视频内容的维基百科网址列表。对于 video 资源，网址对应于资源的 topicDetails.relevantTopicIds[] 属性中返回的主题 ID。
  • video 资源的新 contentDetails.contentRating.mpaatRating 属性用于标识美国电影协会对电影预告片或预览的分级。

2017 年 2 月 27 日

正如最初在 2016 年 8 月 11 日宣布的一样，YouTube 已将支持的主题 ID 列表改为精选列表。channel 和 video 资源的 topicDetails 属性以及 search.list 方法的 topicId 参数中都包含了受支持主题 ID 的完整列表。

请注意，精选列表有多项更改：

  • 已将以下主题添加为“Society”的子主题：
    名称主题 ID
    企业/m/09s1f
    健康/m/0kt51
    军事/m/01h6rj
    政治/m/05qt0
    宗教/m/06bvp
  • Animated cartoon 主题（以前是 Entertainment 的子级）已被移除。
  • Children's music 主题（以前是 Music 的子级）已被移除。

由于此更改，与视频相关的主题现在始终在 video 资源的 topicDetails.relevantTopicIds[] 属性值中返回。

2016 年 11 月 29 日

此更新包含以下更改：

  • 从 2017 年 2 月 10 日起，我们将对主题 ID 列表进行以下三项细微更改：

    • Professional wrestling 类别（以前是 Sports 类别的子项）现在是 Entertainment 的子项。
    • TV shows 类别是 Entertainment 的子类别，是新的类别。
    • Health 类别（以前是 Lifestyle 的子类别）已被移除。

    另请注意，这里还有几个父类别（Entertainment、Gaming、Lifestyle、Music 和 Sports）。与子类别（如 Tennis）关联的所有视频也会与父类别 (Sports) 相关联。

2016 年 11 月 10 日

此更新包含以下更改：

  • 正如 2016 年 8 月 11 日首次公布的那样，要弃用 Freebase 和 Freebase API，您需要对主题 ID 进行一些更改。主题 ID 用于标识与 channel 和 video 资源相关联的主题，您还可以使用 topicId 搜索参数查找与特定主题相关的频道或视频。

    从 2017 年 2 月 10 日起，YouTube 将开始返回一小部分主题 ID，而不是目前为止所返回更为细化的那组 ID。另请注意，我们不保证频道和视频会与任何主题相关联，这与当前的 API 行为一致。

    为了让您的 API 客户端为这些更改做好准备，以下 API 参数和属性的定义已更新，以列出在上述时间过后受支持的主题 ID。请注意，所有房源的类别列表都是相同的。

  • 注意：这是弃用通知。

    以下属性即将弃用：

    • channel 资源的 topicDetails.topicIds[] 属性。此媒体资源将不再受支持，直到 2017 年 11 月 10 日。
    • video 资源的 topicDetails.relevantTopicIds[] 属性。此媒体资源将不再受支持，直到 2017 年 11 月 10 日。
    • video 资源的 topicDetails.topicIds[] 属性。2017 年 2 月 10 日之后，此属性将不再包含值。（在该日期之后，topicDetails.relevantTopicIds[] 属性值将标识与视频相关联的所有主题。）

  • 由于 Freebase 已弃用，因此我们从文档中移除了使用 Freebase 主题进行搜索指南。该指南提供了代码示例，展示应用如何使用 Freebase API。

    此外，search.list 方法的文档中移除了多个与主题 ID 相关的代码示例。

2016 年 11 月 2 日

此更新包含以下更改：

  • 新的属性和参数

    • video 资源包含几个新属性：

      • player.embedHtml 属性包含一个 <iframe> 标记，您可以使用该标记嵌入用于播放视频的播放器。新的 player.embedHeight 和 player.embedWidth 属性用于标识嵌入式播放器的尺寸。仅当 API 请求为 maxHeight 或 maxWidth 参数中至少一个指定值时，系统才会返回这些属性。这两个新参数稍后会在此修订历史记录条目中进行说明。

      • 新的 hasCustomThumbnail 属性用于指明视频上传者是否已为视频提供了自定义缩略图。请注意，只有视频上传者才能看到此属性。

      • 新的 fpbRatingReasons[] 会指明视频获得 FPB（南非）分级的原因。

      • 新的 mcstRating 用于标识视频在越南获得的分级。

    • videos.list 方法支持两个新参数：maxHeight 和 maxWidth。在检索 video 资源中的 player 部分时，您可以使用形参之一或同时使用这两个形参。

      默认情况下，player.embedHtml 属性中返回的 <iframe> 的高度为 360 像素。调整宽度以匹配视频的宽高比，从而确保嵌入式播放器不会为视频加框。例如，如果视频的宽高比为 16:9，则播放器的宽度将为 640 像素。

      借助这些新参数，您可以指定嵌入代码使用适合应用布局的高度和/或宽度，而不是使用默认尺寸。API 服务器会根据需要调整播放器尺寸，以确保嵌入式播放器不会对视频进行边框。请注意，这两个参数都指定了嵌入式播放器的最大尺寸。因此，如果同时指定了两个参数，则其中一个维度仍可能会小于该维度允许的上限。

      例如，假设视频的宽高比为 16:9。因此，如果未设置 maxHeight 或 maxWidth 参数，player.embedHtml 代码将包含 640x360 播放器。

      • 如果 maxHeight 参数设为 720，且未设置 maxWidth 参数，该 API 会返回 1280x720 播放器。
      • 如果 maxWidth 参数设为 960，且未设置 maxHeight 参数，该 API 会返回 960x540 播放器。
      • 如果 maxWidth 参数设为 960，且 maxHeight 参数设为 450，该 API 会返回 800x450 播放器。

      新的 player.embedHeight 和 player.embedWidth 属性（如上所述）用于标识播放器的尺寸。

  • 现有方法、属性和参数的更新

    • 我们更新了 channelSection 资源说明，以指明在未设置定位数据的情况下，一个频道最多可以创建 10 个频道架（包含定位数据）。

      此外，channelSection 资源的 targeting 属性也已更新，以体现只能使用 API 设置定位选项。如果使用 YouTube 网站上的界面修改了频道版块，则会删除定位选项。

    • 更正了 i18nLanguage 资源的 snippet.name 属性的定义，现在该值表示以 i18nLanguage.list 方法的 hl 参数指定的语言编写的语言名称。

    • playlistItem 资源的 contentDetails.note 属性已更新，以指明属性值的最大长度为 280 个字符。

    • playlistItem 资源的 contentDetails.startAt 和 contentDetails.endAt 属性已弃用。如果在 playlistItems.insert 或 playlistItems.update 请求中设置了这些字段，则它们会被忽略。

    • playlistItems.delete 和 playlistItems.update 方法现在支持 onBehalfOfContentOwner 参数，其他一些方法也已支持该参数。使用该方法的请求还需要使用令牌进行授权，该令牌可提供对 https://www.googleapis.com/auth/youtubepartner 范围的访问权限。

    • search.list 方法的 publishedBefore 和 publishedAfter 参数都已更新，以指明参数值包含边界值。因此，例如，如果设置了 publishedBefore 参数，则 API 会返回在指定时间或指定时间之前创建的资源。

    • video 资源的 contentDetails.contentRating.grfilmRating 属性支持另外三个值：grfilmK12、grfilmK15 和 grfilmK18。

    • videos.insert 方法说明已更新，以指明上传的视频的文件大小上限已从 64GB 提高到 128GB。

  • 新错误和更新后的错误

    • 该 API 支持以下新错误：

      错误类型 错误详情 说明
      forbidden (403) homeParameterDeprecated activities.list 方法返回此错误，表明此 API 无法获取用户的首页活动数据。如果您在未经授权的请求中将 home 参数设置为 true，则可能会发生此错误。
      invalidValue (400) invalidContentDetails playlistItems.insert 方法返回此错误来指明请求中的 contentDetails 对象无效。出现此错误的一个原因是 contentDetails.note 字段超出了 280 个字符。
      forbidden (403) watchHistoryNotAccessible playlistItems.list 方法会返回此错误，表示相应请求尝试检索“观看记录”但这些项目无法通过 API 检索到。
      forbidden (403) watchLaterNotAccessible playlistItems.list 方法返回此错误，表示相应请求尝试检索“稍后观看”但这些项目无法通过 API 检索到。
      badRequest (400) uploadLimitExceeded videos.insert 方法会返回此错误，以指明该频道已超过其可以上传的视频数量。
      forbidden (403) forbiddenEmbedSetting videos.update 方法会返回此错误，以表明该 API 请求试图为视频设置无效的嵌入设置。请注意，某些频道可能无权为直播提供嵌入式播放器。如需了解详情，请访问 YouTube 帮助中心。

    • 如果您在播放列表中插入重复的视频，playlistItems.insert 方法将不再返回错误。之前，某些播放列表（如收藏的视频）不允许重复，但不再受支持。一般来说，播放列表允许出现重复的视频。

  • 其他更新

    • 我们更新了 2016 年 9 月 15 日的修订历史记录条目，以明确说明：每当响应中包含 channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性时，它们始终分别包含 HL 和 WL 值。此外，只有在授权用户检索有关用户自己频道的数据时，才会包含这些属性。

2016 年 9 月 15 日

此更新包含以下更改：

  • 2016 年 8 月 11 日修订历史记录更新讨论了与主题 ID 相关的几项更改，其中包括支持的主题 ID 集将于 2017 年 2 月 10 日起发生变化。我们将在 2016 年 11 月 10 日前发布受支持的主题列表。

  • 以下更改现已生效。我们在 2016 年 8 月 11 日的修订历史记录更新中提供了以下变更通知：

    • 如果在调用 activities.list 方法时将 home 参数设置为 true，则 API 响应现在包含的内容与未登录的 YouTube 用户在首页上看到的内容类似。

      此次细微更改旨在提供比 2016 年 8 月 11 日修订历史记录更新中所描述的行为更好的用户体验。该更新已声明使用 home 参数的请求将返回空列表。

    • channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性现在分别包含所有频道的 HL 和 WL 值。

      需要说明的是，只有获得授权且检索用户自己频道相关数据的用户才能看到这些属性。这些属性始终包含值 HL 和 WL，即使授权用户检索有关用户自己频道的数据也是如此。因此，您无法通过该 API 检索观看记录和“稍后观看”播放列表 ID。

      此外，检索频道观看记录或“稍后观看”播放列表的播放列表详情 (playlists.list) 或播放列表内容 (playlistItems.list) 的请求现在会返回空列表。此行为适用于新值 HL 和 WL，以及您的 API 客户端可能已存储的任何观看记录或“稍后观看”播放列表 ID。

  • 系统不再返回 video 资源的 fileDetails.recordingLocation 对象及其子属性。以前，此类数据（例如父级 fileDetails 对象）只能由视频所有者检索。

2016 年 8 月 11 日

此更新包含以下更改：

  • 新发布的《YouTube API 服务的服务条款》（简称“更新后的条款”）在 YouTube 工程和开发者博客中进行了详细讨论，提供了大量对现行《服务条款》的更新。除了更新后的条款（将于 2017 年 2 月 10 日生效）之外，此次更新还包含一些支持文档，以帮助解释开发者必须遵守的政策。

    如需了解完整的新文档，请参阅更新后的条款的修订历史记录。此外，将来对更新条款或支持文档进行的更改也会在修订历史记录中说明。您可以通过 RSS Feed 中的链接订阅修订历史记录中列有更改的内容。

  • Freebase 和 Freebase API 的弃用导致与主题 ID 相关的几项变更。主题 ID 用于以下 API 资源和方法：

    • channel 资源的 topicDetails 部分用于标识与频道关联的主题。
    • video 资源的 topicDetails 部分用于标识与视频相关的主题。
    • 借助 search.list 方法的 topicId 参数，您可以搜索与特定主题相关的视频或频道。

    这些功能的变化如下：

    • 从 2017 年 2 月 10 日起，YouTube 将开始返回一小部分主题 ID，而不是目前为止所返回更为细化的那组 ID。这组受支持的主题将用于标识体育或篮球等高级分类，但是无法识别具体的球队或球员。我们将公布一系列受支持的主题，以便您有充足的时间针对此次变更准备申请。

    • 在 2017 年 2 月 10 日之前，您已检索到的任何 Freebase 主题 ID 都可用于搜索内容。但此后，您将只能使用上一项中确定的一小部分主题来按主题检索搜索结果。

    • 在 2017 年 2 月 10 日之后，如果您尝试使用未属于支持的小型主题 ID 集的主题 ID 来搜索结果，API 将返回空的结果集。

  • 以下 API 字段和参数将于 2016 年 9 月 12 日弃用：

    • activities.list 方法的 home 参数可让授权用户检索将在 YouTube 首页上为该用户显示的活动 Feed。在 2016 年 9 月 12 日之后使用此参数的请求将返回空列表。

    • channel 资源的 contentDetails.relatedPlaylists.watchHistory 和 contentDetails.relatedPlaylists.watchLater 属性仅对检索用户自己频道相关数据的授权用户可见。2016 年 9 月 12 日之后，对于所有渠道，contentDetails.relatedPlaylists.watchHistory 将返回值 HL，contentDetails.relatedPlaylists.watchLater 属性将返回值 WL。

      2016 年 9 月 12 日之后，如果请求检索频道观看记录或“稍后观看”播放列表的播放列表详情 (playlists.list)，则会返回空列表。在该时间过后，检索其中任何一个播放列表中播放列表项 (playlistItems.list) 的请求也将返回一个空列表。这适用于新值 HL 和 WL，以及您的 API 客户端可能已存储的任何观看记录或“稍后观看”播放列表 ID。

    • 2016 年 9 月 12 日之后，系统将不再返回 video 资源的 fileDetails.recordingLocation 对象或其任何子属性。此数据只能由视频所有者检索，因为父级 fileDetails 对象只能由视频所有者检索。

2016 年 6 月 13 日

此更新包含以下更改：

  • channel 资源的 contentDetails.googlePlusUserId 属性已弃用。以前，仅当频道与 Google+ 个人资料相关联时，此属性才会显示。弃用后，该属性将不再包含在任何 channel 资源中。

  • comment 资源的 snippet.authorGoogleplusProfileUrl 属性已弃用。以前，仅当频道与 Google+ 个人资料相关联时，此属性才会显示。弃用后，该属性将不再包含在任何 comment 资源中。

由于弃用后这两个属性都不会返回，因此已从相应的资源文档中移除这两个属性。

2016 年 5 月 31 日

此更新包含以下更改：

  • subscriptions.list 方法的新 myRecentSubscribers 参数会检索已通过身份验证的用户的频道订阅者列表，此列表按照用户订阅频道的时间逆序排列。

    请注意，新参数仅支持检索已验证用户频道的最近 1000 位订阅者。如需检索完整的订阅者列表，请使用 mySubscribers 参数。该参数不会按特定顺序返回订阅者，也不会限制可以检索到的订阅者的数量。

  • 针对 activity、playlistItem、playlist、search result、缩略图和视频资源更新了 snippet.thumbnails.(key) 属性的定义，请注意，某些视频可以使用额外的缩略图图片大小。

    • standard 图片宽 640 像素，高 480 像素。
    • maxres 图片宽 1280 像素，高 720 像素。

  • channelSection.list 方法的 part 参数的定义已更新，以指明 targeting 部分需要支付 2 个配额单元才能检索。

  • 现在，如果未正确授权的请求尝试检索 video 资源的 fileDetails、processingDetails 或 suggestions 部分，videos.list 方法会返回 forbidden (403) 错误。这些部分仅供视频所有者使用。

2016 年 5 月 17 日

新的 Data API 代码段工具可为常见的 YouTube Data API 用例提供简短的代码段。代码段目前适用于 Apps Script、Go、JavaScript、PHP、Python 和 Ruby 中的所有只读 API 方法。

对于每种方法，该工具都会显示一个或多个用例的代码示例。例如，它为 search.list 方法提供了五个代码段：

  • 按关键字列出视频
  • 按位置列出视频
  • 列出直播活动
  • 搜索经过身份验证的用户的视频
  • 列出相关视频

对于每个用例，该工具都会显示 API 请求中使用的参数。您可以修改参数值，在这种情况下，该工具会更新代码段，以反映您提供的参数值。

最后，该工具会显示每个请求的 API 响应。如果您修改了请求参数，则 API 响应将基于您提供的参数值。请注意，您需要授权该工具代表您提交请求，以显示 API 响应。

2016 年 4 月 28 日

此更新包含以下更改：

  • video 资源的新 contentDetails.projection 属性用于指定视频的投影格式。有效的属性值为 360 和 rectangular。

  • 我们更新了 video 资源的 recordingDetails.location 和 fileDetails.recordingLocation 属性，以说明这两个属性之间的区别：

    • recordingDetails.location 属性用于标识视频所有者希望与视频关联的位置。此位置可修改、可在公开视频中搜索；对于公开视频，此位置可能会向用户显示。
    • fileDetails.recordingLocation 属性值不可变，表示与上传的原始视频文件相关联的位置。该值仅对视频所有者可见。

  • channel 资源的 contentDetails.relatedPlaylists.favorites 属性的定义已更新，以指明该属性值可能包含引用空播放列表且无法提取的播放列表 ID。这是因为收藏视频功能已被弃用。请注意，此属性不受 API 弃用政策的约束。

  • ineligibleAccount 错误（可由 comments.insert、comments.update、commentThreads.insert 或 commentThreads.update 方法返回）的定义已更新，指出如果用于授权 API 请求的 YouTube 账号尚未与用户的 Google 账号合并，就会发生此错误。

2016 年 4 月 20 日

此更新包含以下更改：

  • channels.update 方法的 part 参数的定义已更新，以指明 localizations 也是该参数的有效值。

  • 入门指南的配额使用情况部分已更新为链接到 Google Developers Console，您可以在其中查看自己的实际配额和配额使用情况。

2016 年 3 月 16 日

此更新包含以下更改：

  • 现有资源和方法的更新

    • channelBanner 资源文档已更新，以指明上传的频道横幅图片的建议大小为 2560x1440 像素。最小尺寸（2048 x 1152 像素）没有更改。

    • channel 资源的新 snippet.customUrl 属性用于标识与频道关联的自定义网址。（并非所有频道都有自定义网址）。YouTube 帮助中心介绍了获取自定义网址的资格要求以及如何设置自定义网址。

    • channel 资源的 brandingSettings.watch 对象及其所有子属性都已被弃用。

    • 对 search.list 请求的 API 响应现在包含一个 regionCode 属性。该属性标识搜索查询所用的地区代码。地区代码指示 API 返回指定国家/地区的搜索结果。

      属性值是用于标识区域的两个字母的 ISO 国家/地区代码。i18nRegions.list 方法会返回受支持区域的列表。默认值为 US。如果指定的区域不受支持，YouTube 可能仍会选择其他区域（而不是默认值）来处理查询。

    • 更新了 videoAbuseReportReason 资源的 snippet.label 和 snippet.secondaryReasons[].label 属性的定义，以指明这些属性包含本地化标签文本，这是举报滥用行为的原因。

      此外，videoAbuseReportReasons.list 方法现在支持 hl 参数，该参数用于指定 API 响应中标签文本应使用的语言。默认的参数值为 en_US。

    • video 资源的新 contentDetails.contentRating.ecbmctRating 属性用于标识视频由土耳其文化旅游部评估和分级委员会颁发的分级。

      此外，其他分级系统的 API 属性支持以下新属性值：

      • contentDetails.contentRating.fpbRating（南非）
        评分：10；属性值：fpb10
      • contentDetails.contentRating.moctwRating（台湾）
        评分：R-12；属性值：moctwR12
      • contentDetails.contentRating.moctwRating（台湾）
        评分：R-15；属性值：moctwR15

    • video 资源的 liveStreamingDetails.activeLiveChatId 属性包含与视频相关联的有效实时聊天的 ID。仅当视频是启用了实时聊天功能的当前直播时，此属性值才会显示。直播结束后且实时聊天结束后，系统将不再为视频返回该属性。

    • video 资源的 status.rejectionReason 属性支持新属性值 legal。

  • 该 API 支持以下新错误：

    错误类型 错误详情 说明
    badRequest (400) notEditable channelSections.insert、channelSections.update 和 channelSections.delete 方法会返回此错误，表明指定的频道版块无法创建、更新或删除。
    badRequest (400) styleRequired channelSections.insert 和 channelSections.update 方法会返回此错误，以表明 API 请求中提交的 channelSection 资源必须为 snippet.style 属性指定一个值。
    badRequest (400) typeRequired channelSections.insert 和 channelSections.update 方法会返回此错误，以表明 API 请求中提交的 channelSection 资源必须为 snippet.type 属性指定一个值。
    badRequest (400) processingFailure commentThreads.list 方法会返回此错误，表明 API 服务器未能成功处理请求。虽然这可能是暂时性错误，但通常表示请求的输入无效。检查请求正文中 commentThread 资源的结构，确保其有效。
    forbidden (403) commentsDisabled commentThreads.list 方法返回此错误，表示由 videoId 参数标识的视频已停用评论功能。
    badRequest (400) commentTextTooLong commentThreads.insert 方法返回此错误，表明正在插入的 comment 资源 snippet.topLevelComment.snippet.textOriginal 属性中包含过多字符。
    invalidValue (400) videoAlreadyInAnotherSeriesPlaylist playlistItems.insert 方法会返回此错误，表示您尝试添加到播放列表中的视频已在另一个系列播放列表中。请参阅 YouTube 帮助中心，详细了解系列播放列表。
    badRequest (400) subscriptionForbidden subscriptions.insert 方法会返回此错误，表明您已达到订阅数量上限或近期创建的订阅过多。对于后一种情况，您可以在几个小时后重试请求。
    badRequest (400) invalidCategoryId videos.update 方法返回此错误，表示上传的 video 资源中的 snippet.categoryId 属性指定的类别 ID 无效。使用 videoCategories.list 方法检索支持的类别。
    badRequest (400) invalidDescription videos.update 方法返回此错误，表示上传的 video 资源中的 snippet.description 属性指定的值无效。
    badRequest (400) invalidPublishAt videos.update 方法会返回此错误，以表明上传的 video 资源中的 status.publishAt 属性指定的预定发布时间无效。
    badRequest (400) invalidRecordingDetails videos.update 方法返回此错误，表示上传的 video 资源中的 recordingDetails 对象指定了无效的录音详细信息。
    badRequest (400) invalidTags videos.update 方法返回此错误，表示上传的 video 资源中的 snippet.tags 属性指定的值无效。
    badRequest (400) invalidTitle videos.update 方法会返回此错误，以指明上传的 video 资源中的 snippet.title 属性指定的视频标题无效或为空。
    badRequest (400) invalidVideoMetadata videos.update 方法返回此错误来表明请求元数据无效。如果请求更新 video 资源的 snippet 部分，但没有同时为 snippet.title 和 snippet.categoryId 属性设置值，则会出现此错误。

2015 年 12 月 18 日

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

2015 年 11 月 19 日

API 现在支持为 playlist 和 video 资源的 snippet.title 和 snippet.description 属性、channelSection 资源的 snippet.title 属性以及 channel 资源的 snippet.description 属性设置和检索本地化文本。

  • 设置本地化商品名和说明

    在为资源调用 insert 或 update 方法时，您可以为该资源设置本地化值。如需为资源设置本地化值，请执行以下两项操作：

    • 确保为资源的 snippet.defaultLanguage 属性设置一个值。该属性用于标识资源的 snippet.title 和 snippet.description 属性的语言。其值可以是任何受支持的应用语言或大多数其他 ISO 639-1:2002 语言代码。例如，如果您上传的视频带有英语标题和说明，则应将 snippet.defaultLanguage 属性设置为 en。

      有关更新 channel 资源的注意事项：如需为 channel 资源设置 snippet.defaultLanguage 属性，您实际上需要更新 brandingSettings.channel.defaultLanguage 属性。

    • 将 localizations 对象添加到要更新的资源。每个对象键都是一个用于标识应用语言或 ISO 639-1:2002 语言代码的字符串，并且每个键都映射到一个包含资源的本地化标题（和说明）的对象。

      以下示例代码段将资源的默认语言设置为英语。它还会为视频添加经过本地化的德语和西班牙语标题和说明：

      {
  "kind": "youtube#video",
  ...
  "snippet": {
    "title": "Playing soccer",
    "description": "We play soccer in the park on Sundays.",
    "defaultLanguage": "en",
    ...
  },
  "localizations":
    "de": {
      "title": "Fußball spielen",
      "description": "Wir spielen Fußball im Park am Sonntag"
    },
    "es": {
      "title": "Jugar al fútbol",
      "description": "Nosotros jugamos fútbol en el parque los domingos",
    }
  }
}

      • 重要提示：请记住，当您更新资源的本地化数据时，您的 API 请求必须包含数据的所有现有本地化版本。例如，如果您后续发送了一个向上述示例视频添加葡萄牙语数据的请求，则该请求需要包含德语、西班牙语和葡萄牙语的本地化数据。

  • 检索本地化的值

    该 API 支持两种方法检索资源的本地化值：

    • 将 hl 参数添加到您的 channels.list、channelSections.list、playlists.list 或 videos.list 请求，以检索 YouTube 网站支持的特定应用语言的本地化数据。如果有本地化的资源详细信息能以相应语言提供，资源的 snippet.localized 对象将包含这些本地化的值。但是，如果没有本地化的详细信息，snippet.localized 对象将包含以资源默认语言显示的资源详细信息。

      例如，假设 videos.list 请求使用本地化的德语和西班牙语数据检索了上述视频的数据。如果 hl 参数设置为 de，该资源将包含以下数据：

      {
  "kind": "youtube#video",
  ...
  "snippet": {
    "title": "Playing soccer",
    "description": "We play soccer in the park on Sundays.",
    "defaultLanguage": "en",
    "localized": {
      "title": "Fußball spielen",
      "description": "Wir spielen Fußball im Park am Sonntag"
    }
    ...
  }
}

      但是，如果 hl 参数设置为 fr，则 snippet.localized 对象将包含英文标题和说明，因为此资源的默认语言是英语，且未提供本地化的法语详情。

      重要提示：hl 参数仅支持用于标识 YouTube 网站支持的应用语言的值。如需确定本地化文本是否适用于其他语言，您需要检索资源的 localizations 部分，并进行过滤以确定本地化文本是否存在。

      例如，您需要检索完整的本地化列表，以确定本地化文本是否提供阿巴拉契亚英语版本。

    • 检索资源时，请在 part 参数值中包含 localizations，以检索该资源的所有本地化详情。如果您要检索的本地化数据所用的语言不是当前 YouTube 应用语言，则需要使用此方法检索所有本地化语言版本，然后进行过滤，以确定是否存在所需的本地化数据。

  • 与本地化文本值相关的错误

    该 API 还支持以下针对本地化文本值的新错误：

    错误类型 错误详情 说明
    badRequest (400) defaultLanguageNotSetError 此错误表示尝试为资源插入或更新 localizations 对象的请求失败，因为没有为该资源设置 snippet.defaultLanguage 属性。channels.update、channelSections.insert、channelSections.update、playlists.insert、playlists.update、videos.insert 和 videos.update 方法支持此错误。
    badRequest (400) localizationValidationError 此错误表示资源的 localizations 对象中的某个值无法验证。例如，如果对象包含无效的语言代码，就可能会出现此错误。channels.update、channelSections.insert、channelSections.update、playlists.insert 和 playlists.update 方法支持此错误。

2015 年 11 月 4 日

此更新包含以下更改：

  • 现有资源和方法的更新

    • search.list 方法的 order 参数已更新，以指明如果您按 viewCount 对直播进行排序，API 结果将按直播的直播期间同时观看的人数。

    • search.list 方法的 relatedToVideoId 参数已更新，以指明，如果设置了该参数，则唯一支持的其他参数为 part、maxResults、pageToken、regionCode、relevanceLanguage、safeSearch、type（必须设置为 video）和 fields。此更新并未反映 API 行为的变化。

    • video 资源的 snippet.publishedAt 属性的定义已更新，以指明用于指定视频发布日期和时间的属性值可能与视频的上传时间不同。例如，如果某个视频在上传为私享视频，后来又设为公开，则 属性值会指定该视频设为公开的时间。更新后的定义还说明了对于私享视频和不公开列出的视频，此值是如何填充的。

      此更改不反映 API 行为的变化。

    • video 资源的 status.publishAt 属性的定义已更新，以注明以下事项：

      • 如果您在调用 videos.update 方法时设置此属性的值，则还必须将 status.privacyStatus 属性值设为 private，即使视频已是私享视频也是如此。
      • 如果请求将某个视频安排在过去某个时间发布，则该视频会立即发布。因此，将 status.publishAt 属性设为过去的日期和时间的效果与将视频的 privacyStatus 从 private 更改为 public 的效果相同。

    • video 资源的 contentDetails.contentRating.cncRating 属性用于指定法国电影分级委员会的视频分级。此属性取代了现已废弃的 contentDetails.contentRating.fmocRating 属性。

    • channel 资源的 brandingSettings.channel.keywords 的定义已更新，以正确反映属性值包含以空格分隔的字符串列表，而不是以英文逗号分隔的列表（如前所述）。此更新并未反映 API 行为的变化。

    • thumbnails.set 方法的文档已更新，以准确反映请求的正文包含您要上传并与视频关联的缩略图。请求正文不包含 thumbnail 资源。之前，文档指出在调用此方法时不应提供请求正文。此更新并未反映 API 行为的变化。

    • activity 资源的说明已更新，以反映 activities.list 方法目前不包含与新视频评论相关的资源。资源的 snippet.type 和 contentDetails.comment 也已更新。

  • 新错误和更新后的错误

    • API 现在支持以下错误：

      错误详情
      activities.insert
      HTTP 响应代码badRequest (400)
      原因invalidMetadata
      说明kind 属性与提供的 ID 类型不匹配。
      commentThreads.update
      comments.insert
      comments.update
      HTTP 响应代码badRequest (400)
      原因commentTextTooLong
      说明所插入或更新的 comment 资源的 snippet.topLevelComment.snippet.textOriginal 属性中包含过多字符。
      playlistItems.insert
      playlistItems.update
      HTTP 响应代码forbidden (403)
      原因playlistItemsNotAccessible
      说明此请求未获得适当的授权，无法插入、更新或删除指定的播放列表项。
      playlists.delete
      playlists.insert
      playlists.update
      HTTP 响应代码badRequest (400)
      原因playlistForbidden
      说明此操作被禁止或未正确授权。
      search.list
      HTTP 响应代码badRequest (400)
      原因invalidLocation
      说明location 和/或 locationRadius 参数值的格式不正确。
      search.list
      HTTP 响应代码badRequest (400)
      原因invalidRelevanceLanguage
      说明“relevanceLanguage”参数值的格式不正确。
      subscriptions.insert
      HTTP 响应代码badRequest (400)
      原因subscriptionForbidden
      说明出现以下任一情况时，就会显示此错误：
      • 您尝试创建的订阅已存在
      • 你的订阅数量已达到上限
      • 你正在尝试订阅自己的频道，系统不支持此操作。
      • 您最近创建的订阅过多，需要等待几个小时才能重试请求。
      videos.update
      HTTP 响应代码badRequest (400)
      原因invalidDefaultBroadcastPrivacySetting
      说明该请求尝试为默认广播设置无效的隐私设置。

2015 年 8 月 28 日

此更新包含以下更改：

  • 现有资源和方法的更新

    • video 资源的 statistics.favoriteCount 属性已弃用。

      根据我们的弃用政策，在发布此公告后的至少一年内，此属性将继续包含在 video 资源中。但是，属性值现在始终设置为 0。

2015 年 8 月 7 日

此更新包含以下更改：

  • 现有资源和方法的更新

    • video 资源的 snippet.tags[] 属性的定义已更新，以提供关于 API 服务器如何计算属性值长度的详细信息。请注意，此更新并不反映 API 行为的变化。

      具体而言，该定义现在解释了，如果标记包含空格，API 服务器会把标记值视为用引号引起来，并且引号也会计入字符数限制。因此，出于字符数限制的考虑，标记 Foo-Baz 包含 7 个字符，而标记 Foo Baz 包含 9 个字符。

    • commentThreads.insert 方法不再支持 shareOnGooglePlus 参数，该参数之前指示是否应将某条评论和对该评论的回复发布到作者的 Google+ 个人资料中。如果请求提交 参数，则 API 服务器会忽略该参数，但以其他方式处理请求。

2015 年 6 月 18 日

此更新包含以下更改：

  • 现有资源和方法的更新

    • commentThreads.list 方法的新 order 参数用于指定 API 响应列出评论会话的顺序。讨论帖可以按时间或相关性排序。默认行为是按时间排序。

    • video 资源的新 snippet.defaultAudioLanguage 属性用于指定视频的默认音轨所用的语言。

    • 我们更新了 video 资源的 contentDetails.licensedContent 属性的定义，以明确指出内容最初必须是上传到与 YouTube 内容合作伙伴相关联的频道，然后由该合作伙伴声明的。这并不表示实际 API 行为发生了变化。

    • captions.delete、captions.download、captions.insert、captions.list 和 captions.update 方法现在支持 onBehalfOfContentOwner 参数，其他几种方法也已支持该参数。使用该方法的请求还需要使用令牌进行授权，该令牌可提供对 https://www.googleapis.com/auth/youtubepartner 范围的访问权限。

  • 新错误和更新后的错误

    • API 现在支持以下错误：

      错误详情
      videos.rate
      HTTP 响应代码badRequest (400)
      原因emailNotVerified
      说明在对视频评分之前，用户必须先验证其电子邮件地址。
      videos.rate
      HTTP 响应代码badRequest (400)
      原因videoPurchaseRequired
      说明只有租借视频的用户才能对租借视频进行评分。

    • subscriptions.delete 和 subscriptions.insert 方法不再支持 accountClosed 和 accountSuspended 错误。

2015 年 4 月 27 日

此更新包含以下更改：

  • 新资源和方法

    • 新增的 videoAbuseReportReason 资源中包含相关信息，以说明视频因包含滥用内容而遭到举报的原因。借助 videoAbuseReportReasons.list 方法，您可以检索视频被举报的所有可能原因的列表。

    • 新的 videos.reportAbuse 方法提供了一种真正举报包含侮辱性内容的视频。请求的正文包含一个 JSON 对象，用于指定被举报的视频以及视频被视为包含侮辱性内容的原因。可以通过上述 videoAbuseReportReason.list 方法获取正当原因。

      迁移指南也已更新，添加了举报滥用视频的示例。通过此次变更，v3 API 现在支持其计划支持的所有 v2 API 功能。迁移指南中也介绍了这些功能。

  • 现有资源和方法的更新

    • search.list 方法的新 forDeveloper 过滤条件参数将搜索限制为仅检索通过开发者的应用或网站上传的视频。forDeveloper 参数可与可选的搜索参数（例如 q 参数）结合使用。

      对于此功能，系统会自动使用项目编号标记您上传的每个视频，这些项目编号与 Google Developers Console 中开发者的应用相关联。

      当搜索请求随后将 forDeveloper 参数设置为 true 时，API 服务器会使用该请求的授权凭据来识别开发者。因此，开发者可以将结果限制为通过开发者自己的应用或网站上传的视频，但不能显示通过其他应用或网站上传的视频。

      这项新功能提供的功能与 v2 API 支持的开发者代码功能类似，但并不完全相同。

    • channel 资源的新 snippet.country 属性可让频道所有者将其频道与特定国家/地区相关联。

      注意：如需为 channel 资源设置 snippet.country 属性，您实际上需要更新 brandingSettings.channel.country 属性。

    • 该 API 现在支持定位到 channelSection 资源。频道版块定位提供了一种方式，可将内容版块的公开范围限制为符合特定条件的用户。

      该 API 提供了三种定位选项。用户必须满足所有定位设置，频道版块才会显示。

    • 更正了 video 资源的 contentDetails.duration 属性的定义，以反映该值可以反映小时、天等。

    • 更正了 channelSections.delete、playlistItems.delete、playlists.delete、subscriptions.delete 和 videos.delete 方法的文档，以反映成功后，这些方法都会返回 HTTP 204 响应代码 (No Content)。

  • 新错误和更新后的错误

    • API 现在支持以下错误：

      错误类型 错误详情 说明
      badRequest (400) targetInvalidCountry 如果插入的 channelSection 资源包含无效的 targeting.countries[] 属性值，则 channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) targetInvalidLanguage 如果插入的 channelSection 资源包含无效的 targeting.languages[] 属性值，则 channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) targetInvalidRegion 如果插入的 channelSection 资源包含无效的 targeting.regions[] 属性值，则 channelSections.insert 和 channelSections.update 方法会返回此错误。
      badRequest (400) operationNotSupported 如果 API 用户无法插入评论来回复 snippet.parentId 属性标识的顶级评论，则 comments.insert 方法会返回此错误。在 commentThread 资源中，snippet.canReply 属性指示当前查看者是否可以回复该线程。
      badRequest (400) invalidChannelId 如果请求中的 channelId 参数指定的频道 ID 无效，search.list 方法会返回此错误。
      badRequest (400) subscriptionForbidden 如果 API 用户尝试订阅用户自己的频道，subscriptions.insert 方法会返回此错误。

    • captions.update 方法不再支持 invalidMetadata 和 videoNotFound 错误。

2015 年 4 月 16 日

此更新包含以下更改：

  • 我们更新了迁移指南，以说明如何迁移仍在使用 v2 API 中的评论功能的应用。

    本指南还指出了 v2 API 不支持但 v3 API 支持的一些评论功能。其中包括：

    • 检索有关频道的评论
    • 检索与频道相关的所有评论会话，这意味着 API 响应可以包含有关频道或其任何视频的评论。
    • 更新评论的文本
    • 将评论标记为垃圾评论
    • 设置评论的审核状态

  • 订阅推送通知指南已更新，以反映通知只会推送到 Google PubSubHubBub 中心，不会同时推送到 Superfeedr 中心（如前所述）。

2015 年 4 月 9 日

此更新包含以下更改：

  • 通过 API 的新 commentThread 和 comment 资源，您可以检索、插入、更新、删除和管理评论。

    • commentThread 资源包含有关 YouTube 评论会话的信息，其中包括顶级评论和对该评论的回复（如果有）。commentThread 资源可以表示关于视频或频道的评论。

      顶级评论和回复实际上是嵌套在 commentThread 资源中的 comment 资源。请务必注意，commentThread 资源并不一定包含评论的所有回复，并且如果您要检索特定评论的所有回复，则需要使用 comments.list 方法。此外，有些评论没有回复。

      对于 commentThread 资源，该 API 支持以下方法：

    • comment 资源包含一条 YouTube 评论的相关信息。comment 资源可以表示关于视频或频道的评论。此外，评论可以是顶级评论，也可以是对顶级评论的回复。

      对于 comment 资源，该 API 支持以下方法：

      • comments.list - 检索评论列表。使用此方法可检索特定评论的所有回复。
      • comments.insert - 创建对现有评论的回复。
      • comments.update – 修改评论。
      • comments.markAsSpam – 举报一条或多条评论为垃圾内容。
      • comments.setModerationStatus - 设置一条或多条评论的审核状态。例如，您可以清除某条评论以供公开显示，或拒绝某条评论不适合显示。API 请求必须获得与评论相关联的频道或视频所有者的授权。
      • comments.delete – 删除评论。

    请注意，调用 comments.insert、comments.update、comments.markAsSpam、comments.setModerationStatus、comments.delete、commentThreads.insert 和 commentThreads.update 方法时需要使用 API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围（请参阅 2015 年 4 月 2 日的修订历史记录）。

  • 新增的订阅推送通知指南介绍了该 API 通过 PubSubHubBub 新增对推送通知的支持。PubSubHubBub 是一种服务器到服务器的发布/订阅协议，适用于可通过网络访问的资源。当频道执行以下任意活动时，您的 PubSubHubBub 回调服务器可以收到 Atom Feed 通知：

    • 上传视频
    • 更新视频标题
    • 更新视频说明

  • 迁移指南也已更新，以指出对推送通知的新支持。不过，由于 v2 API 支持 v3 API 不支持的许多其他类型的推送通知，因此该指南的已弃用部分中仍会提及 PubSubHubBub 支持。

  • 对于以前支持 https://www.googleapis.com/auth/youtube 范围的任何 API 方法，API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围现在都是有效的范围。

  • API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest (400) invalidRating 如果请求的 rating 参数包含非预期的值，videos.rate 方法会返回此错误。

  • subscriptions.insert 方法不再支持 subscriptionLimitExceeded 错误，该错误之前表示通过请求标识的订阅者已超过订阅速率限制。

2015 年 4 月 2 日

此更新包含以下更改：

  • 新的 captions 资源表示 YouTube 字幕轨道。一个字幕轨道只能与一个 YouTube 视频关联。

    该 API 支持列出、插入、更新、下载和删除字幕轨道的方法。

  • 我们还更新了迁移指南，介绍如何迁移仍在使用 v2 API 字幕功能的应用。

  • API 的新 https://www.googleapis.com/auth/youtube.force-ssl 范围要求通过 SSL 连接与 API 服务器进行通信。

    此新范围会授予与 https://www.googleapis.com/auth/youtube 范围相同的访问权限。实际上，这两个作用域在功能上是相同的，因为 YouTube API 服务器只能通过 HTTPS 端点访问。因此，即使 https://www.googleapis.com/auth/youtube 范围不需要 SSL 连接，实际上也无法通过其他方式发出 API 请求。

    调用所有 caption 资源的方法需要新范围。

2015 年 3 月 11 日

此更新包含以下更改：

  • YouTube Data API (v3) 迁移指南包含一个名为 v3 API 中的新功能的新标签，其中列出了 v3 API 支持和不支持的功能。这些功能之前已提供，并且仍然列在指南的其他标签页中。例如，频道（配置文件）标签页下也会列出介绍如何更新频道的视频内推广广告系列数据的新功能。

  • YouTube Data API (v3) 迁移指南已更新，指出 v3 API 将支持以下 v2 API 功能：

  • YouTube Data API (v3) 迁移指南已更新，指出 v3 API 不支持以下 v2 API 功能：

    • 检索视频推荐 - v3 API 不会检索到只包含为当前 API 用户推荐的视频的列表。不过，您可以使用 v3 API 查找推荐视频，具体方法是调用 activities.list 方法并将 home 参数值设为 true。

      在 API 响应中，如果 snippet.type 属性的值为 recommendation，则资源对应于推荐的视频。在这种情况下，contentDetails.recommendation.reason 和 contentDetails.recommendation.seedResourceId 属性将包含视频推荐原因的相关信息。请注意，我们无法保证响应中包含任何特定数量的推荐视频。

    • 检索频道建议

    • 检索新的订阅视频 - v3 API 不会检索符合以下条件的列表：仅包含最近上传到 API 用户订阅的频道的视频。不过，您可以使用 v3 API 查找新的订阅视频，只需调用 activities.list 方法并将 home 形参值设置为 true 即可。

      在 API 响应中，如果 snippet.type 属性的值为 upload，则资源对应于新的订阅视频。请注意，我们无法保证响应会包含任何特定数量的新订阅视频。

    • RSS Feed 支持

    • Feed 更新的推送通知 - v2 API 支持的推送通知使用简单更新协议 (SUP) 或 PubSubHubbub，以监控 YouTube 用户的用户活动 Feed。系统会针对新订阅的频道，以及对视频进行评分、分享、收藏、评论或上传视频的通知。

      v3 API 将支持使用 PubSubHubbub 协议的推送通知，但通知仅涵盖视频上传以及对视频标题或视频说明的更新。

    • 频道位置 - v2 API 使用 <yt:location> 标记来识别用户在频道的 YouTube 公开个人资料中输入的位置。虽然一些开发者使用此字段将频道与特定国家/地区相关联，但该字段的数据无法始终用于此目的。

    • 设置或检索开发者标签 – 在 v2 API 中，支持在上传视频时将关键字或开发者标签与视频相关联。开发者标签不会向 YouTube 用户显示，但视频拥有者可以检索与特定开发者标签相匹配的视频。

      v3 API 将提供类似但并不完全相同的功能。具体来说，开发者将能够搜索由其自己的应用上传的视频。对于此功能，系统会自动使用项目编号标记您上传的每个视频，这些项目编号与 Google Developers Console 中开发者的应用相关联。然后，开发者会使用相同的项目编号搜索视频。

    • 按发布日期、观看次数或评分列出视频 - 在 v2 API 中，您可以使用 orderby 参数按位置、时长、发布日期、标题以及其他多个值对播放列表中的视频进行排序。在 v3 API 中，播放列表项通常按位置升序排序，其他排序选项不可用。

      但也有一些例外情况。对于以下类型的播放列表，系统会自动将新上传的视频、收藏的视频、赞过的视频或最近观看的视频添加为第一项 (snippet.position=0)。因此，系统会根据这些项添加到列表中的时间，按照从新到旧的顺序有效地对上述每个列表进行排序。

      • 用户上传的内容
      • 收藏的视频
      • 顶过的视频
      • 观看记录

      不过请注意，添加到“稍后观看”列表中的新项目播放列表将作为该列表中的最后一项添加，从而有效地从最旧项到最新项对列表进行排序。

    • 批处理 - v3 API 支持 v2 API 支持的批处理用例之一。v3 API 的 channels.list、channelSections.list、guideCategories.list、playlistItems.list、playlists.list、subscriptions.list、videoCategories.list 和 videos.list 方法都支持 id 参数，该参数可用于指定以英文逗号分隔的 ID（视频 ID、频道 ID 等）列表。使用这些方法，您可以通过单个请求检索多个资源的列表。

    通过这些更改，本指南现在明确指出了旧版 (v2) API 中支持的所有功能，而旧版 (v2) API 将在当前 API 版本 (v3) 中弃用这些功能。

2015 年 3 月 4 日

此更新包含以下更改：

  • channelSections.delete 和 channelSections.update 方法现在支持 onBehalfOfContentOwner 参数，其他一些方法也已支持该参数。

  • 以下属性及其子属性已被弃用：

    • brandingSettings.image.backgroundImageUrl
    • brandingSettings.image.largeBrandedBannerImageImapScript
    • brandingSettings.image.largeBrandedBannerImageUrl
    • brandingSettings.image.smallBrandedBannerImageImapScript
    • brandingSettings.image.smallBrandedBannerImageUrl

    注意：上述资源均不受《API 弃用政策》的约束。

  • video 资源的新 contentDetails.contentRating.contentDetails.contentRating.djctqRatingReasons 属性指出了视频获得 DJCQT（巴西）评级的原因。

  • API 现在支持以下错误：

    错误类型 错误详情 说明
    notFound (404) channelNotFound 如果请求的 id 参数指定了找不到渠道，channels.update 方法会返回此错误。
    badRequest (400) manualSortRequiredinvalidValue 如果请求尝试设置播放列表项的位置，但播放列表未使用手动排序，则 playlistItems.insert 和 playlistItems.update 方法会返回此错误。例如，播放列表中的内容可以按日期或热门程度排序。您可以通过从请求正文中发送的资源中移除 snippet.position 元素来解决此问题。如果您希望播放列表项在列表中位于特定的位置，需要先将播放列表的排序设置更新为手动。您可以在 YouTube 视频管理器中调整此设置。
    forbidden (403) channelClosed 如果请求的 channelId 参数指定某个频道已关闭，则 playlists.list 方法会返回此错误。
    forbidden (403) channelSuspended 如果请求的 channelId 参数指定已暂停的频道，则 playlists.list 方法会返回此错误。
    forbidden (403) playlistForbidden 如果请求的 id 参数不支持请求或请求未正确授权，playlists.list 方法会返回此错误。
    notFound (404) channelNotFound 如果请求的 channelId 参数指定了找不到渠道，playlists.list 方法会返回此错误。
    notFound (404) playlistNotFound 如果请求的 id 参数指定了找不到播放列表，playlists.list 方法会返回此错误。
    notFound (404) videoNotFound 如果请求的 id 参数指定了找不到视频，videos.list 方法会返回此错误。
    badRequest (400) invalidRating 如果请求的 rating 参数包含非预期的值，videos.rate 方法会返回此错误。

2015 年 3 月 2 日

此更新包含以下更改：

2015 年 1 月 14 日

此更新包含以下更改：

  • YouTube Data API (v3) 迁移指南已更新，介绍了如何使用 v3 API 通过 JavaScript 上传视频。（有关详情，请参阅上传视频部分）。此功能相当于 v2 API 支持的基于浏览器的上传功能。请注意，对迁移指南的这一更改并不反映实际的 API 更改，而是反映提供用于使用客户端 JavaScript 上传视频的新示例代码。

    由于支持使用 JavaScript 客户端库和 CORS 上传视频，因此迁移指南不再将基于浏览器的上传列为 v3 API 中可能已弃用的功能。

  • videos.insert 方法的文档已更新，以包含上述新的 JavaScript 代码示例。适用于 YouTube Data API (v3) 的 JavaScript 代码示例列表也已更新。

2014 年 11 月 11 日

此更新包含以下更改：

  • 调用 search.list 方法的配额费用已更改为 100 个单位。

    重要提示：在许多情况下，您可以使用其他 API 方法以较低的配额费用检索信息。例如，您可以考虑使用以下两种方法来查找上传到 GoogleDevelopers 频道的视频。

    • 配额费用：100 个单元

      调用 search.list 方法并搜索 GoogleDevelopers。

    • 配额费用：6 个单位

      调用 channels.list 方法以查找正确的频道 ID。将 forUsername 形参设置为 GoogleDevelopers，并将 part 形参设置为 contentDetails。在 API 响应中，contentDetails.relatedPlaylists.uploads 属性为频道中上传的视频指定播放列表 ID。

      然后，调用 playlistItems.list 方法，并将 playlistId 参数设置为捕获的 ID，并将 part 参数设置为 snippet。

2014 年 10 月 8 日

此更新包含以下更改：

  • channel 资源包含两个新属性：

    • status.longUploadsStatus 属性用于指明频道是否可以上传时长超过 15 分钟的视频。只有在频道所有者授权了 API 请求时，系统才会返回此属性。有效的属性值包括：

      • allowed – 频道可以上传时长超过 15 分钟的视频。
      • eligible – 频道可以上传时长超过 15 分钟的视频，但必须先启用此功能。
      • disallowed – 频道无法或无法上传时长超过 15 分钟的视频。

      有关这些值的详细信息，请参阅属性定义。YouTube 帮助中心也提供了有关此功能的更多详细信息。

    • invideoPromotion.useSmartTiming 属性用于指明频道的宣传广告系列是否使用了“智能计时”。此功能会尝试在视频中的时间点展示宣传内容，此时间点显示宣传内容更有可能获得点击，并且不太可能干扰观看体验。此功能还可以选择单个宣传，以便在每个视频上展示。

  • video 资源的 snippet.title 和 snippet.categoryId 属性的定义都已更新，以阐明 API 处理 videos.update 方法调用的方式。如果您调用该方法以更新 video 资源的 snippet 部分，则必须为这两个属性设置一个值。

    如果您尝试更新 video 资源的 snippet 部分，但没有为这两个属性设置值，API 会返回 invalidRequest 错误。该错误的说明也已更新。

  • video 资源的 contentDetails.contentRating.oflcRating 属性用于标识视频来自新西兰电影与文学分类办公室的分级，现在支持两种新分级：oflcRp13 和 oflcRp16。这两个值分别对应于 RP13 和 RP16 评分。

  • channelBanners.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest bannerAlbumFull 频道所有者的“YouTube 频道图片”影集中的图片过多。频道所有者应访问 http://photos.google.com，转到影集页面，并从该影集的图片中移除一些内容。

2014 年 9 月 12 日

此更新包含以下更改：

  • 除了指定资源部分的费用之外，调用 search.list 方法的配额费用已从 1 个单位更改为 2 个单位。

2014 年 8 月 13 日

此更新包含以下更改：

  • subscriptions.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest subscriptionLimitExceeded 此请求所标识的订阅者已超出订阅速率限制。您过几个小时后可以尝试更多订阅。

2014 年 8 月 12 日

此更新包含以下更改：

  • 标题为将您的应用迁移到 YouTube Data API (v3) 的新指南介绍了如何使用 YouTube Data API (v3) 执行 YouTube Data API (v2) 中提供的功能。旧版 API 自 2014 年 3 月 4 日起已正式弃用。本指南旨在帮助您将仍在使用 v2 API 的应用迁移至最新的 API 版本。

2014 年 7 月 8 日

此更新包含以下更改：

  • playlists.insert 方法现在支持以下错误：

    错误类型 错误详情 说明
    badRequest maxPlaylistExceeded 如果由于频道已达到允许的播放列表数量上限而无法创建播放列表，就会出现此错误。

2014 年 6 月 18 日

此更新包含以下更改：

  • 每个 API 方法的说明已更新，以包含调用该方法所产生的配额费用。同样，part 参数的定义也已更新，以指定可在 API 调用中检索到的每个部分的配额费用。例如，调用 subscriptions.insert 方法大约消耗 50 个单位的配额费用。subscription 资源还包含三个部分（snippet、contentDetails 和 subscriberSnippet），每个部分的费用为两个单位。

    请注意，配额费用可能会发生变化，恕不另行警告。

  • video 资源现在支持 43 种新的内容分级制度，这些分级制度可以确定视频从各个国家级分级机构获得的分级。

2014 年 5 月 28 日

此更新包含以下更改：

  • search.list 方法现在支持 location 和 locationRadius 参数，以便您搜索与地理位置相关联的视频。为根据位置检索结果，请求必须为这两个参数指定一个值；如果请求仅包含这两个参数中的一个，则 API 将返回错误。

    • location 参数用于指定圆形地理区域中心的纬度/经度坐标。

    • locationRadius 参数用于指定与视频相关联的位置距离视频区域中心的最大距离，以便视频仍然显示在搜索结果中。

2014 年 5 月 13 日

此更新包含以下更改：

  • channel 资源的 invideoPromotion.items[] 属性已更新，以指明您通常只能为频道设置一个促销商品。如果您尝试插入过多促销商品，API 会返回 tooManyPromotedItems 错误，其包含 HTTP 400 状态代码。

  • channelSection 资源现在可以包含一些新型精选内容的相关信息。channelSection 资源的 snippet.type 属性现在支持以下值：

    • postedPlaylists - 频道所有者发布到频道活动 Feed 的播放列表
    • postedVideos - 频道所有者发布到频道活动 Feed 的视频
    • subscriptions - 频道所有者订阅的频道

  • video 资源的新 contentDetails.contentRating.ifcoRating 属性用于标识视频从爱尔兰电影分级局获得的分级。

  • 我们更新了 watermark 资源的 position.cornerPosition 属性的定义，以指明水印始终显示在播放器的右上角。

  • search.list 方法的 q 参数的定义已更新，以指明查询字词可以使用布尔值 NOT (-) 运算符排除与特定搜索字词相关联的视频。此值还可以使用布尔值 OR (|) 运算符来查找与多个搜索字词之一相关联的视频。

  • 在对 search.list 调用的 API 响应中返回的 pageInfo.totalResults 属性的定义已更新，以指明该值为近似值，可能并不表示精确值。此外，最大值为 1,000,000。您不应使用此值创建分页链接。请改用 nextPageToken 和 prevPageToken 属性值来确定是否显示分页链接。

  • watermarks.set 和 watermarks.unset 方法已更新，以反映 API 会针对对这些方法的成功请求返回 HTTP 204 响应代码。

2014 年 5 月 2 日

此更新包含以下更改：

  • 新的 i18nLanguage 资源用于标识 YouTube 网站支持的应用语言。应用语言也可称为界面语言。对于 YouTube 网站，系统会根据 Google 账号设置、浏览器语言或 IP 位置自动选择应用语言，用户也可以从 YouTube 网站页脚中手动选择所需的界面语言。

    该 API 支持使用列出受支持的应用语言的方法。在调用 videoCategories.list 和 guideCategories.list 等 API 方法时，支持的语言可用作 hl 参数的值。

  • 新的 i18nRegion 资源用于标识可供 YouTube 用户选作首选内容区域的地理区域。内容区域也可称为内容语言区域。对于 YouTube 网站，可以根据 YouTube 网域或用户的 IP 位置等启发法自动选择内容区域，用户也可以从 YouTube 网站页脚中手动选择所需的内容区域。

    该 API 支持使用列出支持的内容区域的方法。在调用 search.list、videos.list、activities.list 和 videoCategories.list 等 API 方法时，支持的地区代码可用作 regionCode 参数的值。

2014 年 4 月 7 日

此更新包含以下更改：

  • 新增的 channelSection 资源包含频道选择推介的一组视频的相关信息。例如，版块可以展示某个频道最新上传的视频、最热门的上传视频或一个或多个播放列表中的视频。

    该 API 支持列出、插入、更新或删除频道版块的方法。您可以通过指定特定的频道 ID 或指定唯一频道版块 ID 来检索已验证用户的频道的频道版块列表。

    错误文档也已更新，以说明 API 专门针对这些新方法支持的错误消息。

  • video 资源的 fileDetails 对象的定义已更新，以说明仅当视频的 processingDetails.fileDetailsAvailability 属性的值为 available 时，系统才会返回该对象。

    同样，video 资源的 suggestions 对象的定义也已更新，以说明仅当视频的 processingDetails.tagSuggestionsAvailability 属性或其 processingDetails.editorSuggestionsAvailability 属性的值为 available 时，系统才会返回该对象。

  • videos.insert 和 videos.update 方法的文档已更新，以体现在调用这些方法时可以设置 status.publishAt 属性。

  • channel 资源的 invideoPromotion 对象的定义已更新，以指明只有频道所有者才能检索该对象。

  • videos.rate 方法的参数列表已更新，以反映该方法实际上并不支持 onBehalfOfContentOwner 参数。这是一个文档错误，因为设置此参数的 videos.rate 请求会返回 500 错误。

2014 年 3 月 31 日

此更新包含以下更改：

2014 年 3 月 13 日

此更新包含以下更改：

  • API 现在支持 channel 资源的 contentOwnerDetails 部分。新部分包含与频道关联的 YouTube 合作伙伴相关的频道数据，包括与频道相关联的内容所有者的 ID，以及内容所有者与频道关联的日期和时间。请注意，这个新增部分不受弃用政策的约束。

  • 该文档现在列出了以下属性支持的最大字符长度：

    资源 属性 最大长度
    channel invideoPromotion.items[].customMessage 40 个字符
    video snippet.title 100 个字符
    video snippet.description 5000 个字节
    video snippet.tags 500 个字符。请注意，属性值是一个列表，列表中各项之间的逗号将计入限制。

  • channel 资源的 brandingSettings.watch.featuredPlaylistId 属性已弃用。如果您尝试设置其值，API 将返回错误。

  • 以下 video 资源属性已添加到插入或更新视频时可设置的值列表中：

  • 现在，错误文档中指定了每种错误类型的 HTTP 响应代码。

  • API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest (400) invalidCriteria 如果请求指定的过滤条件参数无法相互结合使用，则 channels.list 方法会返回此错误。
    badRequest (400) channelTitleUpdateForbidden 如果您尝试更新频道的 brandingSettings 部分并更改 brandingSettings.channel.title 属性的值，channels.update 方法会返回此错误。（请注意，如果您省略该属性，API 将不会返回错误。）
    badRequest (400) invalidRecentlyUploadedBy 如果 invideoPromotion.items[].id.recentlyUploadedBy 属性指定的频道 ID 无效，channels.update 方法会返回此错误。
    badRequest (400) invalidTimingOffset 如果 invideoPromotion 部分指定的计时偏移量无效，则 channels.update 方法会返回此错误。
    badRequest (400) tooManyPromotedItems 如果 invideoPromotion 部分指定的促销商品数量超出了允许的上限，则 channels.update 方法会返回此错误。
    forbidden (403) promotedVideoNotAllowed 如果 invideoPromotion.items[].id.videoId 属性指定的视频 ID 无法找到或无法用作促销商品，则 channels.update 方法会返回此错误。
    forbidden (403) websiteLinkNotAllowed 如果 invideoPromotion.items[].id.websiteUrl 属性指定了不允许使用的网址，channels.update 方法会返回此错误。
    required (400) requiredTimingType 如果请求未指定 YouTube 应展示促销商品的时间设置的默认时间设置，则 channels.update 方法会返回此错误。
    required (400) requiredTiming channels.update 方法必须为每个促销商品指定 invideoPromotion.items[].timing 对象。
    required (400) requiredWebsiteUrl channels.update 方法必须为每个促销商品指定 invideoPromotion.items[].id.websiteUrl 属性。
    badRequest (400) invalidPublishAt 如果请求元数据指定的预定发布时间无效，videos.insert 方法会返回此错误。

2014 年 3 月 4 日

此更新包含以下更改：

2013 年 12 月 5 日

此更新包含以下更改：

  • search.list 方法的文档已更新，以正确反映您在提交搜索请求时无需为一个过滤器参数指定值。相反，您可以为零个过滤器参数或一个过滤器参数设置一个值。

  • search.list 方法参数的定义已更新，以指明如果您也为以下任何形参指定了值，则必须将 type 形参的值设置为 video：

    • eventType
    • videoCaption
    • videoCategoryId
    • videoDefinition
    • videoDimension
    • videoDuration
    • videoEmbeddable
    • videoLicense
    • videoSyndicated
    • videoType

  • 上传的频道横幅图片的最小尺寸已缩减至 2048x1152 像素。（之前，最小尺寸为 2120 x 1192 像素）。另请注意，channel 资源文档指定了通过 API 投放的所有横幅图片的大小上限。例如，电视应用的 brandingSettings.image.bannerTvImageUrl 图片的最大尺寸为 2120 x 1192 像素，但实际图片可能是 2048 x 1152 像素。YouTube 帮助中心提供了更多指南，帮助您优化频道图片，以更好地显示在不同类型的设备上。

  • 多个 channel 资源属性定义已更新，以反映以下信息：

    • brandingSettings.channel.description 属性的值的长度上限为 1000 个字符。
    • brandingSettings.channel.featuredChannelsTitle 属性的长度上限为 30 个字符。
    • brandingSettings.channel.featuredChannelsUrls[] 属性现在最多可以列出 100 个频道。
    • 如果设置了 brandingSettings.channel.unsubscribedTrailer 属性值，则必须指定归频道所有者所有的公开或不公开视频的 YouTube 视频 ID。

  • channels.update 方法现在支持更新 invideoPromotion.items[].promotedByContentOwner 属性。该属性指示在展示宣传时是否会显示内容所有者的名称。仅当使用 onBehalfOfContentOwner 参数代表内容所有者发出用于设置属性值的 API 请求时，才能设置此属性。

  • playlistItems.list 和 playlistItems.insert 方法现在支持 onBehalfOfContentOwner 参数，其他一些方法也已支持该参数。

  • 现在，contentDetails.contentRating.acbRating 属性可以为电影指定澳大利亚分类委员会 (ACB) 或澳大利亚通信媒体管理局 (ACMA) 的儿童电视节目分级。

  • 新的 contentDetails.contentRating.catvRating 和 contentDetails.contentRating.catvfrRating 属性会标识视频根据加拿大电视分类系统和在魁北克使用的法语 Régie du cinéma 分级系统获得的分级。

  • videoCategory 资源的新 snippet.assignable 属性用于指明更新后的视频或新上传的视频是否可以与该视频类别相关联。

  • 为以下方法添加了代码示例：

2013 年 10 月 24 日

此更新包含以下更改：

  • 该 API 包含两项额外功能，旨在帮助查找和推介直播内容：

    搜索结果中的新 snippet.liveBroadcastContent 属性用于指明视频或频道资源是否有直播内容。有效的属性值包括 upcoming、active 和 none。

    请注意，用于标识直播内容的另外两项功能已于 2013 年 10 月 1 日发布：search.list 方法的 eventType 参数和搜索结果的 snippet.liveBroadcastContent 属性。

  • videos.insert 方法现在支持 notifySubscribers 参数，该参数指示 YouTube 是否应向订阅视频频道的用户发送有关新视频的通知。该参数的默认值为 True，表示订阅者将在有新上传的视频时收到通知。但是，上传了许多视频的频道所有者可能希望将该值设为 False，以避免每次向频道订阅者发送新视频的通知。

  • 调用 channels.update 方法时可以修改的属性列表已更新，以包含 invideoPromotion.items[].customMessage 和 invideoPromotion.items[].websiteUrl 属性。此外，此列表还经过修改，以标识可修改的 brandingSettings 属性。这些 brandingSettings 属性已可修改，因此文档变更并不反映对 API 现有功能所做的更改。

  • playlists.insert、playlists.update 和 playlists.delete 方法现在支持 onBehalfOfContentOwner 参数，其他几种方法已经支持该参数。

  • playlists.insert 方法现在支持 onBehalfOfContentOwnerChannel 参数，一些其他方法已经支持该参数。

  • video 资源的 contentDetails.contentRating.tvpgRating 属性现在支持 pg14 值，该值对应于 TV-14 评分。

  • 搜索结果中的 snippet.liveBroadcastContent 属性的定义已更正，以反映 live 是有效的属性值，但 active 不是有效的属性值。

  • video 资源的 contentDetails.contentRating.mibacRating 属性现在支持另外两个评分：

    • mibacVap (VAP) – 儿童应由成人陪同。
    • mibacVm6 (V.M.6) - 仅限 6 及更高版本。
    • mibacVm12 (V.M.12) - 仅限年满 12 周岁的用户观看。

  • channel 资源的新 invideoPromotion.items[].promotedByContentOwner 属性用于指明是否会在展示促销活动时显示内容所有者的名称。只有当用于设置该值的 API 请求是代表内容所有者提出时，才能设置此字段。如需了解详情，请参阅 onBehalfOfContentOwner 参数。

2013 年 10 月 1 日

此更新包含以下更改：

  • channel 资源的新 auditDetails 对象包含频道数据，多频道网络 (MCN) 在确定是接受还是拒绝特定频道时会评估这些数据。请注意，任何检索此资源部分的 API 请求都必须提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit 范围的授权令牌。此外，多频道网络决定接受或拒绝频道后，或在令牌发放之日起两周内，必须撤消使用这种范围的令牌。

  • channel 资源的 invideoPromotion.items[].id.type 属性现在支持 recentUpload 值，该值表示所宣传的商品是指定频道最近上传的视频。

    默认情况下，频道与设置视频内宣传数据的频道相同。但是，您可以宣传来自其他频道最近上传的视频，只需将新 invideoPromotion.items[].id.recentlyUploadedBy 属性的值设为该频道的频道 ID 即可。

  • channel 资源包含 brandingSettings.image.bannerTvLowImageUrl、brandingSettings.image.bannerTvMediumImageUrl 和 brandingSettings.image.bannerTvHighImageUrl 这三个新属性，用于指定电视应用的频道页上显示的横幅图片的网址。

  • 搜索结果中的新 snippet.liveBroadcastContent 属性用于指明视频或频道资源是否有直播内容。有效的属性值包括 upcoming、active 和 none。

    • 对于 video 资源，值为 upcoming 表示视频是尚未开始的直播，而值为 active 则表示视频正在进行直播。
    • 对于 channel 资源，值 upcoming 表示频道有尚未开始的预定广播，而值 acive 表示频道有正在进行的直播。

  • 在 watermark 资源中，targetChannelId 属性已从对象更改为字符串。现在，targetChannelId 属性本身会指定该值本身，而不是包含用于指定水印图片所链接频道的 YouTube 频道 ID 的子属性。因此，资源的 targetChannelId.value 属性已被移除。

  • thumbnails.set 方法现在支持 onBehalfOfContentOwner 参数，一些其他方法已经支持该参数。

  • search.list 方法现在支持 eventType 参数，该参数将搜索限制为仅返回正在进行、即将到来或已完成的广播事件。

  • 新的 contentDetails.contentRating.mibacRating 属性用于标识视频从意大利的 Ministero dei Beni e delle Attivitaculturei e del Turismo 获得的分级。

  • API 现在支持以下错误：

    错误类型 错误详情 说明
    badRequest invalidImage 如果提供的图片内容无效，thumbnails.set 方法会返回此错误。
    forbidden videoRatingDisabled 如果被评视频的所有者停用了视频的评分，videos.rate 方法会返回此错误。

2013 年 8 月 27 日

此更新包含以下更改：

  • 新的 watermark 资源用于标识在播放指定频道的视频期间显示的图片。您还可以指定图片要链接到的目标频道以及时间详情，这些信息将决定水印何时在视频播放期间显示以及显示多长时间。

    watermarks.set 方法可上传并设置频道的水印图片。watermarks.unset 方法可删除频道的水印图片。

    错误文档介绍了 API 专门针对 watermarks.set 和 watermarks.unset 方法支持的错误消息。

  • channel 资源的新 statistics.hiddenSubscriberCount 属性包含一个布尔值，用于指明频道的订阅人数是否处于隐藏状态。因此，如果频道的订阅人数是公开显示的，则该属性的值为 false。

  • playlists.list 方法现在支持 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 参数。其他几种方法已经支持这两个参数。

  • videos.list 方法现在支持 regionCode 参数，该参数标识应检索图表的内容区域。此参数只能与 chart 参数结合使用。此参数值是 ISO 3166-1 alpha-2 国家/地区代码。

  • error documentation 描述了以下新的常见请求错误（使用多种 API 方法时可能会出现错误）：

    错误类型 错误详情 说明
    forbidden insufficientPermissions 为请求提供的 OAuth 2.0 令牌关联的范围不足以访问请求的数据。

2013 年 8 月 15 日

此更新包含以下更改：

  • channel 资源的 invideoPromotion 对象具有以下新属性和更新后的属性：

  • subscriptions.list 方法现在支持 onBehalfOfContentOwner 和 onBehalfOfContentOwnerChannel 参数。其他几种方法已经支持这两个参数。

  • 在 thumbnails.set 请求的 API 响应中，kind 属性值已从 youtube#thumbnailListResponse 更改为 youtube#thumbnailSetResponse。

  • 为以下方法添加了代码示例：

    请注意，playlistItems.insert 方法的 Python 示例也已被移除，因为它演示的功能现在由 videos.rate 方法处理。

  • error documentation 描述了以下新的请求上下文错误，支持 mine 请求参数的任何 API 方法都可能会出现此错误：

    错误类型 错误详情 说明
    badRequest invalidMine mine 参数不能用于通过身份验证的用户是 YouTube 合作伙伴的请求。您应该移除 mine 参数，通过移除 onBehalfOfContentOwner 参数验证 YouTube 用户的身份，或者提供 onBehalfOfContentOwnerChannel 参数（如果适用于所调用的方法），充当合作伙伴的频道之一。

2013 年 8 月 8 日

此更新包含以下更改：

2013 年 7 月 30 日

此更新包含以下更改：

  • 在 channelBanner 资源中，kind 属性的值已从 youtube#channelBannerInsertResponse 更改为 youtube#channelBannerResource。该资源会在响应 channelBanners.insert 请求时返回。

  • channel 资源的新 brandingSettings.channel.profileColor 属性可指定与频道内容相得益彰的突出颜色。此属性值是一个井号 (#)，后跟一个包含六个字符的十六进制字符串，例如 #2793e6。

  • 该 API 现在支持指定订阅是针对频道的所有活动，还是仅针对新上传的视频。subscription 资源的新 contentDetails.activityType 属性用于标识订阅者将收到通知的活动类型。有效的属性值为 all 和 uploads。

  • videos.list 方法支持使用新参数检索 YouTube 上最热门视频排行榜：

    • chart 参数用于标识您要检索的图表。目前唯一支持的值是 mostPopular。请注意，chart 参数是一个过滤条件参数，这意味着它不能与其他过滤条件参数（id 和 myRating）在同一请求中使用。
    • videoCategoryId 参数用于标识系统应检索其图表的视频类别。此参数只能与 chart 参数结合使用。默认情况下，排行榜不仅限于特定类别。

  • video 资源的新 topicDetails.relevantTopicIds[] 属性提供了与视频或视频内容相关的 Freebase 主题 ID 列表。这些主题的主题可能会在视频中提及或出现。

  • video 资源的 recordingDetails.location.elevation 属性已重命名为 recordingDetails.location.altitude，其 fileDetails.recordingLocation.location.elevation 属性已重命名为 fileDetails.recordingLocation.location.altitude。

  • video 资源的 contentDetails.contentRating 对象指定视频在不同分级制度下获得的分级，包括 MPAA 分级、TVPG 分级等。现在，对于各个分级制度，该 API 支持一个分级值，用于表示视频未进行分级。请注意，对于 MPAA 分级，“未分级”评级通常用于标识影片的剪辑版本已获得官方评级的未剪辑版本。

  • video 资源的新 contentDetails.contentRating.ytRating 属性用于标识有年龄限制的内容。如果 YouTube 认为视频包含不适合未满 18 周岁的用户观看的内容，则该属性的值为 ytAgeRestricted。如果该属性不存在或属性值为空，则表示相应内容尚未被标识为有年龄限制。

  • channels.list 方法的 mySubscribers 参数已废弃。使用 subscriptions.list 方法及其 mySubscribers 参数检索已验证用户频道的订阅者列表。

  • channelBanners.insert、channels.update、videos.getRating 和 videos.rate 方法现在支持 onBehalfOfContentOwner 参数。该参数表示经过身份验证的用户是在代表参数值中指定的内容所有者进行操作。

  • channels.update 方法的文档已更新，以反映该方法可用于更新 channel 资源的 brandingSettings 对象及其子属性这一事实。此外，该文档现在还列出了更新后的属性列表，您可为 channel 资源的 invideoPromotion 对象设置这些属性。

  • error documentation描述了以下新错误：

    错误类型 错误详情 说明
    forbidden accountDelegationForbidden 此错误并非特定于 API 方法。它表示经过身份验证的用户无权代表指定的 Google 账号执行操作。
    forbidden authenticatedUserAccountClosed 此错误并非特定于 API 方法。它表示已验证用户的 YouTube 账号已关闭。如果用户是以另一个 Google 账号的名义进行操作，则此错误表示另一个账号已关闭。
    forbidden authenticatedUserAccountSuspended 此错误并非特定于 API 方法。它表示已验证用户的 YouTube 账号已暂停。如果用户是代表其他 Google 账号执行操作，则此错误会指明该账号已被中止。
    forbidden authenticatedUserNotChannel 此错误并非特定于 API 方法。它表示 API 服务器无法识别与 API 请求关联的渠道。如果请求获得授权并使用 onBehalfOfContentOwner 参数，您还应设置 onBehalfOfContentOwnerChannel 参数。
    forbidden cmsUserAccountNotFound 此错误并非特定于 API 方法。该内容管理系统用户无权代表指定的内容所有者执行操作。
    notFound contentOwnerAccountNotFound 此错误并非特定于 API 方法。找不到指定的内容所有者账号。
    badRequest invalidPart 此错误并非特定于 API 方法。请求的 part 参数指定不能同时写入的部分。
    badRequest videoChartNotFound 如果请求指定的视频图表不受支持或不可用，videos.list 方法会返回此错误。
    notFound videoNotFound videos.update 方法会返回此错误，表示找不到您尝试更新的视频。检查请求正文中 id 属性的值，确保其正确无误。

2013 年 6 月 10 日

此更新包含以下更改：

  • 借助 channels.list 方法的新 forUsername 参数，您可以通过指定频道的 YouTube 用户名来检索其相关信息。

  • activities.list 方法现在支持 regionCode 参数，该参数会指示 API 返回与指定国家/地区相关的结果。当授权用户之前在 YouTube 上的活动未提供足够的信息来生成活动供稿时，YouTube 会使用此值。

  • 播放列表资源现在包含 snippet.tags 属性。该属性只会返回给要检索有关自己播放列表的数据的授权用户。获授权的用户还可以在调用 playlists.insert 或 playlists.update 方法时设置播放列表标签。

  • onBehalfOfContentOwner 参数以前适用于 channels.list 和 search.list 方法，现在也适用于 videos.insert、videos.update 和 videos.delete 方法。请注意，在调用 videos.insert 方法时使用此参数时，请求还必须为新的 onBehalfOfContentOwnerChannel 参数指定一个值，用于标识视频将添加到的频道。频道必须与 onBehalfOfContentOwner 参数指定的内容所有者相关联。

    该参数表明请求的授权凭据标识了代表参数值中指定的内容所有者的 YouTube 内容管理系统用户。用户进行身份验证时使用的内容管理系统账号必须与指定的 YouTube 内容所有者相关联。

    此参数适用于拥有和管理多个不同 YouTube 频道的内容合作伙伴。借助该参数，这些合作伙伴只需进行身份验证一次，即可访问其所有视频和频道数据，而无需为每个频道提供身份验证凭据。

    具体而言，就此版本而言，该参数现在可让内容合作伙伴在其拥有的任何 YouTube 频道中插入、更新或删除视频。

  • error documentation描述了以下新错误：

    错误类型 错误详情 说明
    forbidden insufficientCapabilities 此错误并非特定于 API 方法。这表明调用该 API 的 CMS 用户没有足够的权限执行所请求的操作。此错误与使用 onBehalfOfContentOwner 参数有关，多种 API 方法都支持该参数。
    unauthorized authorizationRequired 如果请求使用了 home 参数，但未正确授权，则 activities.list 方法会返回此错误。

  • 在 channels 资源中，invideoPromotion.channelId 属性已移除，因为渠道 ID 已使用资源的 id 属性指定。

  • 新的使用频道 ID 指南介绍了该 API 如何使用频道 ID。如果开发者从旧版 API 迁移过来，并且其应用的应用需要向 default 用户请求内容，或依赖每个 YouTube 频道都有唯一的用户名这一概念，那么本指南会非常有用。

2013 年 5 月 22 日

此更新包含以下更改：

2013 年 5 月 14 日

此更新包含以下更改：

  • 现在，独立页面会列出 Java、.NET、PHP 和 Ruby 的代码示例。

  • 列出 Python 代码示例的页面现在包含有关添加订阅、创建播放列表和更新视频的示例。

2013 年 5 月 10 日

此更新包含以下更改：

2013 年 5 月 8 日

此更新包含以下更改：

  • 频道资源现在支持 inVideoPromotion 对象，该对象封装了与频道相关联的推广活动的相关信息。当频道播放视频时，频道可以使用视频内推广广告系列在视频播放器中显示推荐视频的缩略图。

    如需检索此数据，您可以在 channels.list 请求的 part 参数值中添加 invideoPromotion。

  • 新的 channels.update 方法可用于更新频道的视频内推广广告系列数据。请注意，此方法仅支持更新 channel 资源的 invideoPromotion 部分，尚不支持更新该资源的其他部分。

2013 年 5 月 2 日

此更新包含以下更改：

  • 频道资源现在支持 status.isLinked 属性，该属性用于指明频道数据是否标识已经与 YouTube 用户名或 Google+ 账号相关联的用户。拥有其中一个链接的用户已经拥有公开的 YouTube 身份，这是执行某些操作（如上传视频）的前提条件。

  • 订阅资源现在支持 subscriberSnippet 部分。该对象封装了订阅者频道的片段数据。

  • 该 API 现在支持 videos.getRating 方法，该方法可检索经过身份验证的用户对一个或多个视频的列表做出的评分。

  • 借助 videos.list 方法的新 myRating 参数，您可以检索经过身份验证的用户评分为 like 或 dislike 的视频列表。

    myRating 参数和 id 参数现在都被视为过滤器参数，这意味着 API 请求必须明确指定其中一个参数。（以前，id 参数是此方法的必需参数。）

    对于尝试检索视频评分信息但未获得相应授权的请求，该方法会返回 forbidden 错误。

  • 随着 myRating 参数的引入，videos.list 方法也进行了更新，以支持分页。但请注意，只有使用 myRating 参数的请求才支持分页参数。（使用 id 参数的请求不支持分页参数和信息。）

    • maxResults 参数用于指定 API 在结果集中可返回的视频数量上限，pageToken 参数用于标识结果集中要检索的特定网页。

    • 为响应 videos.list 请求而返回的 youtube#videoListResponse 资源现在包含 pageInfo 对象，该对象包含结果总数和当前结果集中包含的结果数等详细信息。youtube#videoListResponse 资源还可以包含 nextPageToken 和 prevPageToken 属性，这两个属性都提供了一个令牌，可用于检索结果集中的特定页面。

  • videos.insert 方法支持以下新参数：

    • autoLevels - 将此参数值设为 true，即可指示 YouTube 自动增强视频的光线和色彩。
    • stabilize - 将此参数值设为 true，即可指示 YouTube 通过消除相机移动导致的抖动来调整视频。

  • 为以下资源的 snippet 添加了 channelTitle 属性：

    • playlistItem - 该属性用于指定添加了播放列表项的频道的名称。
    • playlist - 该属性用于指定创建播放列表的频道的名称。
    • subscription - 该属性用于指定订阅频道的名称。

  • 为以下方法添加了代码示例：

  • 借助 subscriptions.list 方法的新 mySubscribers 参数，您可以检索当前经过身份验证的用户的订阅者列表。此参数只能在适当授权的请求中使用。

    注意：此功能旨在替换 channels.list 方法当前支持的 mySubscribers 参数。该参数将被弃用。

  • 在 video 资源中，属性值 unspecified 不再是以下任何属性的可能值：

  • 包含意外参数的 API 请求现在会返回 badRequest 错误，而报告的错误原因是 unexpectedParameter。

  • 当播放列表包含的允许项数已达到上限时，playlistItems.insert 方法返回的错误。现在，错误会报告为 forbidden 错误，错误原因为 playlistContainsMaximumNumberOfVideos。

2013 年 4 月 19 日

此更新包含以下更改：

2013 年 3 月 12 日

此更新包含以下更改：

  • 为以下资源的 snippet 添加了 channelTitle 属性：

    • activity - 该属性指定负责相应 activity 的渠道的名称。
    • search - 该属性用于指定与搜索结果标识的资源相关联的渠道名称。
    • video - 该属性用于指定上传视频的频道的名称。

  • search.list 方法支持以下新参数：

    • channelType 参数可让您将搜索频道限制为检索所有频道或仅检索节目。

    • videoType 参数可让您将搜索限制为检索所有视频，或仅检索电影或节目剧集。

  • video 资源 recordingDetails 部分的定义已更新，指出只有在设置了视频的地理位置数据或录制时间后，系统才会为该视频返回该对象。

  • playlistItems.update 方法现在会返回 invalidSnippet 错误，如果 API 请求未指定有效的代码段，则返回此错误。

  • 有些 API 方法支持专用于 YouTube 内容合作伙伴的新参数。YouTube 内容合作伙伴包括影视工作室、唱片公司，以及在 YouTube 上提供内容的其他内容创作者。

    • onBehalfOfContentOwner 参数用于指明请求的授权凭据可识别代表参数值中指定的内容所有者执行操作的 YouTube 内容管理系统用户。用户进行身份验证时使用的内容管理系统账号必须与指定的 YouTube 内容所有者相关联。

      此参数适用于拥有和管理多个不同 YouTube 频道的内容合作伙伴。借助该参数，这些合作伙伴只需进行身份验证一次，即可访问其所有视频和频道数据，而无需为每个频道提供身份验证凭据。

      channels.list、search.list、videos.delete、videos.list 和 videos.update 方法都支持此参数。

    • channels.list 方法支持的 managedByMe 参数用于指示 API 返回由内容所有者拥有的所有频道（由 onBehalfOfContentOwner 参数指定）。

    • search.list 方法支持的 forContentOwner 参数用于指示 API 将搜索结果限制为仅包含由 onBehalfOfContentOwner 参数指定的内容所有者所拥有的资源。

2013 年 2 月 25 日

此更新包含以下更改：

  • 对于 video 资源，API 支持几个新的部分和属性：

    • 新的 fileDetails、processingDetails 和 suggestions 部分可为视频所有者提供有关其上传视频的信息。此数据对于支持视频上传且包含以下内容的应用非常有用：

      • 处理状态和进度
      • 处理视频时遇到的错误或其他问题
      • 缩略图的可用性
      • 关于改进视频或元数据质量的建议
      • 上传到 YouTube 的原始文件的详细信息

      只有视频拥有者才能检索到所有这些部分。以下列表简要介绍了新部分，而 video 资源文档定义了每个部分包含的所有属性。

      • fileDetails 对象包含有关上传到 YouTube 的视频文件的信息，包括文件的分辨率、时长、音频和视频编解码器、视频流比特率等。

      • processingProgress 对象包含 YouTube 对上传视频文件的处理进度信息。该对象的属性用于标识当前的处理状态，并估算 YouTube 处理完视频还剩余多少时间。此部分还指出视频是否提供不同类型的数据或内容，例如文件详细信息或缩略图。

        该对象旨在用于轮询，以便视频上传者可以跟踪 YouTube 在处理上传的视频文件方面的进度。

      • suggestions 对象包含一些建议，可帮助您找出有助于提升所上传视频质量或元数据的优化建议。

    • contentDetails 部分包含四个新属性。可以使用未经身份验证的请求检索这些属性。

      • dimension - 表示视频提供 2D 还是 3D 格式。
      • definition – 指明视频是以标清模式还是高清模式播放的。
      • caption - 表示视频是否有字幕。
      • licensedContent – 表示视频是否包含已由 YouTube 内容合作伙伴声明的内容。

    • status 部分包含两个新属性。视频所有者可以在插入或更新视频时同时设置这两个属性的值。这些属性也可通过未经身份验证的请求进行检索。

      • embeddable – 表示视频是否可以嵌入其他网站。
      • license - 指定视频的许可。有效值为 creativeCommon 和 youtube。

  • 针对 videos.list、videos.insert 和 videos.update 方法更新了 part 参数的定义，以列出上述新添加的部分以及无意中省略的 recordingDetails 部分。

  • channel 资源的新 contentDetails.googlePlusUserId 属性用于指定与频道关联的 Google+ 个人资料 ID。此值可用于生成指向 Google+ 个人资料的链接。

  • 现在，每个缩略图对象都会指定图片的宽度和高度。目前，缩略图图片会在 activity、channel、playlist、playlistItem、search result、subscription 和 video 资源中返回。

  • playlistItems.list 现在支持 videoId 参数，该参数可与 playlistId 参数结合使用，以仅检索代表指定视频的播放列表项。

    如果在播放列表中找不到该参数所标识的视频，则 API 会返回 notFound 错误。

  • 错误文档介绍了一种新的 forbidden 错误，它表示请求未获得针对请求的操作的适当授权。

  • channel 资源的 snippet.channelId 属性已移除。资源的 id 属性提供相同的值。

2013 年 1 月 30 日

此更新包含以下更改：

  • 新的错误页面列出了 API 可以返回的错误。该页面包含多种不同 API 方法可能会出现的常规错误，以及特定于方法的错误。

2013 年 1 月 16 日

此更新包含以下更改：

  • 下方列表中所示方法和语言的代码示例现已可用：

  • 现在，当 YouTube 将视频添加到自动生成的 YouTube 频道时，activity 资源可以报告 channelItem 操作。（YouTube 会通过算法识别 YouTube 网站上流量较高的主题，并自动为这些主题生成频道。）

  • 以下 search.list 参数已更新：

    • q 参数不再被指定为过滤器，这意味着 ....
    • relatedToVideo 参数已重命名为 relatedToVideoId。
    • published 形参已替换为 publishedAfter 和 publishedBefore 这两个新形参，如下所述。

  • search.list 方法支持以下新参数：

    参数名称 值 说明
    channelId string 返回由指定渠道创建的资源。
    publishedAfter datetime 返回在指定时间之后创建的资源。
    publishedBefore datetime 返回在指定时间之前创建的资源。
    regionCode string 返回指定国家/地区的资源。
    videoCategoryId string 过滤视频搜索结果，使其仅包含与指定视频类别相关的视频。
    videoEmbeddable string 过滤视频搜索结果，使其仅包含可在网页上的嵌入式播放器中播放的视频。将参数值设为 true 可仅检索可嵌入视频。
    videoSyndicated string 过滤视频搜索结果，使其仅包含可在 YouTube.com 以外的地方播放的视频。将参数值设为 true 可仅检索整合的视频。

  • 有些 API 资源支持新属性。下表列出了这些资源及其新属性：

    资源 属性名称 值 说明
    activity contentDetails.playlistItem.playlistItemId string YouTube 分配的播放列表项 ID，用于唯一标识播放列表中的内容。
    activity contentDetails.channelItem object 一个对象，包含添加到渠道的资源的相关信息。仅当 snippet.type 为 channelItem 时，此属性才会显示。
    activity contentDetails.channelItem.resourceId object 用于标识添加到渠道的资源的对象。与其他 resourceId 属性一样，它包含用于指定资源类型（例如视频或播放列表）的 kind 属性。它还仅包含以下属性之一：videoId、playlistId 等，用于指定该资源的唯一标识 ID。
    channel status object 此对象用于封装有关频道隐私状态的信息。
    channel status.privacyStatus string 频道的隐私状态。有效值为 private 和 public。
    playlist contentDetails object 此对象包含有关播放列表内容的元数据。
    playlist contentDetails.itemCount unsigned integer 播放列表中的视频数量。
    playlist player object 此对象包含您在嵌入式播放器中播放播放列表时需要使用的信息。
    playlist player.embedHtml string <iframe> 标记，用于嵌入用于播放播放列表的视频播放器。
    video recordingDetails object 此对象用于封装标识或描述视频录制地点和时间的信息。
    video recordingDetails.location object 此对象包含与视频相关联的地理定位信息。
    video recordingDetails.location.latitude double 纬度（以度为单位）。
    video recordingDetails.location.longitude double 经度（以度为单位）。
    video recordingDetails.location.elevation double 地球上空的海拔高度（以米为单位）。
    video recordingDetails.locationDescription string 视频录制地点的文字说明。
    video recordingDetails.recordingDate datetime 录制视频的日期和时间。该值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。

  • 现在，一些 API 方法的文档确定了必须在请求正文中指定的属性或根据请求正文中的值更新的属性。下表列出了这些方法以及必需的或可修改的属性。

    注意：其他方法的文档可能已经列出了必需属性和可修改属性。

    方法 属性
    activities.insert 必需属性：
    • snippet.description
    可修改的属性：
    • snippet.description
    • contentDetails.bulletin.resourceId
    playlists.update 必需属性：
    • id
    playlistItems.update 必需属性：
    • id
    videos.update 必需属性：
    • id

  • 如果您尝试创建或更新播放列表与同一频道中已存在的播放列表具有相同的标题，API 将不再报告 playlistAlreadyExists 错误。

  • 有些 API 方法支持新的错误类型。下表列出了该方法和新增的支持错误：

    方法 错误类型 错误详情 说明
    guideCategories.list notFound notFound 找不到由 id 参数标识的指南类别。使用 guideCategories.list 方法检索有效值列表。
    playlistItems.delete forbidden playlistItemsNotAccessible 该请求未获得适当授权，无法删除指定的播放列表项。
    videoCategories.list notFound videoCategoryNotFound 找不到由 id 参数标识的视频类别。使用 videoCategories.list 方法检索有效值列表。