修订历史记录

本页面列出了 YouTube Data API (v3) 的变更和文档更新。

2026 年 11 月 2 日

通过未经验证的 API 项目中的 videos.insert 方法上传的视频不再仅限私享观看模式。此项变更推翻了 2020 年 7 月 28 日宣布的政策，该政策规定，在 2020 年 7 月 28 日之后创建的未经验证的 API 项目中上传的视频，在项目完成审核之前，只能以私享模式观看。

如果您未在 videos.insert 请求中为 status.privacyStatus 属性指定值，则上传的视频的隐私状态默认为 public。如 YouTube 帮助中心所述，根据创作者账号设置，某些上传内容可能会默认设为private。

2026 年 10 月 15 日

videos.list 方法已阐明，status.selfDeclaredMadeForKids 和 status.madeForKids 属性仅在请求中指定时才会更新，如果省略则不会被覆盖。

2026 年 9 月 30 日

comments 资源定义已更新，其中包含新的 snippet.imageUrl 属性，该属性提供附加到评论的图片或 GIF 动画的网址。

此功能将于 2026 年 11 月面向所有用户推出。

2026 年 9 月 14 日

此更新包含以下更改：

  • thumbnails.set 方法说明已更新，指出上传的缩略图的文件大小上限已从 2MB 增加到 50MB。
  • playlistImages.insert 方法说明已更新，其中指出上传图片的文件大小上限已从 2MB 增加到 50MB。

2026 年 9 月 11 日

activities、liveBroadcasts、playlistItems、playlists、search 和 videos 资源的参考文档中更新了 snippet.thumbnails.(key) 属性的定义，指出现在某些视频可以使用更高分辨率的缩略图尺寸：fhd (1080p)、qhd (1440p) 和 uhd (4K)。

2026 年 9 月 1 日

videos.getRating 方法现在接受 https://www.googleapis.com/auth/youtube.readonly 授权范围。

2026 年 8 月 27 日

YouTube 将统一所有视频格式（长视频、直播和 Shorts 短视频）的公开观看次数统计方法。只要视频开始播放，YouTube 就会统计公开观看次数。

创收资格条件和大多数核心效果指标不受影响，因为它们仍然基于互动指标。创作者的收入仍将根据“感兴趣的 Shorts 观看次数”和“感兴趣的观看时长”计算，您可以在 YouTube 数据分析 > 高级模式中查看这些数据。

YouTube 合作伙伴计划的资格要求没有变化。YouTube 合作伙伴计划的加入要求现在也将称为“有效 Shorts 观看次数”和“有效观看时长”（之前称为“有效公开 Shorts 观看次数”和“有效公开视频观看时长”）。

如需了解详情，请参阅了解 YouTube 内容的表现。

指标 状态 触发器 用途
查看 已更新 视频从第一帧开始播放（包括自动播放、将指针悬停在视频上以及点击/点按播放）。 标准公开观看次数。
感兴趣的观看 未更改 播放继续，超过第一帧，或者用户点击/点按播放。 通过 YouTube 合作伙伴计划创收、大部分核心分析功能（点击率、平均观看时长）以及互动报告。
缩略图展示 未更改 缩略图在没有互动或自动播放的情况下显示。 衡量 Feed 级曝光度和打包情况。

API 文档更新：更新了频道和视频参考文档中 viewCount 字段的说明。

2026 年 8 月 6 日

此更新包含以下更改：

  • 由于 API 不会返回 activities.contentDetails 下的 contentDetails.like 和 contentDetails.favorite 字段，因此我们已从公开文档中移除了对这些字段的所有引用。

2026 年 7 月 7 日

此更新包含以下更改：

该 API 现在支持 videos 资源中的 brandPartner 部分。此部分包含与视频关联的品牌合作伙伴的详细信息，适用于由创作者发起的品牌合作伙伴访问权限。

调用以下方法时，可以指定 brandPartner 部分：

brandPartner 对象包含以下字段：

  • channelId：品牌合作伙伴的外部频道 ID。
  • channelHandle：品牌合作伙伴的频道标识名。
建立关联时，必须设置 channelId 或 channelHandle，但响应中仅返回 channelId。

2026 年 6 月 23 日

此更新包含以下更改：

  • liveChatMessages 下对 messageDeletedEvent 和 messageRetractedEvent 资源类型（及其对应的 messageDeletedDetails 和 messageRetractedDetails 对象）的所有引用均已移除，因为 API 不会返回这些事件。

2026 年 6 月 3 日

此更新包含以下更改：

该 API 现在支持一种新方法 videos.batchGetStats，该方法可检索与 API 请求参数匹配的视频统计信息列表。

调用此方法会在其自己的精细配额存储桶中产生 1 个单位的配额费用。该方法的默认配额为每天 10,000 个单位。

2026 年 6 月 1 日

YouTube Data API 正在过渡到涵盖较小方法集的精细配额系统，首先从 videos.insert 和 search.list 开始。

此次更新简化了配额增加流程，让 YouTube 能够更轻松地根据特定方法的使用情况验证和批准请求。此次过渡也是我们致力于保障平台稳定性和安全性的关键举措，旨在确保每位开发者都能在受保护的生态系统中运营，同时保留其获批用例所需的访问权限级别。

对 videos.insert 和 search.list 方法的 API 调用将计入各自的配额桶。对所有其他方法的 API 调用将计入现有配额存储桶。开发者可以在 Google Cloud 控制台中查看配额限制，并可以通过配额扩展表单申请更多配额。

2025 年 12 月 4 日

YouTube Data API 文档和配额计算器已更新，反映了视频上传配额费用从大约 1,600 个单位更改为大约 100 个单位。

2025 年 7 月 10 日

自 2025 年 7 月 21 日起，YouTube 将调整 video.list 方法的 mostPopular 图表返回的内容。过去，mostPopular排行榜反映的是“时下流行”列表中的视频。现在，mostPopular排行榜将收录“时下流行音乐”“时下流行电影”和“时下流行游戏”排行榜中的视频。此次 API 变更与 YouTube “时下流行”页面的弃用同步进行。

2025 年 3 月 26 日

自 2025 年 3 月 31 日起，YouTube 将更改 Shorts 观看次数的统计方式。过去，短视频的播放时长达到一定的秒数之后，系统才会统计一次 Shorts 观看。现在，“观看次数”这项指标将统计短视频开始播放或重放的次数，而且没有最低观看时长要求。 了解详情

自 2025 年 3 月 31 日起，Data API 中的以下字段将根据此变更返回 Shorts 观看次数：

  • channels.statistics.viewCount
  • videos.statistics.viewCount

2024 年 10 月 30 日

该 API 现在支持识别包含逼真的加工或合成 (A/S) 内容的视频。详细了解与 A/S 内容相关的 YouTube 政策。

A/S 内容的示例包括：

  • 呈现真实人物的言论或行为，但实际并非本人言行
  • 加工有关真实事件或地点的视频片段
  • 生成逼真但实际并不存在的场景

如需指明视频是否包含 A/S 内容，请设置 status.containsSyntheticMedia 属性。调用 videos.insert 或 videos.update 方法时，可以设置此属性。如果设置了该属性，则会在 video 资源中返回该属性。

2024 年 4 月 30 日

注意：这是一则弃用公告。

此更新包含以下更改：

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

2024 年 3 月 13 日

注意：这是一则弃用公告。

此更新包含以下更改：

captions.insert 和 captions.update 方法的 sync 参数已废弃。YouTube 将于 2024 年 4 月 12 日停止支持该参数。

由于这项变更，开发者在插入或更新字幕轨道时必须包含时间信息，否则上传将会失败。

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 日

由于 videoId 资源未通过 API 调用返回，因此 Comments 下对 videoId 资源的所有引用均已移除。

2023 年 9 月 12 日

注意：这是一则弃用公告。

comments.markAsSpam 方法已弃用多年。YouTube 已不再支持此方法，并且该方法也不再通过 API 受支持。

所有引用 comments.markAsSpam 方法的文档中都添加了弃用通知。

2023 年 8 月 22 日

search.list 方法现在支持 videoPaidProductPlacement 参数。借助此参数，您可以过滤搜索结果，以便仅包含创作者已指明包含付费宣传内容的视频。

2023 年 8 月 18 日

video 资源的 liveStreamingDetails.concurrentViewers 的定义已更新，其中指出 YouTube Data API 返回的同时观看人数可能与通过 YouTube 数据分析提供的经过处理、去垃圾内容的同时观看人数不同。YouTube 帮助中心提供了有关直播指标的更多信息。

2023 年 8 月 7 日

正如 2023 年 6 月 12 日所宣布，search.list 方法的 relatedToVideoId 参数已被弃用。该参数不再受支持，并且对该参数的引用已从 API 文档中移除。

2023 年 6 月 28 日

thumbnails.set 方法现在支持 uploadRateLimitExceeded 错误，该错误表示频道在过去 24 小时内上传了太多缩略图，应稍后再试。

2023 年 6 月 12 日

注意：这是一则弃用公告。

search.list 方法的 relatedToVideoId 参数已弃用。YouTube 将于 2023 年 8 月 7 日停止支持该参数。

目前，search.list 方法的文档中已添加弃用通知。此参数将于 2023 年 8 月 7 日或之后从 search.list 文档中完全移除。

此外，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 日起，YouTube 将停止支持旧版字幕轨道 ID。届时，使用旧字幕轨道 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 日起不公开。这意味着，只有当 API 请求由视频所有者进行身份验证时，该属性才会包含在 videos.list 端点的 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 仍会创建一个新的播放列表。今后，在这种情况下，系统将不会创建播放列表，并且 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[] 属性已被弃用。YouTube 已不再支持此属性，因此，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 嵌入式播放器将内容嵌入到 API 客户端之前，您必须使用 YouTube Data API 服务检查内容的状态。

新的查找视频的 MadeForKids 状态视频指南介绍了如何使用 YouTube Data API 服务查找视频的 MFK 状态。

除了这些变更之外，嵌入式播放器参数文档中还添加了一条提醒，说明如果您启用自动播放，则无需用户与播放器进行任何互动即可播放；因此，系统会在网页加载时收集和分享播放数据。

2020 年 10 月 8 日

此更新涵盖与 channel 资源相关的三项细微更改：

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

2020 年 9 月

注意：这是一则弃用公告。

此更新涵盖以下 API 变更。所有变更都将于 2020 年 9 月 9 日（即本公告发布之日）或之后生效。因此，开发者不应再依赖下面列出的任何 API 功能。

  • 以下 API 资源、方法、参数和资源属性将立即弃用，并将在本公告发布之日或之后停止运行：
  • 如果 API 请求将 managedByMe 参数设置为 true，则 channels.list 方法的 API 响应将不再包含 prevPageToken 属性。此变更不会影响其他 channels.list 请求的 prevPageToken 属性，也不会影响任何请求的 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 日

注意：这是对之前弃用公告的更新。

频道公告功能现已完全弃用。此项变更最初于 2020 年 4 月 17 日公布，现已生效。因此，activities.insert 方法不再受支持，activities.list 方法不再返回频道公告。如需了解详情，请访问 YouTube 帮助中心。

2020 年 4 月 17 日

注意：这是一则弃用公告。

YouTube 即将弃用频道公告功能。因此，activities.insert 方法将被弃用，activities.list 方法将停止返回频道公告。这些变更将于 2020 年 5 月 18 日或之后在 API 中生效。如需了解详情，请访问 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 称之为“面向儿童的内容”）。如需详细了解“面向儿童的内容”，请访问 YouTube 帮助中心。

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

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

    对于频道，可以在调用 channels.update 方法时设置此属性。对于视频，可以在调用 videos.insert 或 videos.update 方法时设置此属性。

    请注意，只有在频道所有者授权 API 请求的情况下，此属性才会包含在包含 channel 或 video 资源的 API 响应中。
  • 借助 madeForKids 属性，任何用户都可以检索频道或视频的“面向儿童”状态。例如，状态可能根据 selfDeclaredMadeForKids 属性的值确定。如需详细了解如何为频道、视频或直播设置观众群，请参阅 YouTube 帮助中心。

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

2019 年 9 月 10 日

API 参考文档已更新，以反映 YouTube 上订阅人数报告方式的变化，以及 API 响应中的相应变化。由于这项变更，对于订阅人数超过 1,000 人的频道，YouTube Data API 服务返回的订阅人数会向下舍入到三位有效数字。此变更会影响 channel 资源的 statistics.subscriberCount 属性。

注意：即使在用户发送有关其自身频道数据的授权请求时，此更改也会影响此属性值。频道所有者仍可在 YouTube 工作室中查看确切的订阅人数。

例如，如果某个频道有 123,456 位订阅者，则 statistics.subscriberCount 属性将包含值 123000。 下表举例说明了订阅人数在 API 响应中如何进行四舍五入，以及在其他公开显示的 YouTube 界面中如何进行缩写：

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

2019 年 4 月 4 日

此更新包含以下更改：

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

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

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

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

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

  • 代码示例工具也已更新，采用了全新界面，提供上述所有相同功能。借助该工具，您可以探索不同方法的应用场景、将值加载到 APIs Explorer 中，以及打开全屏 APIs Explorer 以获取 Java、JavaScript、PHP 和 Python 语言的代码示例。

    与此同时，我们移除了之前列出 Java、JavaScript、PHP 和 Python 可用代码示例的页面。

  • Java、JavaScript、PHP 和 Python 的快速入门指南已更新。修订后的指南说明了如何使用 API 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 的说明。此外，我们还移除了 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 Web 服务器应用提供了完整的代码示例，这些应用使用的授权流程略有不同。如需查看完整示例（以及此项更改），请执行以下操作：

    1. 前往互动式代码段工具或任何 API 方法（例如 channels.list 方法）的文档。
    2. 点击代码示例上方的 Python 标签页。
    3. 点击标签页上方的切换开关，即可从查看代码段切换到查看完整示例。
    4. 该标签页现在应显示使用 InstalledAppFlow 授权流程的完整代码示例。示例上方的说明对此进行了说明，并提供了指向 Web 服务器应用示例的链接。
    5. 点击链接，切换到 Web 服务器示例。该示例使用 Flask Web 应用框架和不同的授权流程。

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

2017 年 8 月 29 日

此更新包含以下更改：

  • search.list 方法的 forContentOwner 参数定义已更新，现在注明如果该参数设置为 true，则 type 参数必须设置为 video。
  • search.list 方法的 regionCode 参数的定义已更新，以阐明该参数会将搜索结果限制为可在指定区域内观看的视频。
  • YouTube 更新了其品牌徽标和图标。您可以从品牌推广指南页面下载新的“developed with YouTube”徽标。该页面上还显示了其他新的 YouTube 徽标和图标，您可以从 YouTube 品牌网站下载这些徽标和图标。

2017 年 7 月 24 日

此更新包含以下更改：

  • iOS 平台现已推出新的 YouTube Data API 快速入门指南。本指南介绍了如何在用 Objective-C 或 Swift 编写的简单 iOS 应用中使用 YouTube Data API。
  • YouTube Data API 的交互式代码段工具现在包含说明该工具部分功能的文档：
    • 执行 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 方法的代码部分。完整示例包含该代码段以及用于授权和发送请求的样板代码。您可以复制完整示例，并通过命令行或本地 Web 服务器运行。

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

    请注意，在提供此工具的页面上，它已取代 APIs Explorer。（每个页面都会显示一个链接，以便您也可以选择在 APIs Explorer 中加载您正在处理的请求。）

  • Data API Code Snippets 工具也已更新，采用了新的界面，可提供上述所有相同功能。此页面上提供的主要新功能如下：

    • 支持写入数据的 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 列表切换为精选列表。受支持的主题 ID 的完整列表包含在 channel 和 video 资源的 topicDetails 属性中，以及 search.list 方法的 topicId 参数中。

请注意，精选列表有以下几项变更：

  • 以下主题已添加为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 个搁架；在设置定位数据的情况下，一个频道最多可以创建 100 个搁架。

      此外，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 相关的多项更改，包括自 2017 年 2 月 10 日起，支持的主题 ID 集将发生变化。我们将在 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 日生效的更新后的条款之外，此次更新还包含多份支持文档，旨在帮助解释开发者必须遵守的政策。

    更新后条款的修订历史记录中介绍了整套新文档。此外，未来对更新后的条款或这些支持文档所做的更改也会在该修订历史记录中进行说明。

  • 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 将返回空结果集。

  • 自 2016 年 9 月 12 日起，多个 API 字段和参数将被弃用：

    • activities.list 方法的 home 参数使授权用户能够检索将在该用户的 YouTube 首页上显示的活动动态。在 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、搜索结果、thumbnail 和 video 资源的 snippet.thumbnails.(key) 属性定义已更新，以说明某些视频还提供其他缩略图尺寸。

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

  • channelSection.list 方法的 part 参数的定义已更新，其中指出，targeting 部分可以消耗 2 个配额单位来检索。

  • 现在，当未经适当授权的请求尝试检索 video 资源的 fileDetails、processingDetails 或 suggestions 部分时，videos.list 方法会返回禁止 (403) 错误。这些部分仅对视频所有者可见。

2016 年 5 月 17 日

新的 Data API 代码段工具可为常见的 YouTube Data API 用例提供简短的代码段。目前，Apps 脚本、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，该 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 资源文档已更新，其中指出上传的频道横幅图片的建议尺寸为 2560 像素 x 1440 像素。最小尺寸（2048x1152 像素）未发生变化。

    • 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 属性指定了法国电影分级委员会 (Commission de classification cinematographique) 对视频的分级。此属性取代了现已弃用的 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 方法。此外，有些评论没有回复。

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

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

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

    请注意，调用 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 回调服务器可以接收 Atom 订阅源通知：

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

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

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

  • 该 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 支持但 v2 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 用户的用户活动动态。当有新频道订阅、视频被评分、分享、标记为收藏、评论或上传时，系统会发送通知。

      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 中支持的所有功能，这些功能将在当前 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 属性用于标识新西兰电影和文学分级办公室 (OFLC) 提供的视频分级，现在支持两个新分级：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 日

此更新包含以下更改：

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 - 频道所有者发布到频道活动动态中的播放列表
    • postedVideos - 频道所有者发布到频道活动动态中的视频
    • subscriptions - 频道所有者订阅的频道

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

  • watermark 资源的 position.cornerPosition 属性的定义已更新，其中指出水印始终显示在播放器的右上角。

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

  • 我们更新了在 API 响应中针对 search.list 调用返回的 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

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

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

    • brandingSettings.channel.description 属性的值长度上限为 1,000 个字符。
    • 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。

    • video 资源的新 snippet.liveBroadcastContent 属性用于指明视频是即将开始的直播还是正在进行的直播。下表说明了该属性的可能值：

      • upcoming - 视频是尚未开始的直播。
      • active - 视频是正在进行的直播。
      • none - 视频不是即将开始或正在进行的直播。对于仍可在 YouTube 上观看的已完成直播，此属性的值将为“completed”。

    • video 资源的新 liveStreamingDetails 属性是一个对象，其中包含有关实时视频广播的元数据。如需检索此元数据，请在 part 参数值的资源部分列表中添加 liveStreamingDetails。元数据包含以下新属性：

      如需检索此元数据，请在调用 videos.list、videos.insert 或 videos.update 方法时，在 part 参数值中添加 liveStreamingDetails。

    请注意，另外两个用于识别直播内容的功能已于 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 范围的授权令牌。此外，当 MCN 决定接受或拒绝频道时，或者在令牌签发之日起两周内，必须撤消使用该范围的所有令牌。

  • 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 Attivita Culturali 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 如果经过身份验证的用户是 YouTube 合作伙伴，则无法在请求中使用 mine 参数。您应移除 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 方法。CMS 用户无权代表指定的内容所有者执行操作。
    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 请求中将 invideoPromotion 包含在 part 参数值中，以检索此数据。

  • 新的 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 参数标识您要检索的结果集中的特定页面。

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

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

    • autoLevels - 将此参数值设置为 true，以指示 YouTube 自动增强视频的光线和色彩。
    • stabilize - 将此参数值设置为 true，以指示 YouTube 通过消除相机运动引起的抖动来调整视频。

  • channelTitle 属性已添加到以下资源的 snippet 中：

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

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

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

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

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

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

  • 当播放列表已包含允许的最大内容数量时，playlistItems.insert 方法返回的错误已更新。现在，该错误会报告为 forbidden 错误，错误原因为 playlistContainsMaximumNumberOfVideos。

2013 年 4 月 19 日

此更新包含以下更改：

2013 年 3 月 12 日

此更新包含以下更改：

  • channelTitle 属性已添加到以下资源的 snippet 中：

    • 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 方法都支持此参数。

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

    • forContentOwner 参数（受 search.list 方法支持）指示 API 限制搜索结果，使其仅包含 onBehalfOfContentOwner 参数指定的内容所有者所拥有的资源。

2013 年 2 月 25 日

此更新包含以下更改：

  • 该 API 支持 video 资源的多个新部分和属性：

    • 新的 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 日

此更新包含以下更改：

  • 现在，下表所示的方法和语言均有代码示例：

  • activity 资源现在可以报告 channelItem 操作，当 YouTube 将视频添加到自动生成的 YouTube 频道时，就会发生此操作。（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 方法检索有效值列表。