本页列出了 YouTube Data API (v3) 的更改和文档更新。订阅此更改日志。
2024 年 4 月 30 日
注意:这是弃用公告。
此更新包含以下更改:
该 API 不再支持插入或检索频道讨论的功能。此变化与 YouTube 网站上支持的功能一致,后者不支持向频道发布评论。
2024 年 3 月 13 日
注意:这是弃用公告。
此更新包含以下更改:
captions.insert
和 captions.update
方法的 sync
参数已弃用。自 2024 年 4 月 12 日起,YouTube 将不再支持该参数。
由于这项变更,开发者在插入或更新字幕轨道时必须添加时间信息,否则上传将会失败。
2024 年 3 月 12 日
此更新包含以下更改:
captions
资源的文档已更新,指出 snippet.name
字段允许的长度上限为 150 个字符。如果轨道名称超过该长度,API 会返回 nameTooLong
错误。
2024 年 3 月 7 日
注意:这是弃用公告。
channel
资源属性 brandingSettings.channel.moderateComments
已弃用。自 2024 年 3 月 7 日起,YouTube 将停止支持该参数。
2024 年 1 月 31 日
此更新包含以下更改:
借助 channels.list
方法的新 forHandle
参数,您可以通过指定频道的 YouTube 标识名来检索频道的相关信息。
2023 年 11 月 9 日
移除了对 Comments
下 videoId
资源的所有引用,因为未使用 API 调用返回 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
参数已弃用。自 2023 年 8 月 7 日起,YouTube 将停止支持该参数。
目前,我们在 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 平台上的私密性变更,自 2021 年 12 月 13 日起,video
资源的 statistics.dislikeCount
属性也将变为不公开状态。这意味着,只有在 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
资源支持两个新属性:
snippet.videoOwnerChannelId
属性用于标识上传了播放列表视频的频道的 ID。snippet.videoOwnerChannelTitle
属性用于标识上传了播放列表视频的频道的名称。
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 资源、方法、参数和资源属性将立即弃用,并将于本公告发布之日或之后停止使用:
- 以下
channel
资源属性:statistics.commentCount
属性brandingSettings.image
对象及其所有子属性brandingSettings.hints
列表及其所有子属性
channels.list
方法的categoryId
过滤器参数guideCategories
资源和guideCategories.list
方法
- 以下
-
如果 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 日
我们移除了与 part
参数相关的额外费用,从而简化了对 API 请求配额收费的流程。此后,我们将仅针对所调用的方法收取基本费用。您可以点击此处详细了解简化后的配额。
此项变更的影响是,大多数 API 调用的配额费用略低,而某些 API 调用的费用保持不变。这项变更不会增加任何 API 调用的费用。总体而言,可能的影响是,您分配的配额(可以在 Google Cloud 控制台中查看)会更进一步。
我们强烈建议所有开发者为自己的项目完成合规性审核,以确保能够持续使用 YouTube API 服务。
此修订历史记录条目最初发布于 2020 年 7 月 20 日。
2020 年 7 月 28 日
对于在 2020 年 7 月 28 日之后创建的未经验证的 API 项目,通过 videos.insert
端点上传的所有视频都将仅限私享观看模式观看。如需解除此限制,每个项目必须接受审核,以验证符合服务条款的要求。
使用未经验证的 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 界面 |
---|---|---|
1234 | 1230 | 1230 |
12,345 | 12300 | 1.23 万 |
123456 | 123000 | 12.3 万 |
1234567 | 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 版快速入门指南。修订后的指南介绍了如何使用 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 即将取消对精选视频和精选网站功能的支持,这些功能可通过
channel
资源的invideoPromotion
对象在 API 中支持。因此,该对象(包括其所有子属性)将被弃用。在 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 资源中的属性对应的键值对列表。然后,它会将属性转换为 JSON 对象,以便在insert
和update
操作中使用。以下示例展示了一组属性名称和值以及代码将为其创建的 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 网络服务器应用的完整代码示例。如需查看完整示例(以及此更改),请执行以下操作:
- 转到交互式代码段工具或任意 API 方法(例如
channels.list
方法)的文档。 - 点击代码示例上方的
Python
标签页。 - 点击标签页上方的切换开关,即可从查看摘要切换为查看完整示例。
- 该标签页现在应该会显示使用
InstalledAppFlow
授权流程的完整代码示例。示例上方的描述对此进行了说明,并且还提供了指向 Web 服务器应用示例的链接。 - 点击链接可切换到 Web 服务器示例。该示例使用 Flask Web 应用框架和不同的授权流程。
所有这些示例都可以下载并在本地运行。如果您想要运行示例,请参阅代码段工具说明中有关在本地运行完整代码示例的说明。
- 转到交互式代码段工具或任意 API 方法(例如
2017 年 8 月 29 日
此更新包含以下更改:
search.list
方法的forContentOwner
形参的定义已作如下更新:如果该形参设置为true
,则必须将type
形参设置为video
。search.list
方法的regionCode
参数的定义已更新,以阐明该参数会将搜索结果限制为可在指定区域中观看的视频。- YouTube 更新了品牌徽标和图标。您可以从品牌推广指南页面下载“使用 YouTube 制作”的新徽标。其他新的 YouTube 徽标和图标也会显示在该页面上,您可以从 YouTube 品牌网站下载。
2017 年 7 月 24 日
此更新包含以下更改:
- 我们发布了全新的 YouTube Data API 快速入门指南(iOS 版)。本指南介绍了如何在用 Objective-C 或 Swift 编写的简单 iOS 应用中使用 YouTube Data API。
- YouTube Data API 的交互式代码段工具现在包含介绍该工具部分功能的文档:
- 执行 API 请求
- 在代码段和完整代码示例之间切换
- 使用样板函数
- 加载现有资源(针对更新方法)
注意:该工具还嵌入到了 API 方法的 API 参考文档中(示例)。
2017 年 6 月 1 日
此更新包含以下更改:
-
注意:这是弃用公告。
以下
video
资源属性即将弃用。虽然在 2017 年 12 月 1 日之前,这些属性一直受支持,但在此之前,我们无法保证视频会继续返回这些属性的值。同样,设置这些属性值的videos.insert
和videos.update
请求在该日期之前也不会生成错误,但系统可能无法存储传入数据。
2017 年 5 月 17 日
此更新包含以下更改:
-
API 参考文档已更新,以使代码段更加普及且更具互动性。介绍 API 方法(例如
channels.list
或videos.rate
)的页面现在包含一个互动工具,让您可以查看和自定义 Java、JavaScript、PHP、Python、Ruby、Apps 脚本和 Go 中的代码段。对于任何指定方法,该工具都会显示一个或多个用例的代码段,每个用例都描述了调用该方法的常用方法。例如,您可以调用
channels.list
方法来检索有关特定频道或当前用户频道的数据。您还可以与代码示例互动:
-
修改参数和属性值,并且代码段会动态更新以反映您提供的值。
-
在代码段和完整示例之间切换。代码段显示了调用 API 方法的那部分代码。完整的示例包含该代码段以及用于授权和发送请求的样板代码。您可以复制完整示例,然后通过命令行或本地网络服务器复制并运行。
-
点击按钮即可执行请求。(要执行请求,您需要授权该工具代表您调用该 API。)
请注意,在提供此工具的页面上,该工具已经取代了 API Explorer。(每个页面都会显示一个链接,这样您还可以选择加载 API Explorer 中正在处理的请求。)
-
-
Data API 代码段工具也更新了,新的界面提供上述所有相同功能。此页面上提供的主要新功能包括:
- 支持写入数据的 API 请求。
- 支持 Java 示例。
- 更灵活、全面的样板代码,用于向用户授权和构建 API 请求。
2017 年 4 月 27 日
此更新包含以下更改:
- 新的快速入门指南介绍了如何设置用于发出 YouTube Data API 请求的简单应用。指南目前适用于 Android、Apps 脚本、Go、Java、JavaScript、Node.js、PHP、Python 和 Ruby。
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[]
属性。video
资源的topicDetails.relevantTopicIds[]
属性。search.list
方法的topicId
参数。
-
注意:这是弃用公告。
以下属性即将弃用:
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 日生效的更新版条款之外,本次更新还包含一些证明文件,说明了开发者必须遵守的政策。
如需了解完整的新文档,请参阅更新后的条款的修订历史记录。此外,如果后续对更新版条款或支持文档的更改,也会在修订历史记录中进行说明。您可以通过该文档中的链接订阅 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 不属于支持的主题 ID 较少的集合,该 API 将返回空的结果集。
-
自 2016 年 9 月 12 日起,一些 API 字段和参数将被弃用:
-
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
。如果请求检索频道观看记录或“稍后观看”播放列表的播放列表详情 (
playlists.list
),系统将在 2016 年 9 月 12 日之后返回空列表。检索上述任一播放列表中的播放列表项 (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
参数会检索已通过身份验证的用户频道的订阅者列表,这些订阅者按照订阅者订阅频道的时间倒序排列。请注意,新参数仅支持检索已验证用户频道的最新 1,000 位订阅者。如需检索完整的订阅者列表,请使用
mySubscribers
参数。该参数不会按特定顺序返回订阅者,而不会限制可检索的订阅者数量。 -
我们针对 activity、playlistItem、playlist、搜索结果、缩略图和视频资源更新了
snippet.thumbnails.(key)
属性的定义,以指明某些视频可以使用其他缩略图图片大小。standard
图片宽 640 像素,高 480 像素。maxres
图片宽 1280 像素,高 720 像素。
-
channelSection.list
方法的part
参数的定义已更新,以指明能够以2
个配额单元为代价检索targeting
部分。 -
现在,当未正确授权的请求尝试检索
video
资源的fileDetails
、processingDetails
或suggestions
部分时,videos.list
方法现在会返回 Forbidden (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。这是因为收藏视频功能已弃用。请注意,此属性不受 API 弃用政策的约束。 -
ineligibleAccount
错误(可由comments.insert
、comments.update
、commentThreads.insert
或commentThreads.update
方法返回)的定义已更新,以反映用于授权 API 请求的 YouTube 帐号未与用户的 Google 帐号合并时发生此错误。
2016 年 4 月 20 日
此更新包含以下更改:
-
更新了
channels.update
方法的part
参数的定义,以指明localizations
也是该参数的有效值。 -
入门指南的配额使用情况部分已更新为链接到 Google Developer 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 日
根据欧盟法律规定,您必须向欧盟境内的最终用户提供特定披露声明并征得其同意。因此,对于欧盟境内的最终用户,您必须遵守欧盟地区用户意见征求政策。我们在 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 category movietographique 分级中的分级。此属性取代了现已废弃的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 服务器会使用该请求的授权凭据来标识开发者。因此,开发者可以将搜索结果范围限定为通过开发者自己的应用或网站上传的视频,而无法仅显示通过其他应用或网站上传的视频。新功能提供的功能与第 2 版 API 支持的开发者标签功能类似,但并不完全相同。
-
channel
资源的新snippet.country
属性可让频道所有者将其频道与特定国家/地区相关联。注意:如需为
channel
资源设置snippet.country
属性,您实际上需要更新brandingSettings.channel.country
属性。 -
该 API 现在支持以
channelSection
资源为目标。频道版块定位提供了一种方法,可限定只有符合特定条件的用户才能看到某个内容版块。该 API 提供了三种定位选项。用户必须满足所有定位设置,才能看到频道版块。
-
targeting.languages[]
:YouTube 应用语言的列表。选择了其中一种语言的用户可以看到相应的频道版块。 -
targeting.regions[]
:YouTube 首选内容区域的列表。选择其中一个区域的用户以及系统自动选择其中一个区域的用户可以看到频道版块。 -
targeting.countries[]
:显示频道版块的国家/地区列表。列表中的每个值都是一个 ISO 3166-1 alpha-2 国家/地区代码。
-
-
更正了
video
资源的contentDetails.duration
属性的定义,以反映该值可以反映小时、天等数据。 -
更正了
channelSections.delete
、playlistItems.delete
、playlists.delete
、subscriptions.delete
和videos.delete
方法的文档,以反映,如果成功,这些方法都会返回 HTTP204
响应代码 (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 支持以下方法:commentThreads.list
- 检索评论线程列表。使用此方法可检索与特定视频或频道相关的评论。commentThreads.insert
– 创建新的顶级评论。(使用comments.insert
方法回复现有评论。)commentThreads.update
– 修改顶级评论。
-
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 视频相关联。 -
迁移指南也已更新,介绍了如何迁移仍在使用 v2 API 字幕功能的应用。
-
API 的新
https://www.googleapis.com/auth/youtube.force-ssl
范围要求通过 SSL 连接与 API 服务器进行通信。此新范围授予与
https://www.googleapis.com/auth/youtube
范围相同的访问权限。而且,事实上这两个范围在功能上是相同的,因为只有通过 HTTPS 端点才能使用 YouTube API 服务器。因此,即使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
,则资源对应于新的订阅视频。请注意,我们无法保证该响应将会包含任何特定数量的新订阅视频。 -
Feed 更新的推送通知 - v2 API 支持使用简单更新协议 (SUP) 或 PubSubHubbub 的推送通知,以监控 YouTube 用户的用户活动 Feed。系统针对新频道订阅以及视频评分、分享、收藏、评论或上传视频时提供了通知。
v3 API 将支持采用 PubSubHubbub 协议的推送通知,但通知将仅涵盖视频上传以及视频标题或视频说明的更新。
-
Channel location - 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 等)。使用这些方法,您可以通过单个请求检索多个资源的列表。
进行这些更改后,本指南现在标识了将在当前 API 版本 (v3) 中弃用的旧版 (v2) API 支持的所有功能。
-
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 日
此更新包含以下更改:
-
search.list
方法现在支持relevanceLanguage
参数,可让您请求与特定语言最相关的结果。YouTube Data API (v3) 迁移指南也已更新,介绍了如何使用以下新参数。该参数解决了当前 API 版本 (v3) 与上一版本 (v2)(已弃用)之间的功能差异。
-
YouTube Data API (v3) 迁移指南也进行了更新,以指明弃用 v2 API 提供的用于描述电影、预告片、电视节目、电视剧季和电视剧集的特殊 Feed 和元数据字段。
2015 年 1 月 14 日
此更新包含以下更改:
-
YouTube Data API (v3) 迁移指南已更新,介绍了如何使用 API v3 通过 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 个新的内容分级制度,这些制度用于标识视频从各国家级分级机构获得的分级。新增支持的分级系统包括:阿根廷、奥地利、比利时、保加利亚、保加利亚、智利、智利、和智利53、支持和支持智利、和{6智利{6.支持的国家、支持和支持的国家/地区)。
2014 年 5 月 28 日
此更新包含以下更改:
-
search.list
方法现在支持location
和locationRadius
参数,可让您搜索与某个地理位置相关联的视频。请求必须为这两个参数指定一个值,才能根据位置检索结果,如果请求仅包含这两个参数中的一个,则 API 会返回错误。-
location
参数用于指定圆形地理区域中心的纬度/经度坐标。 -
locationRadius
参数用于指定对于视频仍显示在搜索结果中,视频位置与区域中心之间可达到的最大距离。
-
2014 年 5 月 13 日
此更新包含以下更改:
-
channel
资源的invideoPromotion.items[]
属性已更新,请注意,您通常只能为自己的频道设置一项促销商品。如果您尝试插入过多促销商品,该 API 会返回tooManyPromotedItems
错误,其中包含 HTTP400
状态代码。 -
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 会在向这些方法的成功请求返回 HTTP204
响应代码。
2014 年 5 月 2 日
此更新包含以下更改:
-
新的
i18nLanguage
资源用于标识 YouTube 网站支持的应用语言。应用语言也可称为界面语言。对于 YouTube 网站,可以根据 Google 帐号设置、浏览器语言或 IP 位置自动选择应用语言,用户也可以从 YouTube 网站页脚中手动选择所需的界面语言。该 API 支持使用 list 方法列出受支持的应用语言。在调用
videoCategories.list
和guideCategories.list
等 API 方法时,您可以将支持的语言用作hl
参数的值。 -
新的
i18nRegion
资源标识了一个地理区域,YouTube 用户可以将其选为首选内容区域。内容区域也可称为内容语言区域。对于 YouTube 网站,系统可以根据 YouTube 域或用户的 IP 位置等启发法自动选择内容区域,用户也可以从 YouTube 网站页脚中手动选择所需的内容区域。该 API 支持使用 list 方法列出支持的内容区域。调用
search.list
、videos.list
、activities.list
和videoCategories.list
等 API 方法时,可将支持的区号用作regionCode
参数的值。
2014 年 4 月 7 日
此更新包含以下更改:
-
新的
channelSection
资源包含频道选择推介的一组视频的相关信息。例如,版块可以展示某个频道最新上传的视频、最热门的上传视频,或者一个或多个播放列表中的视频。该 API 支持 list、insert、update 或 delete 频道版块的方法。您可以通过指定特定频道 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 日
此更新包含以下更改:
-
借助
video
资源的新status.publishAt
属性,您可以指定预定发布私享视频的日期和时间。仅当视频的隐私状态为private
且视频从未发布时,才能设置此属性。此新属性不受弃用政策的约束。
2014 年 3 月 13 日
此更新包含以下更改:
-
对于
channel
资源,API 现在支持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 的值,该 API 将返回错误。 -
错误文档现在指定了每种错误类型的 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 日
此更新包含以下更改:
-
YouTube Data API v3 现在需遵守 YouTube API 服务条款中所述的弃用政策。请注意,在列明受弃用政策约束的 API 页面中,一些 v3 API 功能不在此政策的适用范围内。
2013 年 12 月 5 日
此更新包含以下更改:
-
search.list
方法的文档已更新,以正确反映提交搜索请求时不需要只为一个过滤条件参数指定值。相反,您可以为 0 个过滤器参数或 1 个过滤器参数设置一个值。 -
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
属性用于指明更新后的视频或新上传的视频是否可以与该视频类别关联。 -
为以下方法添加了代码示例:
activities.insert
(精简版)channelBanners.insert
(Python)channels.update
(Python)playlistItems.list
(精简版)search.list
(精简版)thumbnails.set
(Java)videos.insert
(精简版)
2013 年 10 月 24 日
此更新包含以下更改:
-
该 API 还包含两项可帮助您查找和推介直播内容的额外功能:
搜索结果中的新
snippet.liveBroadcastContent
属性可指明视频或频道资源是否有直播内容。有效的属性值包括upcoming
、active
和none
。-
video
资源的新snippet.liveBroadcastContent
属性用于指明视频是即将开始还是正在进行的直播。以下列表说明了该属性的可能值:upcoming
– 视频是尚未开始的直播。active
– 视频正在进行现场直播。none
– 视频不是即将开始或正在进行的直播。这是仍可在 YouTube 上观看的已完成直播的属性值。
-
video
资源的新liveStreamingDetails
属性是一个对象,其中包含有关直播视频广播的元数据。如需检索此元数据,请在part
参数值的资源部分列表中添加liveStreamingDetails
。元数据包括以下新属性:liveStreamingDetails.actualStartTime
- 直播实际开始的时间。(只要广播的状态为active
,就会显示此值。)liveStreamingDetails.actualEndTime
– 直播实际结束的时间。(直播结束后就会显示此值。)liveStreamingDetails.scheduledStartTime
- 预定的直播开始时间。liveStreamingDetails.scheduledEndTime
- 预定的直播结束时间。如果属性值为空或该属性不存在,则按计划无限期进行广播。liveStreamingDetails.concurrentViewers
- 观看直播的人数。
如需检索此元数据,请在调用
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
范围的授权令牌。此外,如果多频道网络决定接受或拒绝频道,或者在令牌发放后的两周内,就必须撤消使用该范围的任何令牌。 -
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
属性用于标识视频由意大利文化部部长提供的分级。 -
现在,该 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
对象具有以下新属性和更新后的属性:-
该 API 现在支持将网站指定为促销商品。为此,请将
invideoPromotion.items[].id.type
属性值设为website
,并使用新的invideoPromotion.items[].id.websiteUrl
属性指定网址。此外,还可以使用新的invideoPromotion.items[].customMessage
属性定义要在促销活动中显示的自定义消息。链接可以指向关联网站、商家网站或社交网站。如需详细了解如何为您的内容启用链接,请参阅 YouTube 帮助中心针对关联网站和商家网站的说明。
添加促销链接,即表示你同意这些链接不会被用来将流量重定向到未经授权的网站,并且这些链接符合 YouTube 的 AdWords 政策、YouTube 广告政策、YouTube 社区准则和 YouTube 服务条款。
-
调整了与用于在视频播放期间显示促销商品的时间设置相关的属性:
-
invideoPromotion.timing
对象已移至invideoPromotion.items[].timing
。现在,您可以通过该对象自定义invideoPromotion.items[]
列表中每个促销商品的时间数据。 -
新的
invideoPromotion.defaultTiming
对象用于指定促销活动的默认计时设置。这些设置用于确定在你频道的某个视频播放期间何时展示推广商品。您可以使用invideoPromotion.items[].timing
对象替换任何给定促销商品的默认投放时间。 -
新的
invideoPromotion.items[].timing.durationMs
属性用于指定促销活动应显示的时长(以毫秒为单位)。invideoPromotion.defaultTiming
对象还包含durationMs
字段,用于指定促销商品的默认展示时长。
-
-
invideoPromotion.items[].type
和invideoPromotion.items[].videoId
属性均已移至invideoPromotion.items[].id
对象。
-
-
subscriptions.list
方法现在支持onBehalfOfContentOwner
和onBehalfOfContentOwnerChannel
参数。其他几种方法已经支持这两个参数。 -
在对
thumbnails.set
请求的 API 响应中,kind
属性值已从youtube#thumbnailListResponse
更改为youtube#thumbnailSetResponse
。 -
为以下方法添加了代码示例:
channels.update
(Java、Python)playlists.insert
(.NET、PHP)subscriptions.insert
(PHP、Python)thumbnails.set
(PHP、Python)videos.insert
(PHP)videos.list
(PHP)videos.rate
(Python)videos.update
(Java、PHP、Python)
请注意,还移除了
playlistItems.insert
方法的 Python 示例,因为它演示的功能现在由videos.rate
方法处理。 -
error documentation
描述了以下新的请求上下文错误,任何支持mine
请求参数的 API 方法都可能会发生此错误:错误类型 错误详情 说明 badRequest
invalidMine
在经过身份验证的用户是 YouTube 合作伙伴的请求中,不能使用 mine
参数。您应该移除mine
参数;通过移除onBehalfOfContentOwner
参数验证成为 YouTube 用户的身份;或者通过提供onBehalfOfContentOwnerChannel
参数(如果可用于调用的方法)充当合作伙伴频道之一。
2013 年 8 月 8 日
此更新包含以下更改:
-
YouTube Data API 使用入门指南的配额使用部分已更新,以反映视频上传的配额费用从大约 16,000 个单位更改为大约 1,600 个单位。
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 上的活动无法提供足够的信息来生成活动 Feed,则 YouTube 会使用此值。 -
播放列表资源现在包含
snippet.tags
属性。此资源只会返回给正在检索自己的播放列表相关数据的授权用户。已获授权的用户还可以在调用playlists.insert
或playlists.update
方法时设置播放列表标签。 -
channels.list
和search.list
方法以前支持的onBehalfOfContentOwner
参数现在也可用于videos.insert
、videos.update
和videos.delete
方法。请注意,在调用videos.insert
方法时使用此参数时,请求还必须为新的onBehalfOfContentOwnerChannel
参数指定一个值,该值用于标识要添加视频的频道。频道必须与onBehalfOfContentOwner
参数指定的内容所有者相关联。该参数指示该请求的授权凭据标识代表参数值中指定的内容所有者的 YouTube 内容管理系统用户。用户进行身份验证时所用的 CMS 账号必须与指定的 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 日
此更新包含以下更改:
-
借助新的
channelBanners.insert
方法,您可以上传横幅图片,之后可使用channel
资源的新brandingSettings.image.bannerExternalUrl
属性将其设置为频道的横幅图片。 -
更新了
channels.update
方法的文档,列出了在调用该方法时可修改的属性。 -
video
资源文档不再将unspecified
列为suggestions.processingErrors[]
、suggestions.processingHints[]
、suggestions.processingWarnings[]
和suggestions.editorSuggestions[]
属性的有效属性值。 -
videos.list
方法的maxResults
参数现在的默认值为5
。 -
error documentation
现在会列出channelBanners.insert
和subscriptions.list
方法的错误。还列出了channels.update
方法的几个新错误。
2013 年 5 月 14 日
此更新包含以下更改:
2013 年 5 月 10 日
此更新包含以下更改:
-
YouTube 不再标识实验性 API 功能和服务。我们现在改为提供受弃用政策约束的 YouTube API 的列表。
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
参数的请求不支持 Paging 参数和信息。)-
maxResults
参数用于指定 API 可在结果集中返回的视频数量上限,而pageToken
参数用于标识结果集中要检索的特定网页。 -
为响应
videos.list
请求而返回的youtube#videoListResponse
资源现在包含pageInfo
对象,该对象包含结果总数和当前结果集中包含的结果数等详细信息。youtube#videoListResponse
资源还可以包含nextPageToken
和prevPageToken
属性,每个属性都提供可用于检索结果集中特定页面的令牌。
-
-
videos.insert
方法支持以下新参数:autoLevels
- 将此参数的值设为true
,以指示 YouTube 自动增强视频的光线和色彩。stabilize
- 将此参数值设为true
,以指示 YouTube 通过消除镜头移动导致的抖动来调整视频。
-
已将
channelTitle
属性添加到以下资源的snippet
:playlistItem
- 属性指定添加了播放列表项的频道的名称。playlist
- 属性指定创建播放列表的频道的名称。subscription
- 属性指定所订阅频道的名称。
-
为以下方法添加了代码示例:
activities.insert
(Ruby)playlistItems.list
(.NET)search.list
(.NET)subscriptions.insert
(Java、Ruby)videos.insert
(.NET、Ruby)
-
借助
subscriptions.list
方法的新mySubscribers
参数,您可以检索当前经过身份验证的用户的订阅者列表。此参数只能在经过适当授权的请求中使用。注意:此功能旨在取代
channels.list
方法当前支持的mySubscribers
参数。该参数将被废弃。 -
在
video
资源中,属性值unspecified
不再是以下任何属性的可能值: -
现在,包含意外参数的 API 请求会返回
badRequest
错误,并且报告的错误原因是unexpectedParameter
。 -
当播放列表包含的更新项数已达到允许的上限时,
playlistItems.insert
方法返回的错误。该错误现在会报告为forbidden
错误,错误原因为playlistContainsMaximumNumberOfVideos
。
2013 年 4 月 19 日
此更新包含以下更改:
-
通过新的
videos.rate
方法,用户可以为视频设置like
或dislike
分级,或者移除视频的分级。错误文档也已更新,列出了 API 在响应
videos.rate
方法调用时可能会返回的错误。 -
现在,在 API 文档中,缩略图图片标识为单独的资源,新的
thumbnails.set
方法可让您将自定义视频缩略图上传到 YouTube 并为视频设置缩略图。错误文档也已更新,列出了 API 在响应
thumbnails.set
方法调用时可能会返回的错误。请注意,此更改并不会真正影响返回缩略图的现有资源。缩略图图片在这些资源中返回的方式与以前相同,不过现在文档确实列出了 API 可能返回的不同缩略图大小的名称。
-
channel
资源的新brandingSettings
部分用于标识频道的频道页和视频观看页面的设置、文本和图片。 -
playlistItem
资源包含以下新属性:-
新的
status
对象可封装有关播放列表项的状态信息,而status.privacyStatus
属性用于标识播放列表项的隐私状态。
-
-
video
资源包含以下新属性:-
status.publicStatsViewable
属性用于指明观看页面上的扩展视频统计信息是否可公开查看。默认情况下,这些统计信息可供查看,并且即使该属性的值设为false
,视频的观看次数和评分等统计信息仍会公开显示。您可以在调用videos.insert
或videos.update
方法时设置此属性的值。 -
contentDetails.contentRating
对象可封装视频根据各种分级制度获得的分级。以下列表列出了所支持的分级制度,并提供了指向每种分级制度相关联的资源的链接。属性定义标识了每个系统支持的评分值。
-
-
playlistItems.update
方法的文档已更新,以反映必须在作为请求正文发送的资源中指定snippet.resourceId
属性。 -
search.list
方法现在支持以下功能:-
新的
forMine
参数将搜索限制为仅检索经过身份验证的用户的视频。 -
order
参数现在支持按标题的字母顺序 (order=title
) 或视频数量降序 (order=videoCount
) 对结果进行排序。 -
新的
safeSearch
参数用于指明搜索结果是否应包含受限内容。
-
-
videos.insert
方法支持以下几种新错误,如下表所示:错误类型 错误详情 说明 badRequest
invalidCategoryId
snippet.categoryId
属性指定的类别 ID 无效。使用videoCategories.list
方法可检索支持的类别。badRequest
invalidRecordingDetails
metadata specifies invalid recording details.
badRequest
invalidVideoGameRating
请求元数据指定的视频游戏分级无效。 badRequest
invalidVideoMetadata
请求元数据无效。 -
onBehalfOfContentOwner
参数已从videos.update
和videos.delete
方法支持的参数列表中移除。
2013 年 3 月 12 日
此更新包含以下更改:
-
已将
channelTitle
属性添加到以下资源的snippet
: -
search.list
方法支持以下新参数:-
借助
channelType
参数,您可以将频道搜索限制为检索所有频道或仅检索节目。 -
借助
videoType
参数,您可以将视频搜索限制为仅检索所有视频,或者仅检索电影或电视节目剧集。
-
-
更新了
video
资源的recordingDetails
部分的定义,指出只有在设置了视频的地理位置数据或录制时间时,才会为视频返回该对象。 -
playlistItems.update
方法现在会返回invalidSnippet
错误,如果 API 请求未指定有效的代码段,就会返回该错误。 -
有几种 API 方法支持专用于 YouTube 内容合作伙伴的新参数。YouTube 内容合作伙伴包括电影和电视工作室、唱片公司以及其他在 YouTube 上发布内容的内容创作者。
-
onBehalfOfContentOwner
参数用于指明该请求的授权凭据用于标识代表参数值中指定的内容所有者的 YouTube CMS 用户。用户进行身份验证时所用的 CMS 账号必须与指定的 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 日
此更新包含以下更改:
-
该 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
错误。 -
移除了
channel
资源的snippet.channelId
属性。资源的id
属性提供相同的值。
2013 年 1 月 30 日
此更新包含以下更改:
-
新的 error 页面列出了 API 可能会返回的错误。本页面包含常见错误(可能出现在多个不同的 API 方法中),以及特定于方法的错误。
2013 年 1 月 16 日
此更新包含以下更改:
-
下方列表中显示的方法和语言现在提供相关代码示例:
activities.insert
- JavaplaylistItems.insert
- PythonplaylistItems.list
- Java、JavaScript、PHP、Python、Rubyplaylists.insert
- Java、JavaScript、Pythonsearch.list
- Java、JavaScript、Python、Rubyvideos.insert
- Java
-
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 方法检索了有效值列表。