YouTube Data API の概要

はじめに

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

始める前に

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

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

3. プロジェクトを作成したら、YouTube Data API が、アプリケーションで使用するよう登録されているサービスのいずれかであることを確認します。

   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 を使用してやり取りできる各種リソースについて説明したものです。

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

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

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

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

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

割り当て使用量

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. 例 1 は、4 つのパートと kind プロパティと etag プロパティを含む動画リソースを返します。
2. 例 2 は、2 つのパートと kind プロパティと etag プロパティを含む動画リソースを返します。
3. 例 3 は、2 つのパートを含み、kind プロパティと etag プロパティを除外した動画リソースを返します。
4. 例 4 は、2 つのパートを含む動画リソースを返しますが、kind と etag、およびリソースの snippet オブジェクト内にネストされたプロパティの一部を除外しています。

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

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

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

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

パフォーマンスの最適化

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