はじめに
このドキュメントは、YouTube と情報をやり取りするアプリケーションを作成するデベロッパーの方を対象としています。このドキュメントでは、YouTube および API 自体の基本的な概念について説明します。また、API がサポートするさまざまな機能の概要についても説明します。
始める前に
-
Google API Console にアクセスし、API キーをリクエストして、アプリケーションを登録するには、Google アカウントが必要です。
-
Google Cloud Console でプロジェクトを作成し、アプリケーションが API リクエストを送信できるように認証情報を取得します。
-
プロジェクトを作成したら、アプリケーションで登録されているサービスの 1 つが YouTube Data API であることを確認します。
- API Console に移動し、登録したプロジェクトを選択します。
- [有効な 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 つまたは複数の再生リストの動画などを 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 にアップロードして動画に関連付けます。
Operations | |
---|---|
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
ユニットです。 - 動画のアップロード 1 回あたりの費用は
1600
ユニットです。
[API リクエストの割り当て費用] の表には、各 API メソッドの割り当て費用が表示されます。これらのルールに留意することで、割り当てを超過することなく、アプリケーションが 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
パラメータは、part
パラメータ値で指定されたリソース パーツのみを含む API レスポンスをフィルタします。これにより、レスポンスには特定のフィールド セットのみが含まれます。fields
パラメータを使用すると、ネストされたプロパティを API レスポンスから削除できるため、帯域幅の使用量をさらに削減できます。(part
パラメータを使用して、レスポンスからネストされたプロパティをフィルタすることはできません)。
以下のルールでは、fields
パラメータ値でサポートされている構文について説明します。この構文は XPath の構文に大まかに基づいています。
- 複数のフィールドを選択するには、カンマ区切りリスト(
fields=a,b
)を使用します。 - すべてのフィールドを識別するワイルドカードとしてアスタリスク(
fields=*
)を使用します。 - かっこ(
fields=a(b,c)
)を使用して、API レスポンスに含めるネストされたプロパティのグループを指定します。 - ネストされたプロパティを指定するには、スラッシュ(
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
オブジェクト内のネストされたプロパティも除外しています。
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
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 thepart
parameter value so that thecontentDetails
andstatus
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 thefields
parameter to remove allkind
andetag
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 thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
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)