YouTube Data API の概要

はじめに

このドキュメントは、YouTube と情報をやり取りするアプリケーションを作成するデベロッパーの方を対象としています。このドキュメントでは、YouTube および API 自体の基本的な概念について説明します。また、API がサポートするさまざまな機能の概要についても説明します。

始める前に

  1. Google API Console にアクセスして API キーをリクエストし、アプリケーションを登録するには、Google アカウントが必要です。

  2. Google API Console でプロジェクトを作成し、アプリケーションが API リクエストを送信できるように認証情報を取得します。

  3. プロジェクトを作成したら、YouTube Data API が、アプリが使用するために登録されているサービスの 1 つであることを確認します。

    1. API Console に移動し、登録したプロジェクトを選択します。
    2. [有効な API] ページにアクセスします。API のリストで、YouTube Data API v3 のステータスが [オン] になっていることを確認します。

  4. ユーザー認証を必要とする API メソッドをアプリケーションで使用する場合は、認証ガイドに目を通して OAuth 2.0 認証の実装方法を習得しておきます。

  5. API の実装を簡素化するためのクライアント ライブラリを選択します。

  6. JSON（JavaScript Object Notation）データ形式のコア コンセプトについて理解しておきます。JSON は言語に依存しない一般的なデータ形式で、任意のデータ構造をシンプルなテキストで表現します。詳細については、json.org をご覧ください。

リソースとリソースの種類

リソースとは、一意の識別子を持つ個別のデータ エンティティです。次の表は、API を使用してやり取りできる各種リソースについて説明したものです。

リソース
activity 特定のユーザーが YouTube サイトで行った操作に関する情報が格納されています。アクティビティ フィードで報告されるユーザー操作は、動画の評価、動画の共有、お気に入りへの動画の追加、チャンネルのお知らせメッセージの投稿などです。
channel 単一の YouTube チャンネルに関する情報が格納されています。
channelBanner 新しくアップロードされた画像をチャンネル用のバナー画像として設定するために使う URL を示します。
channelSection チャンネルがおすすめに設定した動画のセットに関する情報が含まれます。たとえば、チャンネルの最新のアップロード動画、最も人気のあるアップロード動画、1 つまたは複数の再生リストの動画などをセクションに表示できます。
guideCategory コンテンツや人気などの指標に基づいて YouTube がチャンネルに関連付けるカテゴリを示します。guideCategory により、YouTube ユーザーが目的のコンテンツを容易に見つけられるようにチャンネルを整理できます。チャンネルは 1 つ以上のガイド カテゴリに関連付けられる場合がありますが、何らかのガイド カテゴリに属することが保証されているわけではありません。
i18nLanguage YouTube ウェブサイトがサポートするアプリの言語を識別します。アプリの言語は、UI 言語とも呼ばれます。
i18nRegion YouTube ユーザーが優先コンテンツ地域として選択できる地域を表します。コンテンツ地域は、コンテンツ ロケールとも呼ばれます。
playlist 単一の YouTube 再生リストを表します。再生リストとは、順番に視聴したり、他のユーザーと共有したりできる動画のコレクションです。
playlistItem 再生リストを構成する動画などのリソースをしめします。また、playlistItem リソースには、たいしょリソースが再生リストでどのように使用されるのかを説明する詳細な情報も格納されています。
search result API リクエストで指定した検索パラメータに一致する YouTube 動画、チャンネル、または再生リストに関する情報が格納されています。検索結果は、動画など一意に識別可能なリソースを出力しますが、検索結果自体は永続的なデータを持ちません。
subscription YouTube ユーザーの登録チャンネルに関する情報が格納されています。subscription は、新しい動画がチャンネルに追加された場合や、別のユーザーが YouTube で動画のアップロード、動画の評価、動画へのコメントといった何らかの操作を行った場合に、ユーザーに通知します。
thumbnail リソースに関連付けられたサムネイル画像を示します。
video 単一の YouTube 動画を表します。
videoCategory アップロードした動画に関連付けられているか、関連付けることができるカテゴリを示します。
watermark 指定されたチャンネルの動画の再生中に表示される画像を識別します。チャンネル所有者は、画像がリンクされるターゲット チャンネルを指定することもできます。また、動画の再生中にウォーターマークが表示されるタイミングや表示される時間の長さを決定するタイミングの詳細を指定することもできます。

多くの場合、リソースには他のリソースへの参照が含まれている点に注意してください。たとえば、playlistItem リソースの snippet.resourceId.videoId プロパティは、動画リソースを識別します。この動画リソースには、動画に関する完全な情報が含まれています。別の例として、検索結果には、特定の動画、再生リスト、チャンネル リソースを識別する videoId、playlistId、channelId プロパティのいずれかが含まれます。

サポートされているオペレーション

次の表は、API がサポートする最も一般的なメソッドを示したものです。一部のリソースは、そのリソースに固有の関数を実行する他のメソッドもサポートしています。たとえば、videos.rate メソッドはユーザー評価を動画に関連付け、thumbnails.set メソッドは動画のサムネイル画像を YouTube にアップロードして動画に関連付けます。

運用
list 0 個以上のリソースのリストを取得（GET）します。
insert 新しいリソースを作成（POST）します。
update リクエストのデータに応じて既存のリソースを変更（PUT）します。
delete 特定のリソースを削除（DELETE）します。

現在のところ API はサポートされている各リソースの種類の一覧を作成するメソッドをサポートしています。また、多くのリソースに対する書き込み操作もサポートしています。

次の表は、各種リソースでサポートされている操作を示したものです。リソースの挿入、更新、または削除を実行する操作の場合は、常にユーザーによる承認が必要になります。場合によっては、list メソッドは承認済みリクエストと未承認リクエストの両方をサポートします。未承認リクエストは公開データのみを取得しますが、承認済みリクエストは現在認証されているユーザーに関する情報やプライベートな情報も取得できます。

サポートされている操作
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

割り当て使用量

YouTube Data API は、デベロッパーがサービスを意図したとおりに使用し、サービスの品質を不当に低下させたり、他のユーザーのアクセスを制限したりするアプリケーションを作成しないように、割り当てを使用します。すべての API リクエスト（無効なリクエストを含む）に、少なくとも 1 ポイントの割り当て費用が発生します。アプリケーションで使用可能な割り当ては API Console で確認できます。

YouTube Data API を有効にしているプロジェクトには、1 日あたり 10,000 ユニットのデフォルトの割り当てが割り当てられます。これは、API ユーザーの圧倒的多数にとって十分な量です。デフォルトの割り当ては変更される可能性がありますが、割り当ての最適化とインフラストラクチャのスケーリングを API ユーザーにとってより有意義な方法で行うのに役立ちます。割り当ての使用状況は、API Console の [割り当て] ページで確認できます。

注: 割り当て上限に達した場合は、YouTube API サービスの割り当て増加リクエスト フォームに記入して、割り当ての追加をリクエストできます。

割り当て使用量の計算

Google は、各リクエストに費用を割り当てることで、割り当て使用量を計算します。オペレーションのタイプによって割り当て費用が異なります。次に例を示します。

  • リソース（チャンネル、動画、再生リスト）のリストを取得する読み取りオペレーションの費用は、通常 1 ユニットです。
  • リソースの作成、更新、削除を行う書き込みオペレーションの費用は通常 50 ユニットです。
  • 検索リクエストの費用は 100 ユニットです。
  • 動画のアップロードには 100 ユニットの費用がかかります。

API リクエストの割り当て費用の表に、各 API メソッドの割り当て費用が示されています。これらのルールに留意して、アプリケーションが割り当ての範囲内で 1 日に送信できるリクエスト数を見積もることができます。

リソースのパーツ

この API ではリソースのパーツの取得が可能で、実際にこれを要求することにより、アプリケーションが不要なデータの転送、解析、保存を実行しないようにしています。このアプローチにより、API はネットワーク、CPU、メモリの各リソースをより効率的に使用できます。

API は、API レスポンスに含めるリソース プロパティを特定できる 2 つのリクエスト パラメータをサポートしています。これらのパラメータについては、次のセクションで説明します。

  • part パラメータは、リソースに対して返されるプロパティのグループを識別します。
  • fields パラメータは、API レスポンスをフィルタして、リクエストされたリソース部分内の特定のプロパティのみを返します。

part パラメータの使用方法

part パラメータは、リソースを取得または返す API リクエストに必要なパラメータです。API レスポンスに含める最上位レベル（ネストされていない）のリソース プロパティを 1 つ以上指定します。たとえば、video リソースには次の部分があります。

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、API サーバーが取得する（または取得しない）メタデータ フィールドのグループと考えることができます。そのため、part パラメータでは、アプリケーションが実際に使用するリソース コンポーネントを選択する必要があります。この要件には、主に次の 2 つの目的があります。

  • アプリケーションが使用しないメタデータ フィールドの取得に API サーバーが時間を費やすのを防ぐことで、反応時間を短縮できます。
  • アプリケーションが取得する不要なデータの量を低減（または排除）することで、帯域幅使用量を節減できます。

今後リソースのパーツが追加された場合でも、アプリケーションがサポートしていない新たに導入されたプロパティをリクエストすることはないため、上記の利点が損なわれることはありません。

fields パラメータの使用方法

fields パラメータは API レスポンスをフィルタします。これにより、part パラメータ値で指定されたリソース部分のみがレスポンスに含まれるため、レスポンスには特定のフィールド セットのみが含まれます。fields パラメータを使用すると、API レスポンスからネストされたプロパティを削除して、帯域幅の使用量をさらに削減できます。（part パラメータを使用して、レスポンスからネストされたプロパティをフィルタすることはできません）。

次のルールは、XPath 構文に大まかに基づいた fields パラメータ値のサポートされている構文について説明しています。

  • 複数のフィールドを選択する場合は、カンマ区切りのリスト（fields=a,b）を使用します。
  • アスタリスク（fields=*）をワイルドカードとして使用して、すべてのフィールドを識別します。
  • API レスポンスに含めるネストされたプロパティのグループを指定するには、かっこ（fields=a(b,c)）を使用します。
  • ネストされたプロパティを識別するには、スラッシュ（fields=a/b）を使用します。

実際には、これらのルールにより、複数の異なる fields パラメータ値で同じ API レスポンスを取得できることがよくあります。たとえば、再生リストのアイテム ID、タイトル、および再生リストのすべてのアイテムの位置を取得する場合は、次のいずれかの値を使用できます。

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

注: 他のすべてのクエリ パラメータの値と同じように、fields パラメータ値には URL エンコードを使用する必要があります。読みやすくするために、このドキュメントの例ではエンコードを省略します。

パーツのリクエストのサンプル

次の例は、part パラメータと fields パラメータを使用して、API レスポンスにアプリケーションで使用されるデータのみが含まれるようにする方法を示しています。

  1. 例 1 は、4 つのパートと kind プロパティおよび etag プロパティを含む動画リソースを返します。
  2. 例 2 は、2 つのパートと kind プロパティおよび etag プロパティを含む動画リソースを返します。
  3. 例 3 は、2 つのパートを含むが kind プロパティと etag プロパティは除外する動画リソースを返します。
  4. 例 4 は、2 つのパートを含む動画リソースを返しますが、リソースの snippet オブジェクト内の kind、etag、一部のネストされたプロパティは除外されます。
例 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "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"
   }
  }
 ]
}
例 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "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"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
例 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "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"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
例 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

パフォーマンスの最適化

ETag の使用

ETags は HTTP プロトコルの標準的な部分であり、アプリケーションが特定の API リソースの特定のバージョンを参照できるようにします。リソースはフィード全体か、そのフィード内のアイテムになります。この機能は、次の使用事例をサポートしています。

  • キャッシュおよび条件付き取得 – アプリケーションは、API リソースとその ETags をキャッシュできます。そのため、アプリケーションが保存済みのリソースを再度リクエストした場合は、そのリソースに関連付けられた ETag が指定されます。リソースが変更されている場合、API は変更されたリソースと、そのバージョンのリソースに関連付けられた ETag を返します。リソースが変更されていない場合、API はリソースが変更されていないことを示す HTTP 304 レスポンス（Not Modified）を返します。この方法でキャッシュされたリソースを提供することにより、反応時間と帯域幅使用量を低減することができます。

    Google API のクライアント ライブラリは、ETags のサポートの点で異なります。たとえば、JavaScript クライアント ライブラリは、If-Match と If-None-Match を含む許可されたリクエスト ヘッダーのホワイトリストを介して ETag をサポートしています。ホワイトリストでは、リソースの ETag が変更されていない場合にブラウザのキャッシュからリソースを提供できるように、通常のブラウザ キャッシュの発生を許可します。一方、Obj-C クライアントは ETags をサポートしていません。

  • 変更内容の誤った上書きに対する保護 – ETags は、複数の API クライアントが相互の変更内容を誤って上書きしてしまう状況を防ぐのに役立ちます。リソースを更新または削除する場合、アプリケーションではリソースの ETag を指定できます。ETag がそのリソースの最新バージョンと一致しない場合、API リクエストは失敗します。

アプリケーションで ETags を使用すると、次のような複数の利点を得られます。

  • キャッシュ済みの変更されていないリソースのリクエストに対して API が迅速に応答するようになるため、反応時間と帯域幅使用量が低減されます。
  • 別の API クライアントによって発生したリソースの変更を誤って上書きしてしまう状況を回避できます。

Google APIs Client Library for JavaScript は If-Match と If-None-Match の HTTP リクエスト ヘッダーをサポートしているため、通常のブラウザ キャッシュのコンテキスト内で ETag を機能させることができます。

gzip の使用

各 API レスポンスで必要な帯域幅は、gzip 圧縮を有効にして低減させることもできます。API レスポンスの解凍には追加の CPU 時間が必要になりますが、ネットワーク リソースの消費量低下には、そのコストを補うだけの利点があります。

gzip エンコードされたレスポンスを受け取るには、次の 2 つの操作を実行する必要があります。

  • Accept-Encoding HTTP リクエスト ヘッダーを gzip に設定します。
  • ユーザー エージェントを変更して、文字列 gzip を含めます。

次のサンプルの HTTP ヘッダーは、上記の gzip 圧縮を有効にする要件を示したものです。

Accept-Encoding: gzip
User-Agent: my program (gzip)