Yt - YouTube API 的 Ruby 客户端

Yt 帮助你编写需要与 YouTube 交互的应用程序。

源代码可在 GitHub 上获取，文档可在 RubyDoc 上查阅。

在配置你的应用后，你可以运行如下命令：

channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow'
channel.title #=> "Fullscreen"
channel.public? #=> true
channel.videos.count #=> 12

video = Yt::Video.new id: 'jNQXAC9IVRw'
video.title #=> "Fullscreen Creator Platform"
video.comment_count #=> 308
video.hd? #=> true
video.annotations.count #=> 1
video.comment_threads #=> #<Yt::Collections::CommentThreads ...>
# 使用 #take 限制需要从服务器获取的页数
video.comment_threads.take(99).map(&:author_display_name) #=> ["Paul", "Tommy", ...]

完整文档可在 rubydoc.info 上查阅。

如何安装

要在你的系统上安装，运行

gem install yt

要在一个捆绑的 Ruby 项目中使用，在 Gemfile 中添加这一行：

gem 'yt', '~> 0.32.0'

由于该 gem 遵循语义化版本控制，在你的 Gemfile 中指明完整版本（~> major.minor.patch）可以保证当你 bundle update 时，即使发布了新版本的 Yt，你的项目也不会出现任何错误。

可用资源

Yt::Account

查看 nullscreen.github.io/yt 获取 Yt::Account 可用方法的列表。

Yt::ContentOwner

使用 Yt::ContentOwner 可以：

以 YouTube 内容所有者身份进行身份验证
列出与 YouTube 内容所有者合作的频道
列出由内容所有者管理的版权声明
列出并删除由内容所有者管理的参考
列出由内容所有者管理的政策和政策规则
创建资产
列出资产

# 内容所有者可以使用访问令牌、刷新令牌或授权码进行初始化
content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'

content_owner.partnered_channels.count #=> 12
content_owner.partnered_channels.map &:title #=> ["Fullscreen", "Best of Fullscreen", ...]
content_owner.partnered_channels.where(part: 'statistics').map &:subscriber_count #=> [136925, 56945, ...]

content_owner.claims.where(q: 'Fullscreen').count #=> 24
content_owner.claims.first #=> #<Yt::Models::Claim @id=...>
content_owner.claims.first.video_id #=> 'jNQXAC9IVRw'
content_owner.claims.first.status #=> "active"

reference = content_owner.references.where(asset_id: "ABCDEFG").first #=> #<Yt::Models::Reference @id=...>
reference.delete #=> true

content_owner.policies.first #=> #<Yt::Models::Policy @id=...>
content_owner.policies.first.name #=> "Track in all countries"
content_owner.policies.first.rules.first #=> #<Yt::Models::PolicyRule @id=...>
content_owner.policies.first.rules.first.action #=> "monetize"
content_owner.policies.first.rules.first.included_territories #=> ["US", "CA"]

content_owner.create_asset type: 'web' #=> #<Yt::Models::Asset @id=...>

content_owner.assets.first #=> #<Yt::Models::AssetSnippet:0x007ff2bc543b00 @id=...>
content_owner.assets.first.id #=> "A4532885163805730"
content_owner.assets.first.title #=> "Money Train"
content_owner.assets.first.type #=> "web"
content_owner.assets.first.custom_id #=> "MoKNJFOIRroc"

以上所有方法都需要身份验证（见下文）。

Yt::Channel

查看 nullscreen.github.io/yt 获取 Yt::Channel 可用方法的列表。

Yt::Video

查看 nullscreen.github.io/yt 获取 Yt::Video 可用方法的列表。

Yt::Playlist

查看 nullscreen.github.io/yt 获取 Yt::Playlist 可用方法的列表。

Yt::PlaylistItem

查看 nullscreen.github.io/yt 获取 Yt::PlaylistItem 可用方法的列表。

Yt::CommentThread

使用 Yt::CommentThread 可以：

显示评论线程的详细信息。

Yt::CommentThread.new id: 'z13vsnnbwtv4sbnug232erczcmi3wzaug'

comment_thread.video_id #=> "1234"
comment_thread.total_reply_count #=> 1
comment_thread.can_reply? #=> true
comment_thread.public? #=> true

comment_thread.top_level_comment #=> #<Yt::Models::Comment ...>
comment_thread.text_display #=> "funny video!"
comment_thread.like_count #=> 9
comment_thread.updated_at #=> 2016-03-22 12:56:56 UTC
comment_thread.author_display_name #=> "Joe"

Yt::Comment

使用 Yt::Comment 可以：

获取评论的详细信息。

Yt::Comment.new id: 'z13vsnnbwtv4sbnug232erczcmi3wzaug'

comment.text_display #=> "很棒"
comment.author_display_name #=> "Jack"
comment.like_count #=> 1
comment.updated_at #=> 2016-03-22 12:56:56 UTC
comment.parent_id #=> "abc1234" (如果评论不是回复则返回 nil)

Yt::BulkReportJob

使用 Yt::BulkReportJob 可以:

获取批量报告任务的详细信息。

content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
bulk_report_job = content_owner.bulk_report_jobs.first

bulk_report_job.report_type_id #=> "content_owner_demographics_a1"

Yt::BulkReport

使用 Yt::BulkReport 可以:

获取批量报告的详细信息。

content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
bulk_report_job = content_owner.bulk_report_jobs.first
bulk_report = bulk_report_job.bulk_reports.first

bulk_report.start_time #=> 2017-08-11 07:00:00 UTC
bulk_report.end_time #=> 2017-08-12 07:00:00 UTC
bulk_report.download_url #=> "https://youtubereporting.googleapis.com/v1/..."

Yt::Collections::Videos

使用 Yt::Collections::Videos 可以:

搜索视频

videos = Yt::Collections::Videos.new
videos.where(order: 'viewCount').first.title #=>  "PSY - GANGNAM STYLE"
videos.where(q: 'Fullscreen CreatorPlatform', safe_search: 'none').size #=> 324
videos.where(chart: 'mostPopular', video_category_id: 44).first.title #=> "SINISTER - Trailer"
videos.where(id: 'jNQXAC9IVRw,invalid').map(&:title) #=> ["Fullscreen Creator Platform"]

以上方法不需要身份验证。

Yt::Annotation

查看 nullscreen.github.io/yt 获取 Yt::Annotation 可用的方法列表。

Yt::MatchPolicy

使用 Yt::MatchPolicy 可以:

更新资产使用的政策

content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
match_policy = Yt::MatchPolicy.new asset_id: 'ABCD12345678', auth: content_owner
match_policy.update policy_id: 'aBcdEF6g-HJ' #=> true

Yt::Asset

使用 Yt::Asset 可以:

读取资产的所有权
更新资产的属性


content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
asset = Yt::Asset.new id: 'ABCD12345678', auth: content_owner
asset.ownership #=> #<Yt::Models::Ownership @general=...>
asset.ownership.obtain! #=> true
asset.general_owners.first.owner #=> 'CMSname'
asset.general_owners.first.everywhere? #=> true
asset.ownership.release! #=> true

asset.update metadata_mine: {notes: '一些注释'} #=> true

检索资产的元数据(如标题、注释、描述、自定义ID)

content_owner = Yt::ContentOwner.new(...)
asset = content_owner.assets.where(id: 'A969176766549462', fetch_metadata: 'mine').first
asset.metadata_mine.title #=> "Master Final   Neu La Anh Fix"

asset = content_owner.assets.where(id: 'A969176766549462', fetch_metadata: 'effective').first
asset.metadata_effective.title #=> "Neu la anh" (由于所有权冲突而不同)

asset = content_owner.assets.where(id: 'A125058570526569', fetch_ownership: 'effective').first
asset.ownership_effective.general_owners.first.owner # => "XOuN81q-MeEUVrsiZeK1lQ"

搜索资产

content_owner.assets.where(labels: "campaign:cpiuwdz-8oc").size #=> 417
content_owner.assets.where(labels: "campaign:cpiuwdz-8oc").first.title #=> "Whoomp! (Supadupafly) (Xxl Hip House Mix)"

Yt::Claim

使用 Yt::Claim 可以:

读取认领的属性
查看认领的历史
更新认领的属性


content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
claim = Yt::Claim.new id: 'ABCD12345678', auth: content_owner
claim.video_id #=> 'va141cJga2'
claim.asset_id #=> 'A1234'
claim.content_type #=> 'audiovisual'
claim.active? #=> true

claim.claim_history #=> #<Yt::Models::ClaimHistory ...>
claim.claim_history.events[0].type #=> "claim_create"

claim.delete #=> true

data = {
  is_manual_claim: true,
  content_type: 'audiovisual',
  asset_id: 'A123123123123123',
  policy: { id: 'S123123123123123' },
  video_id: 'myvIdeoIdYT',
  match_info: {
    match_segments: [
      {
        manual_segment: {
          start: '00:00:20.000',
          finish: '00:01:20.000'
        }
      },
      {
        manual_segment: {
          start: '00:02:30.000',
          finish: '00:03:50.000'
        }
      }
    ]
  }
}

content_owner.claims.insert(data)

以上方法需要以视频内容所有者的身份进行身份验证(见下文)。

Yt::Ownership

使用 Yt::Ownership 可以:

更新资产的所有权

content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
ownership = Yt::Ownership.new asset_id: 'ABCD12345678', auth: $content_owner
new_general_owner_attrs = {ratio: 100, owner: 'CMSname', type: 'include', territories: ['US', 'CA']}
ownership.update general: [new_general_owner_attrs]

以上方法需要以视频内容所有者的身份进行身份验证(见下文)。

Yt::AdvertisingOptionsSet

使用 Yt::AdvertisingOptionsSet 可以：

更新视频的广告设置

content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
ad_options = Yt::AdvertisingOptionsSet.new video_id: 'jNQXAC9IVRw', auth: $content_owner
ad_options.update ad_formats: %w(standard_instream long) #=> true

上述方法需要以视频内容所有者的身份进行身份验证（见下文）。

插桩

Yt 利用 Active Support Instrumentation 提供了一个钩子，开发者可以使用它来获取向 YouTube 发送 HTTP 请求的通知。这个钩子可用于跟踪一段时间内的请求数量、监控配额使用情况、提供审计跟踪，或跟踪特定请求完成所需的时间。

在您的应用程序中订阅 request.yt 通知：

ActiveSupport::Notifications.subscribe 'request.yt' do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)

  event.payload[:request_uri] #=> #<URI::HTTPS URL:https://www.googleapis.com/youtube/v3/channels?id=UCxO1tY8h1AhOz0T4ENwmpow&part=snippet>
  event.payload[:method] #=> :get
  event.payload[:response] #=> #<Net::HTTPOK 200 OK readbody=true>

  event.end #=> 2014-08-22 16:57:17 -0700
  event.duration #=> 141.867 (ms)
end

配置您的应用

要使用 Yt，您必须在 Google Developers Console 中注册您的应用。

如果您还没有注册应用，请浏览控制台并选择"创建项目"： 01-create-project

当您的项目准备就绪后，在菜单中选择 APIs & Auth，然后分别启用 Google+、YouTube Analytics 和 YouTube Data API： 02-select-api 02a-enable google api 02b-enable youtube api 02c-enable youtube analytics api

下一步是创建 API 密钥。根据您的应用性质，您应选择以下策略之一。

不需要用户交互的应用

如果您正在构建一个只从 YouTube 获取公开数据的只读应用，那么您只需要一个公共 API 访问权限。

在公共 API 部分点击"创建新密钥"，然后选择"服务器密钥"： 03-create-key 04-create-server-key

创建服务器应用程序密钥后，复制 API 密钥并将其添加到您的代码中，使用以下代码片段（替换为您自己的密钥）：

Yt.configure do |config|
  config.api_key = 'AIzaSyAO8dXpvZcaP2XSDFBD91H8yQ'
end

请记住：这种类型的应用不允许执行任何破坏性操作，因此您无法为视频点赞、订阅频道或从特定帐户删除播放列表。您只能检索只读数据。

需要用户交互的网络应用

如果您正在构建一个管理 YouTube 帐户的网络应用，您需要每个帐户的所有者授权您的应用。有三种情况：

情况 1. 如果您已经有帐户的访问令牌，那么您就可以开始了。只需将该访问令牌传递给帐户初始化器，例如：

account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
account.email #=> (检索帐户的电子邮件地址)
account.videos #=> (列出帐户播放列表中的视频)

情况 2. 如果您没有帐户的访问令牌，但有刷新令牌，那么几乎同样简单。在 Google Developers Console 中，找到用于获取刷新令牌的网络应用程序，复制客户端 ID 和客户端密钥，并将它们添加到您的代码中，使用以下代码片段（替换为您自己的密钥）：

Yt.configure do |config|
  config.client_id = '1234567890.apps.googleusercontent.com'
  config.client_secret = '1234567890'
end

然后，您可以通过将刷新令牌传递给帐户初始化器来管理 YouTube 帐户，例如：

account = Yt::Account.new refresh_token: '1/1234567890'
account.email #=> (检索帐户的电子邮件地址)
account.videos #=> (列出帐户播放列表中的视频)

情况 3. 如果您没有任何帐户的令牌，那么您可以通过让用户通过 Google OAuth 页面授权您的应用来获取一个。

在 Google Developers Console 中，点击 OAuth 部分的"创建新客户端 ID"，然后选择"Web 应用程序"： 06-create-client-key

在"授权重定向 URI"文本区域中填写您的应用程序 URL，用户授权他们的 YouTube 帐户后将被重定向到该 URL。

创建 Web 应用程序的客户端 ID 后，复制客户端 ID 和密钥，并将它们添加到您的代码中，使用以下代码片段（替换为您自己的密钥）：

Yt.configure do |config|
  config.client_id = '49781862760-4t610gtk35462g.apps.googleusercontent.com'
  config.client_secret = 'NtFHjZkJcwYZDfYVz9mp8skz9'
end

最后，在您的网络应用中，添加一个链接到通过运行以下代码生成的 URL：

Yt::Account.new(scopes: scopes, redirect_uri: redirect_uri).authentication_url

其中 redirect_uri 是您在上面表单中输入的 URL，scopes 是您希望用户授权的 YouTube 权限列表。根据您应用的性质，您可以在 youtube、youtube.readonly 和 userinfo.email 中选择一个或多个。

每个授权您应用的用户都会被重定向到 redirect_uri，并带有一个额外的 code 参数，看起来类似 4/Ja60jJ7_Kw0。只需将此代码传递给以下方法即可进行身份验证并初始化账户：

account = Yt::Account.new authorization_code: '4/Ja60jJ7_Kw0', redirect_uri: redirect_uri
account.email #=> (获取账户的电子邮件地址)
account.videos #=> (列出账户播放列表中的视频)

使用环境变量进行配置

作为上述方法的替代方案，您可以使用变量配置您的应用。设置以下环境变量：

export YT_CLIENT_ID="1234567890.apps.googleusercontent.com"
export YT_CLIENT_SECRET="1234567890"
export YT_API_KEY="123456789012345678901234567890"

等同于使用初始化程序配置您的应用：

Yt.configure do |config|
  config.client_id = '1234567890.apps.googleusercontent.com'
  config.client_secret = '1234567890'
  config.api_key = '123456789012345678901234567890'
end