此页面由 Cloud Translation API 翻译。

YouTube API 服务 - 最低功能要求

注意：遵守 YouTube 开发者政策一文提供了相关指南和示例，可帮助您确保 API 客户端遵守 YouTube API 服务条款和政策 (API TOS) 的特定部分。本指南可帮助您了解 YouTube 如何强制执行 API 服务条款的某些方面，但它不会取代任何现有文档。

本文档定义了 API 客户端（以下简称“API 客户端”）的最低功能要求，这些客户端实现了 YouTube API 服务的特定功能或提供对这些功能的访问权限。

这些要求和准则旨在确保 API 客户端提供一致的用户体验，从而保护 YouTube 用户、内容所有者和广告客户的利益。这些规则是 YouTube API 服务条款不可或缺的一部分，在开发和实现任何 API 客户端时都必须遵守。

您应该预料到本文档中的要求会发生变化，以便我们确保通过现有的 YouTube 功能提供更好的用户体验。这些政策也会随着 YouTube 新功能和更新功能的推出而发生变化。有时，此类更改可能需要您更新 API 客户端以满足新要求。服务条款修订历史记录会记录所有变更，因此请经常查看该文档或订阅其 RSS Feed，以便及时了解可能影响 API 客户端的变更。

除了本文档中的要求之外，我们强烈建议您遵循 YouTube API 服务政策中介绍的最佳实践，以及 YouTube API 服务文档中其他位置讨论的最佳实践。即使并非严格要求，这些做法也有助于您的 API 客户端更快地从错误中恢复，并优化其配额使用情况（如果它们使用分配配额的 YouTube API 服务）。与此同时，这些做法有助于确保 YouTube 生态系统的健康发展，最重要的是，有助于为您的 API 客户端和 YouTube 应用的用户提供尽可能出色的体验。

YouTube 嵌入式播放器和视频播放

本部分中的要求专门针对嵌入式 YouTube 播放器。YouTube API 服务政策还包含多项与播放 YouTube 影音内容的 API 客户端相关的政策。

API 客户端身份和凭据

使用 YouTube 嵌入式播放器（包括 YouTube IFrame Player API）的 API 客户端必须通过 HTTP Referer 请求标头提供身份信息。在某些环境中，浏览器会自动设置 HTTP Referer，API 客户端只需确保它们不会以抑制 Referer 值的方式设置 Referrer-Policy。YouTube 建议使用 strict-origin-when-cross-origin Referrer-Policy，该政策已成为许多浏览器中的默认设置。

同样，如果要在使用 JavaScript window.open 创建的窗口中集成 YouTube 嵌入式播放器，API 客户端不得使用会抑制 Referer 值的 noreferrer 功能。

设置 Referer

在 HTTP Referer 默认为空且未由浏览器自动设置的环境中，API 客户端必须采取行动，通过其他方式提供其身份。在移动应用或桌面应用等 WebView 集成中，HTTP Referer 默认为空，Referer 通常使用以下方法之一进行设置：

移动应用，其中包含本地 HTML 文件中的播放器

在此配置中，播放器加载到与应用捆绑在一起的 HTML 文件中。加载此 HTML 文件时，设置 baseUrl 参数将设置 Referer。
- Android loadDataWithBaseURL
- iOS loadHTMLString:baseURL:

没有本地 HTML 文件的移动应用

在此配置中，播放器直接从 https://www.youtube.com/embed/VIDEO_ID 加载，没有任何封装的 HTML 文件。您可以通过将 Referer 添加为 HTTP 标头来设置它：

Android loadUrl，并向 additionalHttpHeaders 参数添加了 Referer HTTP 标头

iOS loadRequest:，并在请求中添加了 Referer HTTP 标头。例如：

NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
NSString *referrer = [[NSString stringWithFormat:@"https://%@", bundleId] lowercaseString];
NSURL *referrerUrl = [NSURL URLWithString:referrer];

NSString *destination = @"https://www.youtube.com/embed/VIDEO_ID";
NSURL *destinationUrl = [NSURL URLWithString:destination];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:destinationUrl];
[request addValue:referrerUrl forHTTPHeaderField:@"Referer"];

// Create an instance of WKWebView (omitted for simplicity), then load the NSMutableURLRequest.
[webView loadRequest:request];

移动应用，其中播放器位于原生浏览器标签页内
- Android CustomTabs
  
  使用 Intent.EXTRA_REFERRER 设置引荐来源网址。创建 Uri 时，请务必使用 android-app:// 方案，而不是 https://。例如：
```
String destinationUrl = "https://www.youtube.com/embed/VIDEO_ID";
CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build()
customTabsIntent.intent.putExtra(Intent.EXTRA_REFERRER, Uri.parse("android-app://" + context.getPackageName()));
customTabsIntent.launchUrl(this, Uri.parse(destinationUrl));
```
- iOS SFSafariViewController
  
  SFSafariViewController 不支持设置 Referer。在这种情况下，请改为设置 origin 播放器参数。
桌面应用

在此配置中，通过添加 HTTP 标头来设置 Referer：
- Microsoft .NET - 使用 HttpRequestHeaders.Referrer 或 CoreWebView2HttpRequestHeaders.SetHeader
- macOS - 按照上述针对 iOS 移动应用所述的相同说明操作

对于默认情况下 HTTP Referer 为空的其他平台，请通过配置加载播放器的 WebView 来设置 Referer 值。具体方法可能因平台而异。

如果您是开发者用于集成 YouTube 嵌入式播放器的库、框架、插件、服务或封装容器的所有者，则必须从环境中检索应用 ID（这可能无法实现，具体取决于平台），或者允许开发者传入其应用 ID，以便按上述说明设置 Referer（以及 widget_referrer 播放器参数，如果适用）。

引荐来源网址格式

当您通过设置 WebView 参数或添加 HTTP 标头来明确提供 Referer 时，该格式通常为完全限定的网址。指定 HTTPS 作为协议。在网址中，域名必须是您的应用标识符（“应用 ID”），该标识符已向将您的应用分发给最终用户的商店注册。如果您的应用是通过其他分发渠道提供给用户的，请使用在应用安装期间向操作系统注册的应用 ID。在大多数情况下，您的应用 ID 将是反向域名（也称为“反向 DNS 格式”），例如 com.google.android.youtube。代表性示例：

ChromeOS 上的 Android 操作系统和 Android 应用：应用 ID
Apple 平台（包括 iOS、iPadOS、macOS）：软件包 ID
Samsung Tizen：应用 ID
Linux 发行版：
- Fedora：应用 ID
- Gnome：应用 ID
- Ubuntu：应用 ID

在某些平台上，应用 ID 不是反向域名。在这种情况下，请使用分发应用的商店分配的唯一应用 ID。如果商店应用 ID 是生成的字母数字字符串（由商店或开发工具分配，而非由应用开发者选择），请同时提供应用显示名称（将空格替换为连字符）和商店应用 ID，并用英文句点分隔。例如 <my-app-name>.<AppID>。此值应在应用版本更改期间保持稳定。如果应用未托管在商店中，请使用在应用安装期间向操作系统注册的应用 ID；这通常是应用清单中的唯一标识符。排除有关应用版本和支持的架构的所有详细信息。代表性示例：

Chrome 应用商店：商店托管

商店应用 ID 通常是应用网址 https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID> 中路径的最后一部分。使用连字符分隔的应用名称和应用商店应用 ID 构建上述 <my-app-name>.<AppID> 字符串。
Windows：商店托管

商店应用 ID 通常是应用网址 https://apps.microsoft.com/detail/<AppID> 中路径的最后一部分。使用商店应用 ID 构建上述 <my-app-name>.<AppID> 字符串。还必须包含连字符分隔的应用名称。
Windows：非商店分发

Windows 应用在应用清单中包含软件包身份：Name_Version_Architecture_ResourceID_PublisherID。仅使用 Name 属性。
Xbox：商店托管

商店应用 ID 通常是应用网址 https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID> 中路径的最后一部分。使用连字符分隔的应用名称和应用商店应用 ID 构建上述 <my-app-name>.<AppID> 字符串。

对于向 YouTube 发送大量请求的 API 客户端（请参阅使用情况和配额），可能需要提供额外的凭据才能访问 YouTube 嵌入式播放器。

不遵守这些要求可能会导致 YouTube 嵌入式播放器的功能减少。

WebView 类型

在 WebView 中集成 YouTube 嵌入式播放器时，请尽可能使用操作系统提供的 WebView 类型之一。例如：

Android OS：WebView 或 CustomTabs
Apple 平台，包括 iOS、iPadOS、macOS：WKWebView 或 SFSafariViewController

嵌入式 YouTube 播放器尺寸

嵌入式播放器必须具有一个尺寸至少为200x200像素的视口。如果播放器显示控件，那么它必须足够大，可以在无需将视口缩小到最小尺寸以下的情况下完整显示控件。我们建议 16:9 播放器的宽至少为 480 像素、高至少为 270 像素。

自动播放和脚本化播放

本部分介绍了自动播放。此政策适用于以下 YouTube 嵌入式播放器：使用 autoplay 播放器参数，或使用 YouTube IFrame Player API 服务或其他 YouTube API 服务以编程方式启动自动播放。

自动播放视频的嵌入式播放器应在网页加载时或嵌入式播放器完全可见时立即开始播放。不过，API 客户端不得在播放器可见且页面或屏幕上显示的播放器超过一半之前启动自动播放。
一个网页或屏幕不得包含多个同时自动播放内容的 YouTube 播放器。
任何启动播放的 YouTube 缩略图的宽度必须至少为 120 像素，高度必须至少为 70 像素。

YouTube 播放器属性

YouTube 播放器的属性和参数（包括例如播放器中 YouTube 品牌的显示方式）在 YouTube API 文档和规范 (https://developers.google.com/youtube) 中指定。您不得对 YouTube 播放器进行 API 文档中未明确说明的更改。

叠加层和框架

您不得在 YouTube 嵌入式播放器的任何部分（包括播放器控件）前面显示叠加层、框架或其他视觉元素。同样，您不得使用叠加层、框架或其他视觉元素来遮盖嵌入式播放器的任何部分，包括播放器控件。

鼠标悬停次数

您不得在 YouTube 播放器上使用鼠标悬停或触控事件来代表用户发起任何操作，例如打开窗口或订阅频道。

上传视频

如果 API 客户端允许用户将内容上传到多个平台，则用户应能够选择和取消选择要将视频上传到的平台。

数据要求

允许用户将视频上传到 YouTube 的 API 客户端必须允许用户设置以下列表中的值。未列出的任何属性均为可选属性。

	名称	说明
资源属性
	`snippet.title`	必需。视频的标题。如果该值超过 100 个字符，YouTube 会返回错误。YouTube 支持除 `<` 和 `>` 之外的所有有效 UTF-8 字符。
	`snippet.description`	必需。视频的说明。如果该值超过 5000 字节，YouTube 会返回错误。YouTube 支持除 `<` 和 `>` 之外的所有有效 UTF-8 字符。
	`status.privacyStatus`	必需。视频的隐私设置。用户必须能够选择上传的视频是公开、私享还是不公开列出。
请求参数
	`onBehalfOfContentOwnerChannel`	在特定条件下必需。如果请求的授权凭据标识了内容所有者，并且设置了 `onBehalfOfContentOwner` 参数，那么 API 用户还必须能够指定要将视频上传到的 YouTube 频道。

显示评论

	名称	说明
资源属性
	`snippet.textDisplay`	必需。评论的文本。API 客户端必须 (a) 显示评论或评论回复的全文，或者 (b) 截断文本并提供一种让观看者能够轻松从截断版本访问全文的方式。此要求适用于所有评论和评论回复，无论评论与哪种类型的资源（视频、频道等）相关联。请注意，`commentThread` 资源的 `snippet.topLevelComment` 属性值是 `comment` 资源，而 `replies.comments[]` 属性是 `comment` 资源的列表。因此，此要求也适用于 `snippet.topLevelComment.snippet.textDisplay` 和 `replies.comments[].snippet.textDisplay` 属性。
	`snippet.title` (`channel`)	必需（建议）。频道的标题。如果评论与频道相关，API 客户端必须显示该频道的名称。如果评论与视频相关，API 客户端必须显示上传该视频的频道的名称。
	`snippet.title` (`video`)	随条件发生变化（建议）。视频的标题。如果评论与视频相关，则必须显示此值。
	`snippet.moderationStatus`	在特定条件下必需。如果 API 请求中的 `moderationStatus` 参数值为 `heldForReview` 或 `likelySpam`，则显示内容必须使用属性值、类似措辞（例如“此评论正在等待审核”）、标题（例如“等待审核”）或其他明确的措辞清楚指明该状态。`commentThreads.list` 方法支持根据评论的审核状态检索评论。

添加注释

	名称	说明
资源属性
	`snippet.title` (`channel`)	必需。频道的标题。如果用户要添加有关频道的评论，API 客户端必须显示该频道的名称。如果用户要针对某个视频添加评论，API 客户端必须显示上传该视频的频道的名称。
	`snippet.title` (`video`)	必需。如果用户要添加有关视频的评论，API 客户端必须显示视频的标题。
其他要求
	`Comment author's channel name`	必需。API 客户端必须明确标识评论将归属的 YouTube 用户账号。如果请求的授权凭据标识了内容所有者，并且设置了 `onBehalfOfContentOwner` 参数，则 API 用户还必须能够指定评论将归属的 YouTube 频道。

添加评论回复

	名称	说明
资源属性
	`snippet.textDisplay`	必需。评论的文本。API 客户端必须按照本文档的显示评论部分中定义的规则显示用户正在回复的评论的文本。
	`snippet.title` (`channel`)	必需。频道的标题。如果用户回复的是有关频道的评论，API 客户端必须显示该频道的名称。如果用户回复的是有关视频的评论，API 客户端必须显示上传该视频的频道的名称。
	`snippet.title` (`video`)	必需。如果用户要回复有关视频的评论，API 客户端必须显示视频的标题。
其他要求
	`Comment author's channel name`	必需。API 客户端必须明确指明评论回复将归属的 YouTube 用户账号。如果请求的授权凭据标识了内容所有者，并且设置了 `onBehalfOfContentOwner` 参数，则 API 用户还必须能够指定评论回复将归属到的 YouTube 频道。

修改或删除评论回复

	名称	说明
资源属性
	`snippet.textDisplay`	必需。评论的文本。API 客户端必须按照本文档显示评论部分中定义的规则显示用户正在编辑或删除的评论的文本。
	`snippet.title` (`channel`)	必需。频道的标题。如果用户正在修改或删除有关频道的评论，API 客户端必须显示该频道的名称。如果用户正在修改或删除有关某个视频的评论，API 客户端必须显示上传该视频的频道的名称。
	`snippet.title` (`video`)	必需。如果用户正在修改或删除有关视频的评论，API 客户端必须显示视频的标题。
其他要求
	`Comment author's channel name`	必需。API 客户端必须明确指明相应评论归属的 YouTube 用户账号。

禁止用户参与实时聊天（或移除禁令）

	名称	说明
资源属性
	`snippet.title` (`channel`)	必需。被禁或被解除禁令的 YouTube 频道的名称。此外，名称必须链接到频道，或者还必须显示频道网址。
其他要求
	评论作者的频道名称	必需。API 客户端必须明确标识用于添加或移除禁令的 YouTube 用户账号。

YouTube API 服务 - 最低功能要求 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。