このページは Cloud Translation API によって翻訳されました。

YouTube Data API の概要

はじめに

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

始める前に

Google API Console へのアクセス、API キーのリクエスト、アプリケーションの登録を行うには、Google アカウントが必要です。
Google Developers Console でプロジェクトを作成し、認証情報を取得して、アプリケーションが API リクエストを送信できるようにします。
プロジェクトを作成したら、YouTube Data API が、アプリケーションで使用するよう登録されているサービスのいずれかであることを確認します。
1. API Console に移動し、登録したプロジェクトを選択します。
2. 有効な API のページにアクセスします。 API のリストで、YouTube Data API v3 のステータスが [オン] になっていることを確認します。
ユーザー認証を必要とする API メソッドをアプリケーションで使用する場合は、認証ガイドに目を通して OAuth 2.0 認証の実装方法を習得しておきます。
API の実装を簡素化するためのクライアントライブラリを選択します。
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 ユニットの割り当てが設定されています。これは、YouTube の API ユーザーの大多数に対して十分な量です。デフォルトの割り当ては変更される可能性がありますが、これは割り当ての配分を最適化し、API ユーザーにとってより意味のある方法でインフラストラクチャをスケーリングするのに役立ちます。割り当ての使用状況は、API Console の [割り当て] ページで確認できます。

注: 割り当て上限に達した場合は、次の方法で追加の割り当てをリクエストできます。割り当て拡張を完了するリクエストフォームを提出してください。

割り当て使用量の計算

Google では、各リクエストに費用を割り当てて、割り当て使用量を計算します。さまざまな種類のオペレーションごとに割り当て費用が異なります。例:

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

[API リクエストの割り当て費用] 表に、割り当て費用が含まれます。これらのルールを念頭に置くことで、1 対 1 のチャットからクォータを超過せずにアプリケーションが 1 日あたりに送信できるデータの数です。

リソースのパーツ

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

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

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

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

複数のフィールドを選択するには、カンマ区切りのリスト（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 は、4 つのパートと kind プロパティと etag プロパティを含む動画リソースを返します。
例 2 は、2 つのパートと kind プロパティと etag プロパティを含む動画リソースを返します。
例 3 は、2 つのパートを含み、kind プロパティと etag プロパティを除外した動画リソースを返します。
例 4 は、2 つのパートを含む動画リソースを返しますが、kind と etag、およびリソースの snippet オブジェクト内にネストされたプロパティの一部を除外しています。

で確認できます。 <ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph>

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

をご覧ください。 <ph type="x-smartling-placeholder">

</ph>

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

をご覧ください。 <ph type="x-smartling-placeholder">

</ph>

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

をご覧ください。 <ph type="x-smartling-placeholder">

</ph>

例 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 の使用

HTTP プロトコルの標準部分である ETags を使用すると、アプリケーションが特定の 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)

YouTube Data API の概要

はじめに

始める前に

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

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

割り当て使用量

割り当て使用量の計算

リソースのパーツ

part パラメータの使用方法

fields パラメータの使用方法

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

パフォーマンスの最適化

ETag の使用

gzip の使用

`part` パラメータの使用方法

`fields` パラメータの使用方法