YouTube APIファミリー(2020)をざっくり把握する

案件でYouTubeのAPI使う必要があって、すごい調べたので、自分用ノートに加筆して公開します。

# 目的
これからYouTubeのAPIを使う人が何使ったら良いかを把握できるような記事にするために、
YouTube APIの全体像、それぞれのざっくりした機能をまとめたいと思います。

細かい実装の話は書かないつもりです。
（というか僕が使ったのPlayerとDataだけですし）

# 公式
公式ドキュメントは下記にあります。

[YouTube(Google Developers)](https://developers.google.com/youtube?hl=ja)

ところどころ翻訳されてなくて、英語ドキュメントであることを除けば、内容的には親切なドキュメントになってる……と思うんですが、僕は最初イマイチ全体像がつかめませんでした。
要するに「動画のタイトルとりたいんだけど、IFrame Player APIだととれないの？　じゃあどのAPI使えば良いの？」みたいなところがわかりませんでした。

# YouTube APIファミリー(2020)
- IFrame Player API
- YouTube Data API (v3)
- YouTube Analytics API
- YouTube Live Streaming API
- (Subscribe Button)

# それぞれの機能
# IFrame Player API
Web/モバイルで再生可能な埋めこみプレイヤーを提供するAPIです。
HTML5のiframe属性で動くので、モバイル(iOS)でもWebView経由で動きます。
（Androidは全く仕組み知りません……）

基本的にはvideoID(YouTubeの動画URLについているID)を指定すると、細かい指定をしなくても良い感じに調整してHTMLを返してくれます。
とりあえず動画再生したい、というだけなら、このAPI使うだけで事足りるでしょう。
開発者登録も不要です。

[公式サンプル](https://developers.google.com/youtube/youtube_player_demo)

```html:sample
<iframe id="ytplayer" type="text/html" width="720" height="405"
src="https://www.youtube.com/embed/M7lc1UVf-VE"
frameborder="0" allowfullscreen>
```

デメリットは、生データが隠蔽されているので、開発者側で細かくいじれなくて、挙動はかなりの部分APIにお任せになっちゃうところですね。
あとiOS/Android向けの公式プレイヤーはメンテナンスが放置されていて、有志の方がForkしたプロジェクトを探さないといけない、という罠もあります。
（これは普通になんとかして欲しい）

そして、プレイヤーはあくまでプレイヤーで、メタ情報は一切取得できません。
たとえば動画タイトルやチャンネル名などは、プレイヤーをViewに出すと明らかに表示されてるんですが、コードから取得することは不可能です。
そんなときはData APIを使いましょう。

# YouTube Data API (v3)
YouTubeのメインAPIと言っても良いかもしれません。
IFrame Player APIにView機能を移譲しているだけで、他の操作は全てこちら、と思うと整理しやすいかもしれませんね。

```plaintext:サンプルリクエスト
https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY&part=snippet,contentDetails,statistics,status
```

```json:sampleレスポンス
{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
```

YouTube上のほとんどのリソースに対するGET/POST/UPDATE/DELETE操作が可能です。データ形式はJSON。
リソースは具体的に書くと、ユーザーのアクティビティ、チャンネル情報、プレイリスト情報、チャンネル登録情報、サムネイル画像、動画本体の情報などです。
リソースによって、これはGETしかできない、などの制限があります。
リソースと可能な操作の組み合わせはとても書き切れないので、下記を見てください。

[サポートされている操作](https://developers.google.com/youtube/v3/getting-started#supported-operations)

注意点としては二点あります。

- Google Cloud Consoleからの利用登録が必要
- Quota(割当上限)が存在する

特にQuotaは突然引き下げられるという歴史があったようです。
不正利用や休眠アカウントと見做されると、突然Quotaがゼロにされたりするようなので、登録するGmailはこまめにチェックするか、転送設定すると良いかもです。

# YouTube Analytics API
名前の通り、チャンネルの計測（アナリティクス）に関するAPIです。
YouTube Studioのアナリティクスが優秀だと思うので、APIのユースケースがあまり思いつかないです。
自前でレポート取得して、データ分析するようなコアな人向けに提供されているという理解でいいんですかね？

OAuth 2.0で認証する仕組みです。
認証したら、まずAPI経由でjobをcreateします。
jobが成功すると、24時間利用可能なreportができるので、落としましょう。
reportのGET例は下記です。

```plaintext:サンプルリクエスト
GET https://youtubereporting.googleapis.com/v1/jobs/{jobId}/reports/{reportId}
```

```json:サンプルレスポンス
{
  "id": string,
  "jobId": string,
  "startTime": timestamp,
  "endTime": timestamp,
  "createTime": timestamp,
  "jobExpireTime": timestamp,
  "downloadUrl": string
}
```

# YouTube Live Streaming API
YouTube Liveの放送者が使うAPIです。
内部ではYouTube Data APIを使っているらしいので、まずその利用設定を済ませる必要があります。
その上でOAuth 2.0で認証する仕組みっぽいです（多分）。

[公式ドキュメント曰く、ユースケースは下記](https://developers.google.com/youtube/v3/live/getting-started#api-use-cases)です。

- Schedule broadcasts and define broadcast settings. Your application could enable users to predefine broadcast settings and then select the settings to apply to a particular broadcast.
- Associate video streams and broadcasts.
- Enable broadcasters to define information about a broadcast and its video (using the YouTube Data API) at the same time.
- Simplify transitions between broadcast states (testing, live, etc.) and enable users to insert cuepoints.

1個目のライブ前に各種設定を事前にしておけるっていうのは（実際やるかはともかくとして）理解できるんですが、２個目以降は正直よくわかんないですね。
YouTube liveにおけるbroadcastが何なのかよくわかってないせいなのかな……
→調べたら、broadcastはYouTube　live動画用のデータ形式で、通常のvideoとは別扱いらしいです。
 またvideo streamsが実際のライブ動画データのことで、1 streamは3 broadcastまで紐付け可能なので、
 たとえば１つのミュージシャンのライブを日本放送局、中国放送局、韓国放送局みたいな形にわけて放送するようなことが可能になってるっぽいですね。

# (Subscribe Button)
これはYouTubeのAPIのページに他四つと並べて書いてあったので一応ファミリーに入れたんですが、要はチャンネル登録ボタンの埋めこみパーツです。
他四つに比べるとAPIというほどのものでもないんですが、まあ一応。

[ここ](https://developers.google.com/youtube/youtube_subscribe_button)を使うと、簡単にボタンが作れます。

```html
<script src="https://apis.google.com/js/platform.js"></script>

<div class="g-ytsubscribe" data-channel="GoogleDevelopers" data-layout="full" data-count="default"></div>
```