|
日本語
| Sign in
|
日本語
| Sign in
YouTube Data API を利用すると、通常 YouTube ウェブサイト上で実行される機能をアプリケーションで実行できます。API を利用することで、アプリケーションは YouTube 動画の検索や、標準の動画フィード、コメント、動画レスポンスの取得ができます。また、YouTube に動画をアップロードしたり、既存の動画を更新したりすることができます。また、再生リスト、登録チャンネル、ユーザー プロフィールなども利用できます。さらに、ユーザーが再生リスト、登録チャンネル、連絡先など、アカウント固有のエンティティを作成できるように、認証されたリクエストをアプリケーションから送信することができます。
このドキュメントは YouTube と情報をやり取りするクライアント アプリケーションを作成するプログラマの方を対象としています。ここでは、HTTPと XML を直接使う基本的な API 処理の例を示します。Java や PHP のデベロッパーの方には、Java や PHP のクライアント ライブラリを使って類似の機能を実行する方法を説明した言語ごとのデベロッパー ガイドをお読みいただく方が便利かもしれません。
このドキュメントでは、Google Data API プロトコルの背後にある一般原則を理解していることを前提としています。Google Data API は、ウェブ上のデータを読み書きするシンプルな標準プロトコルを提供します。また、Atom 1.0 と RSS 2.0 の各シンジケーション フォーマットと、Atom Publishing Protocol に基づいています。
このドキュメントは、次のセクションに分かれています。
認証セクションでは、特定のユーザー アカウントに API の操作を関連付けるために利用可能な 2 種類の認証方式について説明します。このセクションでは、YouTube Data API と他の Google Data API での認証の違いについても概説します。このドキュメントを通して、それぞれのAPI 関数の説明のところで、その関数にユーザーの認証が必要かどうかを明示しています。
動画のフィードとエントリの説明セクションでは、API の応答の例を示し、動画のリストまたは検索結果のセットから 1 本の動画の情報を抽出する方法について説明します。また、このセクションでは、通常 YouTube ウェブサイトに表示される動画情報と、YouTube Data API レスポンスの XML 要素がどのように対応するかも説明します。個別の動画エントリを更新するための API リクエストのフォーマットについても説明します。
動画の取得と検索セクションでは、動画のリストを取得する方法について説明します。YouTube Data API では、評価の高い動画、人気の動画など、標準フィードのタイプをいくつか定義しています。また、特定のユーザーがアップロードした動画のリストや関連動画のリストを取得する方法も説明します。関連動画とは、特定の動画に似ていると YouTube が判断した動画です。最後に、ユーザーが YouTube 動画ライブラリを検索し、特定の検索用語やカテゴリに一致する動画を見つけ出せるようにするための API の使用方法についても説明します。
動画のアップロードセクションでは、アプリケーションから YouTube にユーザーが動画をアップロードできるようにする 2 種類の方法について簡単に説明します。また、各アップロード方法の処理フロー図を示し、それぞれの方法が、使用する認証方式とどのように関連するかも説明します。
API 関数の中には、ユーザーに動画をアップロードしてもらわないと使えないものもあります。たとえば、ある動画に動画レスポンスを追加する機能を提供する API が該当します。ただし、ユーザーが動画レスポンスとして新しい動画をアップロードする場合、その新しい動画が既存の動画へのレスポンスと認識されるためには、その前にクライアントは動画アップロード手順に従って YouTube に動画を追加しておく必要があります。
動画の更新と削除セクションでは、ユーザーが自分の動画を更新または削除できるようにする方法を説明します。
コミュニティ機能の使用セクションでは、YouTube の動画に対してユーザーが反応を示すことができる API の関数について説明します。これらの関数は、既存の動画についての評価、コメント、動画レスポンス、苦情を投稿する要求を伝えます。API を使用して、動画のコメントや動画レスポンスのリストを取得し、動画レスポンスを削除することもできます。
動画の保存と収集セクションでは、お気に入りの動画、動画再生リスト、YouTube チャンネルへの登録に対して、API を使用してアクセス、作成、更新する方法について説明します。
ユーザー交流の利用セクションでは、API を使用して、ユーザー プロフィールを取得し、更新する方法について説明します。また、ユーザー コンタクトを取得、追加、更新、削除する方法も説明します。
認証を受けると、ユーザーは特定の YouTube アカウントにコンテンツや情報をリンクする YouTube 機能にアクセスできるようになります。この機能を利用するには、ユーザーまたはアプリケーションがそのアカウントの YouTube ユーザー名とパスワードを提示する必要があります。たとえば、動画をアップロードしたり、既存の動画にコメントを追加したりするには、YouTube にログインする必要があります。
このドキュメントで説明する API 関数には、ユーザー認証が必要なものが多く含まれます。たとえば、コンテンツの作成、更新、削除のための API 関数はすべてユーザー認証を必要とします。
認証が必要な機能を実装する場合、明示的に認証を必要としないリクエストであっても、適切な認証ヘッダーをすべてのリクエストに含めることをお勧めします。
適切な認証を受けるには、リクエストに X-GData-Key ヘッダーと Authorization ヘッダーが含まれる必要があります。X-GData-Key ヘッダーはデベロッパー キー、つまりアプリケーションを一意に識別する値を指定します。Authorization ヘッダーには、AuthSub と ClientLogin のいずれかの認証方式を使って各ユーザーごとに入手したトークンを指定します。これにより、ユーザーはアカウント固有の YouTube 機能にアクセスすることが可能になります。アプリケーションに適した認証方式を選択するには、次の内容を参考にしてください。
AuthSub プロキシ認証では、ウェブ アプリケーションは、ユーザーの YouTube ユーザー名とパスワードにアクセスしなくとも、ユーザーを各自の YouTube アカウントに対して認証することができます。動画、コメント、評価、コンタクトなどの情報をユーザーが自分の YouTube アカウントにリンクできるようなウェブ アプリケーションを構築する場合は、AuthSub 認証を使うことをお勧めします。
ClientLogin 認証を使う場合は、すべての API アクションを 1 つの YouTube アカウントに関連付けることになります。ClientLogin は、スタンドアロンで、シングルユーザーの、インストールされたクライアント (デスクトップ アプリケーションなど) を構築する場合に使うことをお勧めします。この場合、アプリケーションはユーザーに YouTube ユーザー名とパスワードを入力するように要求し、それらの値を使って ClientLogin 認証トークンをリクエストします。
注: ClientLogin 認証を実装し、ユーザーにユーザー名とパスワードを入力するように要求するウェブ アプリケーションを構築することは推奨されていません。ユーザーがアクションを自分の YouTube アカウントに関連付けるウェブ アプリケーションを構築する場合は AuthSub 認証を使います。
デベロッパー キーは、API リクエストを送信する YouTube デベロッパーを識別します。クライアント ID は、ロギングとデバッギングの際にアプリケーションを識別するのに使われます。デベロッパー キーとクライアント ID を入手するには http://code.google.com/apis/youtube/dashboard/ にアクセスしてください。
API リクエストを行う場合、次の例に示すように、X-GData-Key リクエスト ヘッダーを使ってデベロッパー キーを指定し、X-GData-Client ヘッダーを使ってクライアント ID を指定します。
X-GData-Client: <client_id> X-GData-Key: key=<developer_key>
AuthSub の処理内容は http://code.google.com/apis/accounts/AuthForWebApps.html により詳しく記載されています。また、YouTube AuthSub 認証のベース URL とサービスのスコープ – http://gdata.youtube.com – は、オンラインで参照できる AuthSub ドキュメントで指定された URL やスコープと異なっていますので注意してください。
認証のトークンを入手するには、次の URL に HTTP POST リクエストを送信します:
https://www.google.com/accounts/AuthSubRequest?
next=http%3A%2F%2Fwww.example.com%2Fupload.html
&scope=http%3A%2F%2Fgdata.youtube.com
&session=0
&secure=0
POST リクエストには次のパラメータが含まれます:
next パラメータには、YouTube にログインした後でユーザーがリダイレクトされる URL が含まれます。
scope パラメータには、あなたのサイトがユーザーに代わってアクセスすることをユーザーが許可したサービスを指定します。このパラメータの値は http://gdata.youtube.com である必要があります。
secure パラメータには、認証サービスから戻されるトークンがセキュアかノンセキュアかを示すブーリアン値 (0 または 1) が含まれます。セキュアなトークンは Google に登録したウェブサイトに対してのみ発行されます。セキュアなトークンを使うUpload API リクエストは、デジタル署名されている必要があります。セキュアなトークンの詳細は、Google AuthSub のドキュメントを参照してください。
session パラメータには、認証サービスにより戻された使い捨て認証トークンを、複数回使えるセッション トークンと交換できるかどうかを示すブーリアン値 (0 または 1) が含まれます。使い捨てトークンをセッション トークンと交換できることを示すには、この変数を 1 に設定します。セッション トークンをリクエストする方法の説明は Google AuthSub ドキュメントを参照してください。
ユーザーが YouTube の認証サービスを使ってログインした後、YouTube は AuthSub リクエストの next パラメータで指定された URL にユーザーをリダイレクトします。リダイレクトには、次の例に示すように、URL の token パラメータで指定された使い捨て認証トークンが含まれます。AuthSub リクエストの session パラメータの値が 1 の場合、AuthSubSessionToken リクエストを送信することによって、1 回用トークンとセッション トークンを交換することができます。
次の URL は、サイトへのリダイレクトに token パラメータがどのように出現するかを示しています。リダイレクトの URL は AuthSub リクエストの next パラメータの値として提供されているはずです。
http://www.example.com/upload.html?token=CKF50YzIHxCT85KMAg
AuthSub 認証トークンを使って認証された API リクエストを行う場合、次の例に示すように、リクエストで Authorization HTTP リクエスト ヘッダーを指定する必要があります。注: このドキュメントでは、別途指定しない限り、サンプル リクエストでは AuthSub 構文を使います。
Authorization: AuthSub token=<authentication_token> X-GData-Key: key=<developer_key>
ClientLogin を使って認証 API リクエストを行うには、リクエストに関連付けられた YouTube ユーザー アカウントを識別する必要があります。また、シングル ユーザー認証には YouTube の ClientLogin システムを使う必要があります。そのユーザーの YouTube アカウントのユーザー名とパスワードを入力して、そのアカウントに関連付けられた処理を実行する権限をそのユーザーが持っていることを確認します。これにより、認証されたアクションがそのアカウントに関連付けられます。次の説明は、標準的な ClientLogin の説明と多少異なりますのでご注意ください。
認証のトークンを入手するには、次の URL に HTTP POST リクエストを送信します:
https://www.google.com/youtube/accounts/ClientLogin
リクエストには次のガイドラインが適用されます:
POST リクエストでは Content-Type ヘッダーに、値 application/x-www-form-urlencoded を指定する必要があります。
POST のボディには、次のフォーマットの文字列が含まれる必要があります:
Email=<youtube_username>&Passwd=<youtube_password>&service=youtube&source=<source>
この文字列を次のように変更します:
文字列 <youtube_username> をユーザーの YouTube アカウント ユーザー名に置き換えます。
文字列 <youtube_password> をユーザーの YouTube アカウント パスワードに置き換えます。
ロギングのために、文字列 <source> を、アプリケーションを識別する短い文字列に置き換えます。
<youtube_username>、<youtube_password>、<source> の値はすべて URL エンコードされている必要があります。
Google は、指定されたユーザーの YouTube アカウントに関連付けられた API 処理を実行するために必要な認証トークンを含むレスポンスを戻します。認証トークンはそのページでの Auth 値になります。また、そのページでの YouTubeUser 値は、そのユーザーの YouTube アカウント ユーザー名になります。ページから認証トークンとユーザー名を抽出し、それらの値を API リクエストで送信する必要があります。認証トークンは一定期間で期限が切れることに注意してください。アプリケーションでこの認証処理を繰り返し、トークンが期限切れで拒否されたら認証トークンの値を更新する必要があることがあります。
注: Google ClientLogin ドキュメントでは、ClientLogin 認証を使ってアプリケーションに CAPTCHA チャレンジを導入する方法も説明されています。
認証の例
たとえば、ユーザー名とパスワードがそれぞれ testuser と testpassword である YouTube アカウントを認証するとします。次の例に示すように、Linux の curl コマンドを使って HTTP POST リクエストをシミュレートすることができます:
curl --location https://www.google.com/youtube/accounts/ClientLogin \
--data 'Email=testuser&Passwd=testpassword&service=youtube&source=TestLogin' \
--header 'Content-Type:application/x-www-form-urlencoded'
認証リクエストが成功した場合、リクエストへのレスポンスは次のフォーマットになります (例では Auth トークン値が短くなっていることに注意してください)。
Auth=AIwbFARksypDdUSGGYRI_5v7Z9TaijoPQqpIfCEjTFPAikn_---OC-I1VJtQ YouTubeUser=testuser
ClientLogin 認証トークンを使って認証された API リクエストを行う場合、次の例に示すように、リクエストで Authorization HTTP リクエスト ヘッダーを指定する必要があります。
Authorization: GoogleLogin auth=<authentication_token> X-GData-Key: key=<developer_key>
動画フィードまたは検索結果リストを取得するとき、YouTube からは、結果セットに含まれる動画 1 本につき <entry> タグを 1 つ含む Atom フィードが返されます。レスポンスのルート XML タグは <feed> タグです。フィードには、結果セットに含まれる個別の動画に関する情報のほか、リストに含まれる結果の総数、リストの最初の項目のインデックス、リストに含まれる項目数など、フィードに関するメタデータも含まれます。
次の XML は、動画フィードが含まれている YouTube Data API レスポンスのフォーマットを示しています:
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:gml='http://www.opengis.net/gml' xmlns:georss='http://www.georss.org/georss' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/standardfeeds/top_rated</id> <updated>2008-02-21T18:57:10.801Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#video'/> <title type='text'>Top Rated</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/browser?s=tr'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?start_index=1&max-results=25'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?start_index=26&max-results=25'/> <author> <name>YouTube</name> <uri>http://www.youtube.com/</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>99</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id> <published>2007-02-16T20:22:57.000Z</published> <updated>2007-02-16T20:22:57.000Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://gdata.youtube.com/schemas/2007#video"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="Steventon"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="walk"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="Darcy"/> <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat" term="Entertainment" label="Entertainment"/> <title type="text">My walk with Mr. Darcy</title> <content type="html"><div ... html content trimmed ...></content> <link rel="self" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b"/> <link rel="alternate" type="text/html" href="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <link rel="http://gdata.youtube.com/schemas/2007#video.responses" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/> <link rel="http://gdata.youtube.com/schemas/2007#video.ratings" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/ratings"/> <link rel="http://gdata.youtube.com/schemas/2007#video.complaints" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/complaints"/> <link rel="http://gdata.youtube.com/schemas/2007#video.related" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/> <author> <name>Andy Samplo</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <media:group> <media:title type="plain">Shopping for Coats</media:title> <media:description type="plain"> What could make for more exciting video? </media:description> <media:keywords>Shopping, parkas</media:keywords> <yt:duration seconds="79"/> <media:category label="People" scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People </media:category> <media:content url='http://www.youtube.com/v/ZTUVgYoeN_b' type='application/x-shockwave-flash' medium='video' isDefault='true' expression="full" duration='215' yt:format="5"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="1"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="6"/> <media:player url="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/2.jpg" height="97" width="130" time="00:00:03.500"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/1.jpg" height="97" width="130" time="00:00:01.750"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/3.jpg" height="97" width="130" time="00:00:05.250"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/0.jpg" height="240" width="320" time="00:00:03.500"/> </media:group> <yt:statistics viewCount="93"/> <gd:rating min='1' max='5' numRaters='435' average='4.94'/> <gd:comments> <gd:feedLink href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments" countHint='2197'/> </gd:comments> </entry>
次のスクリーンショットは、YouTube で動画リストに情報がどのように表示されるかを示しています。スクリーンショットの次に、スクリーンショット中で番号を付けた表示要素と、API レスポンスに含まれる情報との対応を説明します。
スクリーンショットには次の情報が示されています:
この要素は、結果セットのタイトルを示します。アプリケーションでは、この値として <title> タグの値を使用することも、リクエストされたフィードや検索結果に適切なその他のテキストを選択することもできます。
図内のテキスト「1 - 20 of about 13,800」には、API レスポンスの次の要素が使われています:
ユーザーはプルダウン メニューを使って orderby パラメータと time パラメータの値を選択できます。リファレンス ガイドには YouTube Data API でサポートされるクエリ パラメータの一覧表があり、各パラメータが使用可能なクエリのタイプが説明されています。
この要素は動画のサムネイル画像です。YouTube API レスポンスでは、1 本の動画に、それぞれ <media:thumbnail> タグで識別される複数のサムネイル画像が含まれることがあります。YouTube ウェブサイトでは、サムネイル画像は、その動画に関する詳細情報 (コメントや動画レスポンスなど) が表示され、ユーザーが動画を再生できるページにリンクしています。動画エントリで、rel 属性の値が alternate 属性値を持つ <link> タグは、ユーザーが動画を見ることができる YouTube ページの URL を示します。YouTube 検索結果のページでは、サムネイル画像がその URL にリンクしています。
アプリケーションでターゲット ページを表示するための情報を入手するには、動画エントリの edit URL にHTTPリクエストを送信します。次のセクション「動画エントリに関連するフィードの識別」では、エントリの edit URL を識別する方法を説明します。
動画の横にあるタイトルは、その動画の <media:title> タグの値です。タイトルの下のテキストは、<media:description> タグの値です。
右側の列には次の値が表示されます:
最初の行には、その動画の <published> タグの値に対応するテキストが表示されます。スクリーンショットに示されているように、<published> タグには、動画がいつ投稿されたかを近似値で示す、テキストに変換されたタイムスタンプが含まれることに注意してください (例: 「5 months ago」)。ただし、「10/22/07」や「Oct. 22 2007」のように日付を示すこともできます。
2 行目は、動画の所有者の YouTube ユーザー名を示します。この値は、動画エントリの <author> タグの中にカプセル化された <name> タグによって指定されます。YouTube ウェブサイト上では、このリンクをクリックしたユーザーは動画所有者のプロフィール情報を示すページに導かれます。サイト上でこの情報を取得するには、続けてリクエストを、動画エントリの <author> タグにカプセル化された <uri> タグの値に送信します。
3 行目は動画が再生された回数を示しています。<yt:statistics> タグの viewCount 属性がこの値を示しています。
4 行目は、その動画のユーザー評価の平均値を表示します。この評価は、<gd:rating> タグの average 属性から得ることができます。YouTube では、星の画像を正しく表示するために評価が調整されることに注意してください。たとえば、評価が 2.75 から 3.2499 までの場合は星 3 つの評価になり、3.25 から 3.7499 までの場合は星 3.5 の評価が表示されます。
5 番目の行は動画の長さを示します。<yt:duration> タグは動画の秒数を示します。スクリーンショットでは、値は分と秒 での表示に調整されています (292秒 = 04:52)。
6 番目の行は動画の内容を示すカテゴリの名前を示します。この値は <media:category> タグの label 属性に含まれます。YouTube のウェブサイトでは、カテゴリ名は、そのカテゴリに属する他の動画を表示するページにもリンクしています。カテゴリとキーワードによる検索セクションでは、特定のカテゴリに属する動画をリクエストする方法を説明しています。
結果セットにある 1 本の動画に関するフィードを取得するには、HTTP GET リクエストをそのエントリの edit URL に送信します。次のセクションを参照してください。たとえば、ユーザーが検索結果の中の特定の動画を再生するためにリンクを選択したときに、このリクエストを利用することができます。
YouTube Data API レスポンスの各エントリは、動画に関連するいくつかの API URL を示しています。たとえば、あるエントリは、動画へのコメント、動画への動画レスポンス、動画所有者の YouTube 公開ユーザー プロフィールをリクエストする URL を示します。一部の URL は、情報を取得するためだけでなく、情報の作成、更新、削除にも使われることがあります。たとえば、ある URL に HTTP GET リクエストを送信してその動画へのコメントを取得し、同じ URL に HTTP POST リクエストを送信してその動画にコメントを追加することができます。
このドキュメントのいくつかの API 関数は、動画の edit URL または他のタイプのエントリを参照しています (たとえば再生リスト フィードでは、エントリが動画でなく再生リストに対応しています)。フィード <entry> 内では、edit URL は edit という rel 属性値を持っている <link> タグの href 属性の値です。
次の XML サンプルは、YouTube Data API レスポンスで <link> タグがどのように表示されるかを示しています。例では edit URL が太字で示されています。
<entry> <id>http://gdata.youtube.com/feeds/api/videos/dMH0bHeiRN</id> <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/responses'/> <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/ratings'/> <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/complaints'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> ... </entry>
このドキュメントのコミュニティ機能の使用、動画の保存と収集、ユーザー交流の利用の各セクションでは、YouTube API を使ってリソースをリクエスト、作成、更新、または削除するために特定の関数を使うときの状況を記述したユースケースを示します。各ユースケースでは、ユーザーがそれらのユースケースを実行するために必要な、送信する API リクエストと、解析が必要な API レスポンスからの値について説明しています。これらの手順では、API レスポンスの <link> タグで指定された URL に対して API リクエストを送信する必要があることがよくあります。ユースケースは、<link> タグの rel 属性の値を使って API リクエストの URL を識別します。
たとえば、ある動画の動画レスポンスのリストを取得するには、rel 属性値が http://gdata.youtube.com/schemas/2007#video.responses の <link> タグに関連付けられている URL に対して HTTP GET リクエストを送信します。ある動画に評価を追加するには、rel 属性値が http://gdata.youtube.com/schemas/2007#video.ratings の <link> タグに関連付けられている URL に対して HTTP POST リクエストを送信します。
次のスクリーンショットは、YouTube で個別の動画の情報がどのように表示されるかを示しています。動画リストを表示しているスクリーンショットでは 1 つの API リクエストの情報のみを表示していますが、このページでは、いくつかの API レスポンスを 1 ページにまとめています。
スクリーンショットの次に、スクリーンショット中で番号を付けた表示要素と、コンテンツを含む API レスポンスとの対応を説明します。
このページを表示するには、先にその動画エントリのフィードを取得します。動画エントリ フィードの XML は、フィードまたは検索結果セットでその動画に対して表示されるコンテンツと同一です。
スクリーンショットには次の情報が示されています:
セクション 1 には動画のタイトルが表示されます。API レスポンスでは、<media:title> タグに動画のタイトルが含まれています。
セクション 2 には動画本体が表示されます。次のコード スニペットを使って自分のページに YouTube 動画を表示することができます。MEDIA_CONTENT_URL 変数と MEDIA_CONTENT_TYPE 変数には、XML フィードから該当する値を代入します:
ウェブページ上で動画を再生するには、MEDIA_CONTENT_URL 変数を、yt:format 属性値が 5 である <media:content> タグの url 属性値に置き換えます。同じく、MEDIA_CONTENT_TYPE 変数を、同じ <media:content> タグの type 属性値に置き換えます。
モバイル デバイス上で動画を再生するには、yt:format 属性の値に基づいて、該当する <media:content> タグの値を選択します。MEDIA_CONTENT_URL 変数を、そのタグの url 属性値に置き換えます。同じく、MEDIA_CONTENT_URL 変数を、そのタグの url 属性値に置き換えます。
<object width="425" height="350"> <param name="movie" value="MEDIA_CONTENT_URL"></param> <embed src="MEDIA_CONTENT_URL" type="MEDIA_CONTENT_TYPE" width="425" height="350"> </embed> </object>
セクション 3 には、各種の操作ボタンと、動画についての統計情報があります:
操作ボタン
YouTube のウェブサイトの [共有] ボタンをクリックすると、ユーザーがコンタクトまたは他の任意の email アドレスに対してメッセージを送信できるインライン フォームが表示されます。この[共有] ボタンと同等の機能を実現するには、ログインしているユーザーのコンタクトを取得して表示し、ユーザーがメッセージを送信するコンタクトを選択できるフォームを提供する必要があります。ユーザーがメッセージを送信するとき、アプリケーションはメッセージ受信者 1 人につき 1 つの API リクエストを送信する必要があります。
[お気に入り] ボタンからは、ログインしているユーザーのお気に入り動画リストに動画を追加することができます。お気に入り動画の追加に関する詳細を参照する。
[再生リスト] ボタンをクリックすると、ログインしているユーザーの再生リストの一覧と、新しい再生リストを作成するオプションが表示されるプルダウン メニューがあるインライン フォームの表示/非表示が切り替えられます。ユーザーが既存の再生リストを選択すると、動画はその再生リストに追加されます。新しい再生リストへの追加を選択すると、ユーザーは、再生リストに追加するための別のフォームに誘導されます。新しい再生リストに関する情報を送信すると、再生リストに動画が追加されます。
この機能を実現するには、アプリケーションは別の API リクエストを送信してユーザーの再生リストのリストを取得する必要があります。ユーザーが既存の再生リストを選択すると、アプリケーションはその再生リストに動画を追加します。ユーザーが新しい再生リストの作成を選ぶと、アプリケーションは新しい再生リストの情報を収集し、再生リストを追加し、再生リストに動画を追加します。
[フラグ] ボタンをクリックするとインライン フォームが表示され、ユーザーが動画に関する苦情を追加することができます。YouTube サイトでは、そのフォームで表示されるセレクトメニューは、苦情を追加する API リクエストの <yt:description> タグの値を生成するために使われます。アプリケーションでは、類似のプルダウン メニューを表示してもよいし、ユーザーが苦情を入力できるテキスト ボックスを表示するのもよいでしょう。
統計
セクション 4 には、コメントのリストと動画レスポンスが表示されます (この例では、動画レスポンスがありません)。このセクションには次の要素が表示されます:
コメント リストの上部にある、動画レスポンスを投稿するためのリンクをクリックして表示されるフォームでは、動画レスポンスとして、以前にアップロードされた動画を選択するか、新しい動画をアップロードするかをユーザーが選択できます。
ユーザーが以前にアップロードされた動画を選択できるように、アプリケーションはそのユーザーがアップロードした動画のフィードを取得します。ユーザーが動画を選択した場合、アプリケーションではその動画を動画レスポンスとして追加するようにします。
ユーザーが新しい動画をアップロードすることを選択した場合、アプリケーションは、ブラウザベースのアップロードと、直接アップロードによって YouTube に新しい動画を追加する方法のどちらかをサポートする必要があります。ユーザーがそのいずれかを使って新しい動画をアップロードしたら、アプリケーションで新しい動画の ID を取得し、続いてその動画を動画レスポンスとして追加します。
コメント リストの上部にある 2 番目のリンクを使うと、ユーザーがテキスト コメントを投稿できます。このリンクは、ユーザーがコメントを入力できるインライン フォームの表示/非表示を切り替えます。この機能を提供するには、ユーザーがフォームを送信した後、コメントを追加する API リクエストをアプリケーションから送信する必要があります。
コメント リストを表示するには、その動画のコメント フィードを取得する追加の API リクエストをアプリケーションから送信する必要があります。
セクション 5 には、動画と、動画をアップロードした個人に関する補足情報が表示されます:
その個人がアップロードした動画の数など、動画の所有者に関する追加の情報を取得するには、所有者のプロフィールを取得する追加の API リクエストを送信する必要があります。プロフィール フィードには、ユーザーのお気に入りの動画、登録チャンネル、アップロードされた動画など、そのユーザーに関連する多くの <gd:feedLink> タグが含まれています。<gd:feedLink> タグの countHint 属性は、ユーザーのお気に入りの動画の数、登録チャンネルの数、およびアップロードされた動画の数を示します。
ユーザーは動画所有者の名前の横にある [チャンネル登録] ボタンをクリックして、動画所有者のチャンネルを登録することができます。チャンネルにはその動画所有者がアップロードしたすべての動画が含まれます。アプリケーションで [チャンネル登録] ボタンの機能を実現するには、ユーザーがボタンをクリックしたときに登録チャンネルを追加する API リクエストをアプリケーションから送信する必要があります。
ボックスの [About This Video] のパートには、動画に関する補足情報が含まれています。<media:description>、<media:keywords>、<yt:duration> などのタグの内容を使うと、動画に関する詳細情報を提供できます。
セクション 6 には、その動画所有者がアップロードした他の動画が表示されます。<a href="#User_Uploaded_Videos">特定のユーザーがアップロードした動画</a>の取得方法を参照してください。
セクション 7 には、YouTube がそのページの動画に類似していると判断した動画のリストが表示されます。関連動画フィードを使うと、API を使ってこのリストを取得することができます。
このセクションでは、標準 YouTube フィードを取得する方法を説明します。標準フィードには、評価の高い動画や人気の動画のフィードなど、YouTube ユーザーの行動を反映した動画のリストか、お勧め動画やモバイル動画のフィードなど、YouTube スタッフが選択した動画のリストが含まれています。これらのフィードの多くは、YouTube ウェブサイトの [動画] タブに表示されます。
標準フィードを取得するには、そのフィードに関連付けられた URL に HTTP GET リクエストを送信します。次の表に、各標準フィードに関連付けられた URL を示します:
| Name | フィード ID | 例 |
|---|---|---|
| 評価の高い動画 | top_rated | http://gdata.youtube.com/feeds/api/standardfeeds/top_rated |
| お気に入り登録の多い動画 | top_favorites | http://gdata.youtube.com/feeds/api/standardfeeds/top_favorites |
| 人気の動画 | most_viewed | http://gdata.youtube.com/feeds/api/standardfeeds/most_viewed |
| 新着動画 | most_recent | http://gdata.youtube.com/feeds/api/standardfeeds/most_recent |
| 話題の動画 | most_discussed | http://gdata.youtube.com/feeds/api/standardfeeds/most_discussed |
| リンク数の多い動画 | most_linked | http://gdata.youtube.com/feeds/api/standardfeeds/most_linked |
| コメントの多い動画 | most_responded | http://gdata.youtube.com/feeds/api/standardfeeds/most_responded |
| おすすめ | recently_featured | http://gdata.youtube.com/feeds/api/standardfeeds/recently_featured |
| 携帯電話向け動画 | watch_on_mobile | http://gdata.youtube.com/feeds/api/standardfeeds/watch_on_mobile |
また、これらのフィードの多くは time クエリ パラメータをサポートしています。それにより関連性の高い結果として取得するフィードに含まれる動画を、前日、前週、または前月に投稿されたものに制限することができます。たとえば、前日に投稿された評価の高い動画を取得するには、次の URL に HTTP GET リクエストを送信します:
http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today
注: time パラメータは、top_rated、top_favorites、most_viewed、most_discussed、most_linked、および most_responded の各標準フィードでサポートされています。
このセクションでは、特定のユーザーがアップロードしたすべての動画が含まれているフィードを取得する方法を説明します。
現在ログインしているユーザーがアップロードしたすべての動画のフィードをリクエストするには、次の URL に対して HTTP GET リクエストを送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別します。
http://gdata.youtube.com/feeds/api/users/default/uploads
別のユーザーがアップロードしたすべての動画のフィードをリクエストするには、次の URL に対して HTTP GET リクエストを送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username/uploads
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。次の例に示すように、API レスポンスの <name> タグからユーザー名を抽出することができます。
<author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author>
このクエリの API レスポンスのフォーマットは、このドキュメントの動画のフィードとエントリの説明セクションにあるサンプル レスポンスとまったく同じです。
このセクションでは、ある動画の関連動画のリストが含まれているフィードを取得する方法を説明します。YouTube では、関連動画のセットはアルゴリズムによって選択されます。
API レスポンスの各動画エントリには、一連の <link> タグが含まれます。rel 属性値が http://gdata.youtube.com/schemas/2007/#video.related の <link> タグは、その動画エントリに関連する他の動画を取得する URL を示します (<link> タグの href 属性が該当 URL を示します)。
<link rel="http://gdata.youtube.com/schemas/2007#video.related"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>
このクエリの API レスポンスのフォーマットは、このドキュメントの動画のフィードとエントリの説明セクションにあるサンプル レスポンスとまったく同じです。
このセクションでは、特定のカテゴリに属するすべての動画や、特定のキーワードに関連付けられたすべての動画のフィードを取得する方法を説明します (YouTube では、「タグ」という用語は動画に関連するキーワードを示します)。また、例では、あるカテゴリやキーワードに関連付けられた動画のほか、特定のカテゴリやキーワードに関連付けられていない動画を取得する方法も示されています。
API レスポンスの各動画エントリには、一連の <category> 要素が含まれます。各 <category> 要素は、対応する動画が関連付けられているカテゴリまたはキーワードを示しています。要素の scheme 属性は、その要素がカテゴリとキーワードのどちらなのかを示します。このセクションで説明しますが、要素の term 属性は、動画を検索するために使うカテゴリまたはキーワードの用語を示します。
特定のカテゴリに属するか、特定のキーワードに関連付けられているすべての動画のフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します:
http://gdata.youtube.com/feeds/api/videos/-/categories_or_keywords
上記の URL の categories_or_keywords は、動画を取得する特定のカテゴリまたはキーワードに置き換えてください。次の例は「Comedy」カテゴリの動画をリクエストするために使う URL を示しています:
http://gdata.youtube.com/feeds/api/videos/-/Comedy
リクエストでのカテゴリとキーワードには次の表記規則が適用されます:
リクエストでカテゴリと 1 つ以上のキーワードを指定した場合、またはリクエストでカテゴリを指定せず、複数のキーワードを指定した場合は、個別の各カテゴリとキーワード名をスラッシュで区切ります。たとえば、キーワード「bass」および「fishing」に関連する動画をリクエストするには次の URL を使います:
http://gdata.youtube.com/feeds/api/videos/-/bass/fishing
リクエストでは、ブーリアン演算子 NOT (-) および OR (|) を使って、複数のキーワードやカテゴリに関連付けられている動画を検索したり、除外したりすることができます。たとえば、「bass」および「music」に関連する動画を表示する場合、下に例を示すとおり、最も効果的な検索は、キーワード「bass」と関連付けられるが、キーワード「fish」または「fishing」と関連付けられない動画を検索することでしょう (「music」カテゴリに属し、キーワード「bass」に関連付けられた動画を検索する方法では、ベースの奏法に関するレッスン動画が除外される可能性があります)。
http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing
次の例は、「Sports」または「Howto」のカテゴリにある野球 (baseball) の動画を検索する方法を示しています。カテゴリ名は URL エンコードされたパイプ文字 (|) を表す値「%7C」で区切られ、動画が 2 つのいずれかのカテゴリに関連している必要があることを明示しています:
http://gdata.youtube.com/feeds/api/videos/-/Sports%7CHowto/baseball
カテゴリの名前は先頭を大文字にし、キーワードの名前は小文字で表記します。たとえば次のクエリは、キーワード「comedy」に関連付けられているが、「Comedy」カテゴリに属さない動画を指定しています:
http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy
API レスポンスの情報に基づいてカテゴリ検索やキーワード検索を自動生成する場合、カテゴリ名の一部としてスキーマを指定して、YouTube のカテゴリをキーワード タグやデベロッパー タグから明確に区別します。次の URL は、カテゴリ名にスキーマを指定する方法を示します:
http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fcategories.cat%7DNews http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fkeywords.cat%7Ddog http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7Dexample.com
前の項目で説明したように、特定のデベロッパー タグに関連付けられた動画をリクエストする場合は、常にスキーマを指定します。
このセクションでは、ユーザーが指定した検索用語に一致する動画のリストを、API を使って取得する方法を説明します。動画を検索するには次の URL に対して HTTP GET リクエストを送信します。このとき、リクエストの末尾に該当するクエリパラメータを付加します:
http://gdata.youtube.com/feeds/api/videos
次の例では、クエリ用語「football」と一致するがクエリ用語「soccer」と一致しない、最近アップロードされた 10 本の動画の 2 番目のセットが検索されます:
http://gdata.youtube.com/feeds/api/videos?
vq=football+-soccer
&orderby=published
&start-index=11
&max-results=10
検索リクエストには、次のパラメータを含めることができます。よく使われるパラメータから順に示します。
| Name | 説明 | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| vq | vq パラメータは、検索クエリ用語を指定します。YouTube は用語に一致するすべての動画の動画メタデータを検索します。動画メタデータには、タイトル、キーワード、説明、投稿者のユーザー名、カテゴリが含まれます。 パラメータ内のスペース、引用符、またはその他の記号は URL エスケープする必要があることに注意してください。 正確なフレーズを検索するには、フレーズを引用符で囲みます。たとえば、フレーズ「spy plane」に一致する動画を検索するには、vq パラメータを %22spy+plane%22 と設定します。 リクエストでは、ブーリアン演算子 NOT (-) および OR (|) を使って、複数の検索用語に関連付けられている動画を検索したり、除外したりすることもできます。たとえば、「boating」または「sailing」に一致する動画を検索するには、vq パラメータを boating%7Csailing と設定します (パイプ文字は URL エスケープする必要があります)。同様に、「boating」または「sailing」に一致するが、「fishing」には一致しない動画を検索するには、vq パラメータを "boating&7Csailing+-fishing" と設定します。 |
||||||||
| orderby | orderby パラメータは、検索結果セットの動画を並べ替えるために使う値を指定します。このパラメータの有効値は、relevance、published、viewCount、および rating です。また、パラメータ値を relevance_lang_languageCode に設定することで、特定の言語に最も関連性の高い結果をリクエストできます。ここで languageCode は ISO 639-1 の 2 文字言語コード です(簡体字中国語には zh-Hans、繁体字中国語には zh-Hant を使います)。また、検索クエリ用語への関連性が非常に高い場合、他の言語の結果であっても戻されることがあります。デフォルト値は relevance です。 | ||||||||
| start-index | start-index パラメータは、結果セットに含まれる最初の結果のインデックスを指定します。このパラメータでは 1 ベースのインデックスを使います。つまり最初の結果が 1、2 番目の結果が 2、以下同様となります。このパラメータは max-results パラメータと関連して機能し、戻す結果を決定します。たとえば、25 個の結果セットの 2 つめのセット (結果 26～50) をリクエストするには、start-index パラメータを 26 に、max-results パラメータを 25 に設定します。 | ||||||||
| max-results | max-results パラメータは、結果セットに含まれる結果の数の最大値を指定します。このパラメータは start-index パラメータと関連して機能し、戻す結果を決定します。たとえば、25 個の結果セットの 2 つめのセット (結果 26～50) をリクエストするには、max-results パラメータを 25 に、start-index パラメータを 26 に設定します。このパラメータのデフォルト値は 25、最大値は 50 です。 | ||||||||
| author | author パラメータは、検索範囲を特定の YouTube ユーザーがアップロードした動画に制限します。このパラメータについては、特定のユーザーがアップロードした動画セクションで詳しく説明します。 | ||||||||
| alt | alt パラメータは、戻されるフィードのフォーマットを指定します。このパラメータの有効値は atom、rss、json、json-in-script です。デフォルト値は atom で、この文書では、Atom レスポンスのフォーマットだけを説明します。JavaScript での API レスポンス使用の詳細は、Using JSON with Google Data APIs を参照してください。 | ||||||||
| format | format パラメータは、動画が特定の動画フォーマットで使える必要があることを示しています。リクエストでは、次のいずれかの形式を指定することができます:
| lr | lr パラメータは、検索範囲を、タイトル、説明、またはキーワードが特定の言語である動画に制限します。lr パラメータの有効値は ISO 639-1 の 2 文字の言語コードです。簡体字中国語には値 zh-Hans、繁体字中国語には値 zh-Hant を使えます。このパラメータは、標準フィード以外の任意の動画フィードをリクエストするときに使えます。 | ||||||
| racy | racy パラメータを使うと、検索結果セットに、標準コンテンツのほか、制限コンテンツも含むことができます。このパラメータの有効値は、include と exclude です。デフォルトでは、制限コンテンツは除外されます。制限コンテンツを含む動画のフィード エントリには、追加の <yt:racy> 要素が含まれます。 | ||||||||
| restriction | restriction パラメータは、特定の国でのみ再生できる動画を除外するのに使う IP アドレスを示します。デフォルトで、API は API リクエスト送信元の国で再生できない動画を除外します。この制限はクライアント アプリケーションの IP アドレスに基づきます。 特定のコンピュータから再生できる動画をリクエストするには、リクエストに restriction パラメータを含め、パラメータ値を、動画を再生できるコンピュータの IP アドレス (たとえば ) に設定します。 restriction=255.255.255.255特定の国で再生できる動画をリクエストするには、リクエストに restriction パラメータを含め、パラメータ値を、動画を再生する国の ISO 3166 2 文字国別コード (たとえば ) に設定します。 restriction=DE |
||||||||
| time | 標準フィード top_rated と most_viewed でだけ利用できる time パラメータは、指定した期間内にアップロードされた動画に検索範囲を制限します。このパラメータの有効値は、today (1 日)、this_week (7 日)、this_month (1 か月)、および all_time です。このパラメータのデフォルト値は all_time です。 |
検索クエリ パラメータは、他のタイプのフィード リクエストにも付加できることに注意してください。たとえば、特定のユーザーによってアップロードされ、同じく特定のキーワードに一致する動画を取得することができます。
YouTube Data API を使って YouTube に動画をアップロードする方法は 2 つあります。
直接アップロードでは、動画ライブラリにある動画を YouTube に追加できます。あなたのサイトを介してアップロードされる動画を、YouTube に送信するだけではなくそのサイトでもホストしたり格納したりしたい場合、直接アップロードを選択します。直接アップロードのシナリオでは、ユーザーがあなたのサイトを通して動画をアップロードするときに、動画はあなたのサーバーに送信されます。続いてあなたのアプリケーションが API リクエストを送信して、サーバーから YouTube に動画をアップロードします。
ブラウザベースのアップロードでは、実際の動画ファイルを処理したり、ホストしたり、プロキシとしてふるまったりせずに、ユーザーからの動画アップロードを受け入れることができます。動画ファイルをホストしたり格納したりしたくない場合は、ブラウザベースのアップロードを選択します。
アップロード方法のほかに、アプリケーションの適切な認証方式も選ぶ必要があります。以下の各セクションでは、動画アップロード処理について詳しく説明します:
このセクションでは、2 つの認証方式と、2 つのアップロード方法の処理フロー図を示します。アプリケーションにより異なりますが、認証方式とアップロード方法の組み合わせは自由です。
次の図は、AuthSub 認証方式を使うユーザー認証に含まれている手順の図解です。AuthSub 認証は、直接アップロードでも、ブラウザベースのアップロードでも使えます。
図は次の手順を示しています:
ユーザーが動画をアップロードするためにあなたのサイトにあるリンクをクリックします。
あなたのサイトは YouTube の認証プロキシ サービスにユーザーをリダイレクトします。
ユーザーのブラウザが認証サービスにリクエストを送信します。
YouTube は Access Consent ページを表示して、ユーザーに YouTube アカウントにログインするよう求めます。
ユーザーが自分のアカウントにログインすると、YouTube は、ユーザーの動画の詳細情報をあなたのサイトからアップロードすることを許可するか拒否するかユーザーに尋ねます。
ユーザーが許可すると、YouTube はユーザーをサイトにリダイレクトして戻します。リダイレクト URL には、Upload API リクエストの認証トークンが含まれています。
ユーザーのブラウザはあなたのサイトに、認証トークンを含むリクエストを送信します。Google AuthSub のドキュメントに、使い捨て認証トークンを、期限のないセッション トークンに交換するためのオプションの手順が説明されています。
次の図は、ClientLogin 認証方式を使うユーザー認証に含まれている手順の図解です。AuthSub 認証と同様、ClientLogin 認証は、直接アップロードでも、ブラウザベースのアップロードでも使えます。
図は次の手順を示しています:
ユーザーが動画をアップロードするためにあなたのサイトにあるリンクをクリックします。
アプリケーションは YouTube ユーザー名とパスワードを入力するフォームをユーザーに表示します。
ユーザーはインストールされているアプリケーションに自分の YouTube ユーザー名とパスワードを送信します。
アプリケーションは YouTube に ClientLogin 認証リクエストを送信して、動画をアップロードするための認証トークンを入手します。リクエストには、ユーザーの YouTube ユーザー アカウント (動画に関連付けられたアカウント) に対応するユーザー名とパスワードを指定します。
YouTube はユーザーのユーザー名とパスワードを検証し、認証トークンをアプリケーションに戻します。ブラウザベースのアップロードを使う場合、そのトークンを使って動画メタデータのアップロードができます。直接アップロードを使う場合、そのトークンを使ってメタデータと実際の動画ファイルのアップロードができます。
次の図は、ブラウザベースのアップロード処理の図解です。これらの手順が発生する前に、アプリケーションで認証プロセスが既に完了していることもあります。ただし、認証処理が完了する前にユーザーに動画メタデータを提供してもらう方法を選ぶこともできます。
図は次の手順を示しています:
あなたのサイトは、アップロードする動画の詳細情報をユーザーが入力するフォームを表示します。
ユーザーが、動画のタイトル、説明、カテゴリなど、動画の詳細情報を入力します。
あなたのサイトは、認証トークンと、ユーザーが前の手順で送信した動画の詳細を含む HTTP POST リクエストを YouTube に送信します。動画メタデータのアップロードセクションで、YouTube に動画の詳細を送信する方法を説明します。
YouTube は、アップロードされる動画の認証情報と動画詳細情報を暗号化された値として含むワンタイム アップロード トークンを戻します。API レスポンスのアップロード トークンと URL は、API レスポンスからの値の抽出セクションで示します。
あなたのサイトは、ユーザーが自分の動画ファイルを選択して YouTube にアップロードするためのフォームを表示します。フォームは YouTube に直接送信されるため、前の手順で入手したアップロード トークンを示す非表示の入力フィールド (hidden フィールド) を含んでいる必要があります。動画ファイルのアップロードセクションで、このフォームのガイドラインについて説明します。
ユーザーは自分の動画を選択してフォームを送信することで、動画とアップロード トークンを直接 YouTube に送信します。YouTube はトークンが有効であることを検証し、ユーザーの YouTube チャンネルに動画を追加します。この処理では、YouTube で動画を識別するために使われる一意の ID が動画に割り当てられます。
YouTube がユーザーをサイトにリダイレクトして戻します。
次の図は、直接アップロード処理の図解です。これらの手順が発生する前に、アプリケーションで認証プロセスが既に完了していることもあります。ただし、認証処理が完了する前にユーザーに動画メタデータを提供してもらう方法を選ぶこともできます。
図は次の手順を示しています:
あなたのサイトは、ユーザーがアップロードする動画の詳細情報を入力し、アップロードする動画ファイルを選択するフォームを表示します。
ユーザーが、動画ファイルを選択し、動画のタイトル、説明、カテゴリなど、動画の詳細情報を入力します。
あなたのサイトは、認証トークンと動画ファイル、およびユーザーが前の手順で送信した動画の詳細を含む HTTP POST リクエストを YouTube に送信します。動画メタデータのアップロードセクションで、YouTube に動画ファイルと動画の詳細を送信する方法を説明します。
YouTube は新しい動画を記述した API レスポンスを戻します。
あなたは、動画が正常にアップロードされたとことを確認するメッセージをユーザーに対して表示します。
あなたは YouTube に引き渡すすべての動画ファイルの著作権所有者またはその正式な代理人である必要があります。同様に、あなたのサイトから YouTube に動画をアップロードするユーザーは、アップロードするすべての動画の著作権所有者またはその正式な代理人である必要があります。できるだけ高品質の動画を提供することをお勧めします。YouTube の推奨動画仕様は YouTube のヘルプ センターでオンラインで参照できますので、ユーザーにもそれらのガイドラインを提供するようお勧めします。
これらのガイドラインのほか、動画ファイルは 100MB 以下である必要があり、YouTube ではアップロードされた動画の長さを制限しないことに注意してください。.zip フォーマットを使って動画ファイルを圧縮してもかまいません。ただし、100MB のサイズ制限は展開後の動画ファイルに適用されることに注意してください。
動画をアップロードするときに、動画に YouTube の動画カテゴリの 1 つを関連付けることができます。また、動画を識別するために、追加のキーワードやデベロッパー タグを動画に関連付けることができます。デベロッパー タグを使うと、あなたのウェブサイトからアップロードされたすべての動画、またはウェブサイトの特定の領域からアップロードされたすべての動画を識別することができます。YouTube は YouTube ユーザーに対してデベロッパー タグを表示しません。ただし、特定のデベロッパー タグに一致する動画を取得したり、更新したりすることはできます。
デベロッパー タグを動画に関連付けるには、Upload API リクエストに、デベロッパー タグ 1 つにつき 1 つの <media:category> タグを含めます。scheme 属性の値を http://gdata.youtube.com/schemas/2007/developertags.cat に、タグ値を動画に関連付けるキーワードに設定します。次の XML は、Upload API リクエストでサンプル デベロッパー タグを指定する例を示しています(文字列 TagName を、動画に関連付ける実際のキーワードまたはラベルに置き換えます)。
<media:category scheme="http://gdata.youtube.com/schemas/2007/developertags.cat">TagName</media:category>
API レスポンスでは、デベロッパー タグは <category> タグと <media:category> タグで指定されます。
注: 割り当てる各デベロッパー タグは、リクエスト内のデベロッパー キーに関連付けられます。そのデベロッパー タグと一致する動画を検索するには、アプリケーションが検索リクエストで同じデベロッパー キーを指定する必要があります。
特定のデベロッパー タグに関連付けられた動画を検索するには、developertags.cat カテゴリ スキームと、動画が一致するデベロッパー タグを指定する API 検索リクエストを送信します。下の URL は、あるデベロッパー タグに一致するように標準 API URL を変更する方法を示しています (URL 末尾の文字列 TagName を、デベロッパー タグの名前に置き換えます)。
Standard URL:
http://gdata.youtube.com/feeds/api/videos/
Retrieving videos associated with a developer tag:
http://gdata.youtube.com/feeds/api/videos/-/
%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7DTagName
注: デベロッパー タグに一致する動画を検索するには、リクエストで、そのデベロッパー タグを割り当てるために使ったのと同じデベロッパー キーを指定する必要があります。
次の例は、ブラウザベースのアップロードに AuthSub 認証方式を使う API リクエストのフォーマットを示しています:
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token=<authentication_token> X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Content-Length: <content_length> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request
HTTP POST リクエストでは、いくつかの値を提供する必要があります。上の例で太字で示したのがその値です。それらの値に関する説明を以下に示します:
authentication_token - この値はリクエストの認証トークンです。トークンは ClientLogin トークン、使い捨て AuthSub トークン、セッション AuthSub トークンのいずれかです。
client_id - (オプション) この値は API リクエストを行うアプリケーションを示します。この値はロギングとデバッグのために使われます。クライアント ID を入手するには http://code.google.com/apis/youtube/dashboard/ にアクセスしてください。
developer_key - この値は動画をアップロードするためにリクエストを送信している YouTube デベロッパーを示します。デベロッパー キーを入手するには http://code.google.com/apis/youtube/dashboard/ にアクセスしてください。
content_length - この値は、HTTP POST リクエストのボディ全体の長さをバイト単位で示します。
API_XML_Request - この値はアップロードされた動画ファイルに関する Atom XML エントリ形式の情報を含みます。次の例はサンプル XML リクエストを示しています。エントリで使われる XML タグはリファレンス ガイドで定義されます。
次の例は、これらの値をすべて含む HTTP POST リクエストを示しています。ただしバイナリ ファイル データだけは含まれません。
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token=DXAA...sdb8 X-GData-Client: b1c4t9sl2159 X-GData-Key: key=adf15ee97731bca89da876c...a8dc Content-Length: 1941255 Content-Type: application/atom+xml; charset=UTF-8 <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Bad Wedding Toast</media:title> <media:description type="plain">I gave a bad toast at my friend's wedding.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>toast, wedding</media:keywords> </media:group> </entry>
Upload API リクエストを送信する場合、API はアップロード URL とアップロード トークンを含む XML レスポンスを戻して、ユーザーが実際の動画ファイルをアップロードできるようにします。アプリケーションでは、レスポンスから URL とトークンを抽出し、ユーザーが動画ファイルを送信するウェブページ上のフォームにそれらの値を含める必要があります。
下の例は、ブラウザベースのアップロードをリクエストするためのサンプル API レスポンスを示しています:
次の XML は、サンプルのアップロード API レスポンスです。
<?xml version='1.0' encoding='UTF-8'?> <response> <url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD<url> <token>AEwbFAQEvf3xox...</token> </response>
API レスポンスからアップロード URL とアップロードのトークンを抽出したら、ユーザーが実際の動画ファイルをアップロードできるように、フォームを表示する必要があります。そのフォームはアップロード URL を <form> タグの action 属性の値として使用する必要があり、アップロード トークンを含む非表示の入力フィールドを含みます。
次の HTML は、実際に使われるのと同様のサンプル フォームを表示します:
<form action="URL?nexturl=http%3A%2F%2Fwww.example.com method="post" enctype="multipart/form-data"> <input type="file" name="file"/> <input type="hidden" name="token" value="TOKEN/> <input type="submit" value="go" /> </form>
フォームは次のガイドラインに従う必要があります:
フォームのターゲット URL に nexturl パラメータを追加する必要があります。このパラメータは、ユーザーが動画ファイルをアップロードするときに、YouTube がユーザーのブラウザをリダイレクトする URL を指定します。ブラウザで動画がアップロードされると、ユーザーは nexturl URL にリダイレクトされます。URL に付加される追加のパラメータの詳細は、リファレンス ガイドを参照してください。
<form> タグの enctype 属性を multipart/form-data に設定する必要があります。
ファイルを識別する <input> タグは file という名前である必要があります。
トークンを含む <input> タグは token という名前である必要があります。
動画をアップロードするには、http://uploads.gdata.youtube.com/feeds/api/users/<youtube_username>/uploads に、動画と、関連付けられているメタデータを含む HTTP POST リクエストを送信します。文字列 <youtube_username> はコンテンツ作成者の YouTube アカウントのユーザー名に置き換える必要があります。
Upload API リクエストは次のフォーマットに従う必要があります:
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token=<authentication_token> X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Slug: <video_filename> Content-Type: multipart/related; boundary=<boundary_string> Content-Length: <content_length> Connection: close --<boundary_string> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request --<boundary_string> Content-Type: <video_content_type> Content-Transfer-Encoding: binary <Binary File Data> --<boundary_string>--
ClientLogin 認証方式を使って動画をアップロードするリクエストは、上記の例と構文の上で 1 点異なります。ClientLogin 認証トークンの場合、Authorization ヘッダーはフォーマットが異なります。次の例は、ClientLogin 認証トークンの Authorization リクエスト ヘッダーを正しくフォーマットする方法を示しています:
Authorization: GoogleLogin auth=<authentication_token>
注: API を使って動画をアップロードするためのホスト名 uploads.gdata.youtube.com は、他のすべての API 関数で使われるホスト名と異なります。ただし、アップロードには、他の API 関数と同じ認証トークンを使うことができます。
HTTP POST リクエストでは、いくつかの値を提供する必要があります。上の例で太字で示したのがその値です。それらの値に関する説明を以下に示します:
youtube_username - この変数は、ClientLogin 認証を使うリクエストにのみ関連します。この値はユーザーの YouTube アカウントのユーザー名を含んでいます。アップロードされた動画はこのアカウントに関連付けられます。
authentication_token - この値はリクエストの認証トークンを含んでいます。トークンは ClientLogin トークン、使い捨て AuthSub トークン、セッション AuthSub トークンのいずれかです。
client_id - (オプション) この値は API リクエストを行うアプリケーションを示します。この値はロギングとデバッグのために使われます。クライアント ID を入手するには http://code.google.com/apis/youtube/dashboard/ にアクセスしてください。
developer_key - この値は動画をアップロードするためにリクエストを送信している YouTube デベロッパーを示します。デベロッパー キーを入手するには http://code.google.com/apis/youtube/dashboard/ にアクセスしてください。
video_filename - この値はコンテンツ作成者がアップロードする動画ファイルの名前です。
boundary_string - この値は非空白文字の文字列です。通常この文字列は、一連のハイフンに、ランダムな英数字の集合を続けたものです。注: この値は HTTP POST リクエストに複数回出現します。
content_length - この値は、HTTP POST リクエストのボディ全体の長さをバイト単位で示します。
API_XML_Request - この値はアップロードされた動画ファイルに関する Atom XML エントリ形式の情報を含みます。下で示す例でサンプルの XML リクエストを示しています。エントリで使われる XML タグはリファレンス ガイドで定義されます。
video_content_type - この値はアップロードされた動画ファイルの MIME タイプを含んでいます。MIME タイプは video/* (video/mpeg、video/mp4 など) または application/octet-stream である必要があります。
Binary File Data - この値は、アップロードされる動画ファイルのバイナリ コードを含んでいます。
次の例は、これらの値をすべて含む HTTP POST リクエストを示しています。ただしバイナリ ファイル データだけは含まれません。
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token=DXAA...sdb8 X-GData-Client: b1c4t9sl2159 X-GData-Key: key=adf15ee97731bca89da876c...a8dc Slug: video-test.mp4 Content-Type: multipart/related; boundary=--f93dcbA3 Content-Length: 1941255 Connection: close --f93dcbA3 Content-Type: application/atom+xml; charset=UTF-8 <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Bad Wedding Toast</media:title> <media:description type="plain">I gave a bad toast at my friend's wedding.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>toast, wedding</media:keywords> </media:group> </entry> --f93dcbA3 Content-Type: video/mp4 Content-Transfer-Encoding: binary <Binary File Data> --f93dcbA3--
Upload API リクエストを送信すると、API は、リクエストを生成したユーザーがアップロードしたすべての動画を列挙した XML レスポンスを戻します (ClientLogin 認証を使っている場合、レスポンスには、あなたのアカウントにアップロードされたすべての動画が含まれます)。レスポンスは Atom エントリで、ユーザーがアップロードしたすべての動画を取得するためのリクエストに対する YouTube Data API の標準レスポンスと同じフォーマットです。レスポンスには正しくエスケープされた HTML タグが含まれることに注意してください。
アップロードされた動画は、認証されたユーザーのアップロード済み動画フィードにただちに現れます。ただし、その動画を YouTube で再生できるようになるのは、処理とインデクシングが終わってからです。動画のアップロード日時と、動画が YouTube 上で公開される日時の間隔は一定ではありません。ただし通常、動画のインデクシングは 1 日以内で完了します。数時間または 1 時間以下で完了することもあります。
ユーザーのアップロード済み動画フィードを取得することによって、ユーザーの未公開動画のステータスを確認することができます。そのフィードの未公開エントリには <app:control> タグが含まれます。未公開の動画には、処理中の動画、アップロードに失敗した動画、アップロード後に拒否された動画が含まれることに注意してください。
次の XML コードは、<app:control> タグおよびそのサブタグ <app:draft> と <yt:state> がアップロード済み動画フィードにどのように出現するかを示しています。
<entry> <id>http://gdata.youtube.com/feeds/user/username/b5bbb2beb5a7d9ca</id> <app:control> <app:draft>yes</app:draft> <yt:state name='rejected' reasonCode='tooLong' helpUrl='http://www.youtube.com/t/community_guidelines'> Video is too long. </yt:state> </app:control> <yt:private/> </entry>
注: <yt:state> タグの値を確認して、未公開の動画がまだ処理中なのか、エラーによりアップロードが失敗したの