YouTube Data API の概要

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

はじめに

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

作業を始める前に

  1. Google Cloud Console へのアクセス、API キーのリクエスト、アプリケーションの登録を行うために Google アカウントが必要です。

  2. API リクエストを送信できるようにするため、Google にアプリケーションを登録します。

  3. アプリケーションを登録したら、アプリケーションが使用するサービスの 1 つとして YouTube Data API を選択します。

    1. Cloud Console に移動し、登録したプロジェクトを選択します。
    2. [Services] ペインをクリックします。
    3. API のリストから YouTube Data API を探し、ステータスを ON にします。

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

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

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

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

多くの場合、リソースには他のリソースへの参照が含まれている点に注意してください。たとえば、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 では、デベロッパーが目的どおりにサービスを使用できることと、不当にサービス品質を低下させたり他のリソースへのアクセスを制限したりしてしまうアプリケーションの作成を防ぐことを目的としてクォータを使用します。アプリケーションで使用できるクォータは、Cloud console の [Quotas] ペインで確認できます。

Google では、各リクエストにコストを割り当ててクォータの使用量を計算します。ただし、コストはリクエストごとに同じというわけではありません。リクエストのクォータ コストに影響を与えるのは、主に次の 2 つの要因です。

  1. クォータ コストは操作の種類ごとに異なります。

    • 返される各リソースの ID を取得するだけの単純な読み取り操作の場合、コストは約 1 ユニットです。
    • 書き込み操作のコストは、約 50 ユニットです。
    • 動画アップロードのコストは、約 1600 ユニットです。

  2. 読み取りおよび書き込み操作で使用されるクォータの量は、各リクエストが取得するリソースのパーツ数に応じて異なります。また、insert および update 操作では、データの書き込みだけでなくリソースを返す処理も実行される点に注意してください。たとえば、再生リストの挿入では書き込み操作に 50 ユニットのコストがかかるだけでなく、返された再生リスト リソースにもコストがかかります。

    次のセクションで説明しますが、各 API リソースは複数のパーツに分かれています。たとえば、playlist リソースは snippet と status という 2 つのパーツに分けられますが、channel リソースは 6 つのパーツに分けられます。また、video リソースは 10 個のパーツに分けられます。各パーツには関連するプロパティのグループが格納されています。グループはアプリケーションが実際に使用するデータだけを取得するように設計されています。

    リソース データを返す API リクエストでは、そのリクエストで取得するリソースのパーツを指定する必要があります。リクエストのクォータ コストは、パーツごとに約 2 ユニットが追加で消費されます。そのため、各動画の snippet パーツだけを取得する videos.list リクエストのコストは 3 ユニットになります。ただし、各リソースのすべてのパーツを取得する videos.list リクエストのコストは約 21 クォータ ユニットになります。

このような規則を念頭に置きながら、クォータを超過しない範囲でアプリケーションが 1 日あたりに送信できる読み取り、書き込み、またはアップロードの各リクエスト数を見積もることができます。たとえば、1 日あたりのクォータが 5,000,000 ユニットの場合、アプリケーションが送信できるリクエスト数の制限はおおよそ次のようになります。

  • それぞれリソースのパーツを 2 つ取得する 1,000,000 件の読み取り操作。
  • それぞれリソースのパーツを 2 つ取得する 50,000 件の書き込み操作と 450,000 件の追加読み取り操作。
  • それぞれリソースのパーツを 3 つ取得する 2,000 件の動画アップロード操作、7,000 件の書き込み操作、および 200,000 件の読み取り操作。

重要: アプリケーションが必要なリソース パーツだけを取得することで 1 日あたりのクォータ量を節約できるだけでなく、システム全体をより効率的に動作させることができます。

リソースのパーツ

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

この API は、2 つのリクエスト パラメータをサポートしています。これらについては、以降のセクションで説明します。各セクションの説明を読み、API レスポンスに含める必要があるリソース プロパティを特定してください。

  • part パラメータでは、リソースに対して返す必要があるプロパティのグループを指定します。
  • fields パラメータでは、リクエストされたリソースのパーツ内で特定のプロパティだけを返すように API レスポンスをフィルタリングします。

part パラメータについて

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

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

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

  • API クォータの使用量を管理することができます。API レスポンスで取得するパーツ数が増えるほど API での使用量も増加し、使用可能なクォータ量が低下します。
  • アプリケーションが使用しないメタデータ フィールドの取得に API サーバーが時間を費やすのを防ぐことで、反応時間を低減できます。
  • アプリケーションが取得する不要なデータの量を低減（または排除）することで、帯域幅使用量を節減できます。

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

fields パラメータについて

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

次の規則は、fields パラメータ値でサポートされている構文について説明したものです。これは、おおよそ XPath の構文に基づいています。

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

実際には、同じ API レスポンスを取得する場合でも、複数の fields パラメータ値による表現が考えられます。たとえば、再生リストのアイテム 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 つのパーツを含み、kind および etag とリソースの snippet オブジェクトにあるネストされた一部のプロパティを除外した動画リソースを返します。
例 1

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

説明: この例では video リソースを取得し、API レスポンスに含める必要がある複数のリソース パーツを指定します。

API レスポンス:


{ 
 "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

説明: この例では part パラメータ値を変更し、contentDetails プロパティおよび status プロパティがレスポンスに含まれないようにします。

API レスポンス:


{ 
 "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)

説明: この例では fields パラメータを追加し、API レスポンスからすべての kind プロパティおよび etag プロパティを削除します。

API レスポンス:


{ 
 "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

説明: この例では例 3 の fields パラメータを変更し、API レスポンスで、各動画リソースの snippet オブジェクトに channelId、title、および categoryId の各プロパティだけが含まれるようにします。

API レスポンス:


{ 
 "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"
   }
  }
 ]
}

パフォーマンスの最適化

ETags の使用

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

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

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

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

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

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

Google APIs Client Library for JavaScript は If-Match および If-None-Match の各 HTTP リクエスト ヘッダーをサポートしているため、ETags が通常のブラウザ キャッシュのコンテキスト内で動作するようになります。

gzip の使用

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

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

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

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

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