©2009 Google - Code サイト ホーム - 利用規約 - プライバシー ポリシー - サイト ディレクトリ
Google Code が利用できる言語: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
| 
日本語 | ログイン
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> タグの値を確認して、未公開の動画がまだ処理中なのか、エラーによりアップロードが失敗したのか、アップロードが拒否されたのかを動画所有者に問い合わせることをお勧めします。Java と PHP のデベロッパー ガイドには、これらのタグの値をチェックするサンプル コードが記載されています。
動画を更新するには、rel 属性値が edit である動画エントリの <link> タグで指定された URL に HTTP PUT リクエストを送信します:
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/apis/users/andyland74/uploads/914IMX9RSTE'>
PUT リクエストのボディは、動画情報を含んでいる Atom XML エントリです。次の要素とそのサブタグから、任意のものをリクエストに含めることができます。必須要素はアスタリスク (*) で示しています。
ある要素を取り除くと、その動画に関する、既に存在する情報が削除されることに注意してください。たとえば、ある動画が非公開とマークされていても、リクエストに <yt:private> タグを含めないとその動画は公開になります。
次の XML は、動画を更新するためのサンプル リクエストを示しています:
PUT /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?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">Yippee Skippy</media:title> <media:description type="plain">I am updating this video.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>blastoff,rodeo,whiteboards</media:keywords> </media:group> </entry>
動画を削除するには、次の例に示すように、その動画の edit URL に HTTP DELETE リクエストを送信します:
DELETE /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
ユーザーは動画に評価を追加することができます。YouTube では 1 ～ 5 の評価システムを使います。1 が最も低い評価です。ユーザーは評価の更新や削除はできません。通常、動画を鑑賞したユーザーがその動画を評価します。
API レスポンスの各エントリは、ユーザー評価に関係する情報を持つ次の 2 つのタグを含みます:
<gd:rating>、評価スケール、動画の評価の数、動画の評価の平均を示します。このタグは、動画が評価されたことがある場合にのみ返されます。下の XML の抜粋は、API レスポンスでこの URL がどのように出現するかを示しています:
<feed>
<entry>
...
<gd:rating min='1' max='5' numRaters='1914' average='4.24'/>
</entry>
</feed>
<link> タグは、動画に評価を追加するために API リクエストを投稿する URL を示しています。各エントリにはいくつかのリンク タグが含まれますから、rel 属性値が http://gdata.youtube.com/schemas/2007#video.ratings であるタグの URL を使う必要があります。下の XML の抜粋は、API レスポンスでこの URL がどのように出現するかを示しています:
<feed>
<entry>
<link rel='http://gdata.youtube.com/schemas/2007#video.responses'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/responses'/>
<link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
...
<media:group>
</entry>
</feed>
評価を追加するには、評価される動画と評価そのものを示す HTTP POST リクエストを送信します (評価を行うユーザーは認証トークンによって識別されます)。
次の XML は、動画に評価を追加する方法を示しています。<gd:rating> タグの value 属性は評価を示す 1 ～ 5 の整数である必要があることに注意してください。
POST /feeds/api/videos/VIDEO_ID/ratings Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005"> <gd:rating value="4" min="1" max="5"/> </entry>
YouTube でリクエストが正しく処理されると、API は 201 HTTP レスポンス コードを返します。
HTTP リクエストが <gd:rating> タグの value 属性に無効な値、min属性に 1 以外の値、または max 属性に 5 以外の値を指定すると、YouTube はエラーを戻します。
コメントは動画に対するテキスト コメントです。ログインしているユーザーは動画にコメントを追加することができますが、それらのコメントを変更または削除することはできません。また、コメントに HTML マークアップが含まれる場合、YouTube によってすべてプレーン テキストに変換されることに注意してください。通常、動画を鑑賞したユーザーがその動画にコメントを追加します。
各動画エントリは <gd:comments> タグを含んでいます。このタグには、動画のコメントのリストを取得またはそれに追加する API リクエストを送信する URL がカプセル化されています。下のサンプル XML は、API レスポンスでこの URL がどのように出現するかを示しています:
<feed>
<entry>
...
<media:group>
...
</media:group>
<gd:comments>
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
</gd:comments>
</entry>
</feed>
各コメントには、作成者、タイトル、内容があります。次の XML は、コメント フィードが含まれているサンプル 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/'> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?start-index=1&max-results=25</id> <updated>2008-02-25T23:14:03.148Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>Comments on 'My walk with Mr. Darcy'</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' 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://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?start-index=1&max-results=25'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?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>100</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2BAAD03653A691</id> <published>2007-05-23T00:21:59.000-07:00</published> <updated>2007-05-23T00:21:59.000-07:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>Walking is fun.</title> <content type='text'>Walking is fun.</content> <link rel='related' 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='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2BAAD03653A691'/> <author> <name>andyland744</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland744</uri> </author> </entry> <entry> ... </entry> ... </feed>
YouTube ユーザーは、コメントに対して別のコメントで応答することができます。別のコメントに応答して投稿されたコメントには、XML レスポンスで、次の <link> タグに示されているように、in-reply-to リンクが含まれます:
<link rel="http://gdata.youtube.com/schemas/2007#in-reply-to" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/2cdgTWitj_o/comments/978A9E10911314AC"/>
動画にコメントを追加するには、<gd:comments> タグ内部に出現する <gd:feedLink> タグで示された URL にHTTP POST リクエストを送信します。送信する実際のコメントは、POST リクエストのボディを構成する XML に、<content> タグの値として出現します。
次のサンプル XML API リクエストは、動画にコメントを追加する方法を示しています。
POST /feeds/api/videos/VIDEO_ID/comments HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <content>This is a crazy video.</content> </entry>
動画レスポンスとは、別の動画にリプライとして関連付けられる動画です。動画は、他の 1 つの動画に対してのみ、動画レスポンスとして指定することができます。ログインしているユーザーは動画レスポンスを追加/削除することができますが、動画レスポンスとして追加/削除しようとしている動画はあらかじめアップロード済みである必要があります。
このセクションでは、動画に対する動画レスポンスのフィードを取得する方法を説明します。動画レスポンスを持たない動画もあることに注意してください。
API レスポンスの各動画エントリには、一連の <link> タグが含まれます。rel 属性値が http://gdata.youtube.com/schemas/2007/#video.responses の <link> タグは、その動画エントリに対する動画レスポンスを取得する URL を示しています。(<link> タグの href 属性が該当 URL を示します)。
<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"/>
このクエリの API レスポンスのフォーマットは、このドキュメントの動画のフィードとエントリの説明セクションにあるサンプル レスポンスとまったく同じです。
動画レスポンスを追加するには、動画レスポンスが追加される動画と動画レスポンスとして追加する動画の 2 つの動画を識別する HTTP POST リクエストを送信します。
次の XML は、動画レスポンスを追加するサンプル リクエストのフォーマットの例です。リクエストで、文字列 ORIGINAL_VIDEO_ID は動画レスポンスが追加される動画、文字列 RESPONSE_VIDEO_ID は動画レスポンスとして追加する動画を示します。
POST /feeds/api/videos/ORIGINAL_VIDEO_ID/responses HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www/w3.org/2005/Atom"> <id>RESPONSE_VIDEO_ID</id> </entry>
YouTube でリクエストが正しく処理されると、API は 201 HTTP レスポンス コードを返します。ただし、元の動画の所有者によってレスポンスが承認されるまで、動画レスポンスは動画レスポンス フィードにリストされません。
通常、その動画を鑑賞したユーザーが動画に動画レスポンスを追加します。ユーザーがあらかじめアップロードしておいた動画を、レスポンスとして選択する場合もあります。動画レスポンスとなる新しい動画をユーザーがアップロードする場合もあります。次のリストは、各タイプの API リクエストに関連付けられた API コールを示しています:
ユーザーが、動画レスポンスとして既存の動画を選択する場合
その動画自身の URL に対して API リクエストを送信し、動画の情報を取得します。
ユーザーはリンクをクリックし、以前アップロードした動画を動画レスポンスとして追加します。ユーザーがレスポンスを追加する動画に対する動画レスポンスの URL を抽出します。
ユーザーがアップロードした動画のリストを取得する API リクエストを送信します。動画のリストが表示され、ユーザーが動画を選択します。
ユーザーが動画を選択したら、元の動画に対して、動画レスポンス URL を要求する HTTP POST リクエストを送信します。これにより、選択した動画の <id> が指定されます。フィード エントリ用の動画レスポンスを確認する方法については、動画レスポンスのリストの取得セクションをご覧ください。
ユーザーが、動画レスポンスとして新しい動画をアップロードする場合
このユース ケースも、動画の情報を取得する API リクエストから始まります。
ユーザーはリンクをクリックし、新しい動画をアップロード (またはキャプチャ) して、動画レスポンスを追加します。ユーザーがレスポンスを追加する動画に対する動画レスポンスの URL を抽出します。
YouTube の動画ライブラリに新しい動画をアップロードする API リクエストを送信します。ユーザーが動画のキャプチャを行う場合は、ユーザーが動画のタイトルやその他の情報を入力するフォームを表示する必要があります。
新しく追加された動画の動画 ID を、アップロード リクエストに対する API レスポンスから抽出します。
元の動画に対して、動画レスポンス URL を要求する HTTP POST リクエストを送信します。これにより、新しく追加された動画が動画レスポンスとして追加されます。
動画レスポンスを削除するには、2 つの動画を識別する HTTP DELETE リクエストを送信します。以下に例を示します。
DELETE /feeds/api/videos/VIDEO_ID/responses/VIDEO_RESPONSE_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
ユーザーは動画を報告し、不適切なコンテンツを含む動画としてフラグを追加することができます。報告を行うことはできますが、その内容を変更したり削除したりすることはできません。通常、ユーザーは動画を閲覧した後に報告を行います。
API レスポンスでは、各エントリに <link> タグが含まれています。このタグは、動画を報告する API リクエストを送信する URL を識別します。各エントリには複数のリンク タグが含まれるため、rel 属性の値が http://gdata.youtube.com/schemas/2007#video.complaints であるタグの URL を使用する必要があります。
動画を報告するには、報告する動画、報告者、報告に含まれるテキストを識別する HTTP POST リクエストを送信します。(ユーザーは HTTP リクエスト ヘッダーの認証トークンにより識別されます。)このリクエストでは、値が http://gdata.youtube.com/schemas/2007/complaint-reasons.cat の scheme 属性を含む <category> タグを使用して、報告の理由を指定することもできます。このタグの term 属性値は、次のいずれかである必要があります。
次の XML は、動画を報告する方法を示しています。
POST /feeds/api/videos/VIDEO_ID/complaints HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <yt:content type="text"> Please ignore this complaint. I'm testing a YouTube API and needed to issue a complaint to test the add complaint function. Per the value of the category tag, pretend I am complaining about a video that contains violent or repulsive acts. </yt:content> <category scheme="http://gdata.youtube.com/schemas/2007/complaint-reasons.cat" term="VIOLENCE"/> </entry>
YouTube でリクエストが正しく処理されると、API は 201 HTTP レスポンス コードを返します。
このセクションでは、ユーザーが YouTube のコンタクト リストに登録されているユーザーに動画を送信できるようにする方法を説明します。(このドキュメントの動画情報の表示セクションでは、ユーザーが YouTube ウェブサイトでこの機能にアクセスする方法を紹介しています。)
ユーザーが YouTube 上で他のユーザーに動画を送信するには、次の URL に HTTP POST リクエストを送信します。この URL の「CONTACT_ID」を動画を送信する相手の YouTube ユーザー名に置き換えてください。
http://gdata.youtube.com/feeds/users/CONTACT_ID/inbox
POST リクエストでは、<id> タグが動画の送信先を認識し、<yt:description> タグに動画と一緒に送信されるメッセージの内容が含まれます。次に、他のユーザーに動画を送信するリクエストの例を示します。
POST /feeds/api/users/CONTACT_ID/inbox HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
注意: ユーザーが動画を送信できるのは、コンタクト リストに登録されているユーザーのみです。
次に、動画を共有するユース ケースの例を示します。
このユース ケースは、動画の情報を取得する API リクエストから始まります。
動画の閲覧後、ユーザーはコンタクトに動画を送信するリンクをクリックします。
アプリケーションが、現在承認されているユーザーに対し、コンタクト リストを取得するリクエストを送信します。
アプリケーションからユーザーに対し、動画の送信先としてコンタクトを指定するフォームが表示されます。このフォームでは、ユーザーはコンタクト宛てのメッセージを入力することもできます。
ユーザーがフォームを送信したら、選択されたコンタクトごとに HTTP PUT リクエストを送信します。
お気に入りの動画とは、ユーザーがお気に入りに追加した動画のことです。ユーザーは自分のアカウント ページでお気に入りの動画のリストを表示したり、編集したりすることができます。また、ユーザーのお気に入りの動画は他の YouTube ユーザーにも公開されます。
ユーザーは、YouTube Data API を使ってお気に入りの動画を追加したり削除したりできます。お気に入りの動画を追加または削除するには、認証されたユーザーの YouTube ユーザー名と、追加または削除する動画の YouTube ID を提供する必要があります。
このセクションでは、特定のユーザーのお気に入りの動画を示すフィードを取得する方法について説明します。ユーザーによっては、お気に入りの動画を追加していないこともあります。
現在ログインしているユーザーのお気に入りの動画のフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別します。
http://gdata.youtube.com/feeds/api/users/default/favorites
別のユーザーのお気に入りの動画のフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username/favorites
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。
このクエリの API レスポンスには、このドキュメントの動画のフィードとエントリの説明セクションにあるサンプル レスポンスと同一のフォーマットが使用されています。
次のリクエストでは、URL を提供し、ログインしているユーザーのお気に入りの動画のリストに動画を追加するための XML フォーマットを説明しています。
POST /feeds/api/users/default/favorites HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom"> <id>VIDEO_ID</id> </entry>
次に、お気に入りの動画を追加する一般的なユース ケースを 2 つ示し、それぞれのユース ケースに関連する API コールについて説明します。
ユーザーが動画を閲覧し、お気に入りに追加します。
このユース ケースは、特定の動画の情報を取得する API リクエストから始まります。
動画の閲覧後、ユーザーが動画をお気に入りに追加します。
アプリケーションから http://gdata.youtube.com/feeds/api/users/default/favorites に API POST リクエストが送信され、ユーザーのお気に入りのリストに動画が追加されます。
ユーザーは動画の一覧を確認し、お気に入りに追加します。
このユース ケースは、動画を検索する、または特定の動画のフィードを取得するリクエストから始まります。
ユーザーが、たとえば各動画の横のチェックボックスをオンにして、リストから 1 つまたは複数の動画を選択します。
アプリケーションは選択された動画をループし、API リクエストを送信してそれぞれの動画をお気に入りに追加します。アプリケーションは、各リクエストを http://gdata.youtube.com/feeds/api/users/default/favorites に送信します。各リクエストの <id> タグは、対応する動画に対し、前の操作で取得した動画フィード内の <id> タグの値を指定します。
お気に入りの動画を削除するには、動画エントリの edit URL に対し、HTTP DELETE リクエストを送信します。
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/favorites/VIDEO_ID'>
次のサンプル API リクエストで、お気に入りの動画を削除する方法を示します。
DELETE /feeds/api/users/USER_ID/favorites/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
次に、お気に入りの動画を削除する一般的なユース ケースを示し、それぞれのユース ケースに関連する API コールについて説明します。
このユース ケースは、ユーザーのお気に入りの動画のフィードを取得するリクエストから始まります。
ユーザーが、たとえば各動画の横のチェックボックスをオンにして、リストから 1 つまたは複数の動画を選択します。
アプリケーションは選択された動画をループして HTTP DELETE リクエストを送信し、ユーザーのお気に入りのリストからそれぞれを削除します。アプリケーションから、対応するお気に入りの動画に対するそれぞれの API リクエストを edit URL に送信します。
再生リストとは、ユーザーが保存してまとめて閲覧したり、他のユーザーと共有したりできる動画のコレクションのことです。ユーザーは自分のアカウント ページで再生リストを表示したり、編集したりすることができます。また、ユーザーの再生リストは他の YouTube ユーザーにも公開されます。
ユーザーは、YouTube Data API を使って再生リストの取得、作成、編集、削除を行うことができます。
このセクションでは、特定のユーザーの再生リストを示すフィードを取得する方法について説明します。ユーザーによっては、再生リストをまったく作成していない場合もあります。
現在ログインしているユーザーの再生リストのフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別します。
http://gdata.youtube.com/feeds/api/users/default/playlists
別のユーザーの再生リストのフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username/playlists
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。
次の XML は、再生リストのフィードを含む API レスポンスの例を示したものです。レスポンスには複数の <entry> タグが含まれ、その各エントリに再生リストが記述されます。各エントリには、再生リストのタイトル、説明、作成者、変更日、および再生リストにある動画の一覧を取得する URL を指定する <gd:feedLink> タグが含まれています。
<?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: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/users/andyland74/playlists?start-index=1&max-results=25</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>andyland74's Playlists</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_play_list?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?start-index=1&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>My New Playlist Title</title> <content type='text'>My new playlist Description</content> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:description>My new playlist Description</yt:description> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/> </entry> </feed>
前のセクションで述べたとおり、再生リスト フィードの各エントリには、再生リストに含まれる動画のリストを取得するための URL を特定する <gd:feedLink> タグが含まれます。次の例は、再生リスト取得のための URL が、再生リスト フィードのエントリに表示されているところを示しています。
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/>
再生リスト フィードの API レスポンスは、通常の動画フィードまたは検索結果セットとほぼ同じです。ただし、再生リストの所有者は再生リスト内の各動画のタイトルと説明を独自に定義することができるので、フィード エントリはこれらのカスタマイズ値を含む必要があります。再生リスト フィードにおける動画のエントリは、通常の動画エントリと次の点で異なります。
ユーザ定義の動画タイトルが <atom:title> タグ、オリジナルの動画タイトルが <media:title> タグに表示されます。
再生リスト所有者が動画の説明をカスタマイズしている場合、その説明が <yt:description> タグに表示されます。<yt:description> タグは、<entry> タグのサブタグです。
再生リストの各エントリには <yt:position> タグが含まれます。このタグは、再生リスト内での表示順に基づく動画の位置を示します。<yt:position> タグは、<entry> タグのサブタグです。
再生リストを作成するには、再生リストのタイトルと説明を指定する必要があります。<yt:private> タグ (オプション) は、再生リストを公開するかどうかを示します。デフォルトでは、再生リストは他のユーザーに公開されます。
次のリクエストは、新規再生リスト作成のための URL と XML 形式を示しています。
POST /feeds/api/users/default/playlists HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> </entry>
次に、2 つの一般的な再生リスト作成のユース ケースを示し、それぞれのユース ケースに関連する API コールについて説明します。
ユーザーが動画を見て、その動画を含む新しい再生リストを作成します。
このユース ケースは、特定の動画の情報を取得する API リクエストから始まります。
動画を見終わったユーザーは、リンクをクリックして動画を新しい再生リストに追加します。アプリケーションによって、ユーザーが再生リストのタイトルと説明を入力するためのフォームが表示されます。
アプリケーションが http://gdata.youtube.com/feeds/api/users/default/playlists に HTTP POST リクエストを送信し、再生リストを作成します。この API リクエストには、ユーザーが入力した再生リストのタイトルと説明が指定されています。
アプリケーションが追加の API リクエストを送信し、選択した動画を再生リストに追加します。
ユーザーが動画のリストを見て、1 つまたは複数の動画を選択し、新しい再生リストに追加します。
このユース ケースは、動画を検索する、または特定の動画のフィードを取得する API リクエストから始まります。
ユーザーが、たとえば各動画の横のチェックボックスをオンにして、リストから 1 つまたは複数の動画を選択し、新しい再生リストに追加します。
アプリケーションによって、ユーザーが再生リストのタイトルと説明を入力するためのフォームが表示されます。
アプリケーションが http://gdata.youtube.com/feeds/api/users/default/playlists に HTTP POST リクエストを送信し、ユーザーが入力したタイトルと説明を含む再生リストを作成します。
アプリケーションは選択した動画をループして、追加の API リクエストを送信し、選択したそれぞれの動画を再生リストに追加します。
再生リストの更新を行う API リクエストによって、ユーザーは再生リストのタイトル、説明、公開/非公開のステータスを更新できます。この API は、再生リストへの動画の追加、再生リスト内の動画の更新、再生リストからの動画の削除を行うためのリクエストを定義しています。
次のサンプル リクエストは、再生リスト更新の URL と XML 形式を示すものです。このリクエストで送信される XML は、再生リスト作成のリクエストと同じ形式です。ただし、このリクエストは HTTP PUT リクエストであり、API URL によって、更新する再生リストの ID を指定する必要があります。
PUT /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> </entry>
次のユース ケースは、ユーザーが再生リストを変更する場合のシナリオです。
このユース ケースは、ユーザーの再生リストのフィードを取得するリクエストから始まります。
ユーザーはリストから再生リストを選択してリンクをクリックし、再生リストを更新します。
アプリケーションによって、ユーザーが再生リストのタイトルと説明を更新するためのフォームが表示されます。
次に、アプリケーションは 再生リストの edit URL に HTTP PUT リクエストを送信して、再生リストを更新します。
動画を再生リストに追加するには、動画と再生リストのユニーク ID (YouTube によって割り当てられた ID) を指定する API リクエストを送信します。ユーザーは、動画に対し独自のタイトルと説明を指定することもできます。また、<yt:position> タグ (オプション) によって再生リスト内での動画エントリの順番を指定できます。デフォルトでは、新しく作成されたエントリは再生リストの末尾に追加されます。
次のリクエストは、再生リストへの動画の追加の URL と XML 形式を示すものです。
POST /feeds/api/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <id>PLAYLIST_ENTRY_ID</id> <title type="text">Optional custom video title</title> <yt:description>Optional custom video description</yt:description> <yt:position>4</yt:position> </entry>
次に、再生リストに動画を追加する一般的なユース ケースを 2 つ示し、それぞれのユース ケースに関連する API コールについて説明します。
ユーザーが動画を見て、その動画を再生リストに追加します。
このユース ケースは、特定の動画の情報を取得する API リクエストから始まります。
動画を見終わったユーザーは、リンクをクリックして動画を再生リストに追加します。
アプリケーションは、ユーザーの再生リストのリストを取得する API リクエストを送信します。API レスポンスの各エントリの <gd:feedLink> タグに、対応する再生リストに動画を追加するために使用する URL が示されます。
ユーザーが既存の再生リストを選択すると、アプリケーションは選択した動画をその再生リストに追加する API リクエストを送信します。
ユーザーが動画のリストを見て、1 つまたは複数の動画を選択し、再生リストに追加します。
このユース ケースは、動画を検索する、または特定の動画のフィードを取得する API リクエストから始まります。
ユーザーが、たとえば各動画の横のチェックボックスをオンにして、リストから 1 つまたは複数の動画を選択し、再生リストに追加します。
アプリケーションは、ユーザーの再生リストのリストを取得する API リクエストを送信します。API レスポンスでは、<gd:feedLink> タグにより、各再生リストにエントリを追加するために使用する URL が示されます。
ユーザーが再生リストを選択すると、アプリケーションは選択された動画をループして、それぞれの動画を再生リストに追加する API リクエストを送信します。各 API リクエストでは、追加する動画の <id> が XML で指定されます。
ユーザーは、再生リストのエントリを更新するときに、再生リスト エントリに関連付けられているタイトルと説明を独自のものに変更することができます。ユーザーは、再生リストに表示されるエントリの順番を変更することもできます。
次のサンプル リクエストは、再生リスト エントリ更新の XML 形式を示しています。リクエストで送信される XML は、再生リスト エントリ作成のリクエストと同じ形式です。ただし、このリクエストは HTTP PUT リクエストであり、API URL では更新する再生リストの ID を指定します。
PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> <yt:position>2</yt:position> </entry>
次のユース ケースは、ユーザーが再生リスト エントリを変更する場合のシナリオです。
このユース ケースは特定の再生リストを取得するリクエストから始まります。再生リスト内の動画のリストを取得するとき、それぞれの <entry> タグは再生リスト内の各動画に関する情報を含んでいます。再生リストのエントリを更新または削除するために必要な URL は、<entry> タグ内の <gd:feedLink> タグで示されます。
アプリケーションは再生リストのエントリを一覧表示します。また、再生リスト内のエントリの順番 (YouTube での動画の再生順) を変更するオプションをユーザーに提示します。
ユーザーが再生リストのエントリを並べ替え、リンクをクリックして再生リストを更新します。
アプリケーションは再生リスト内のエントリをループして、、各エントリの <yt:position> タグの値を更新します。アプリケーションは、更新するエントリごとに 1 つの API リクエストを送信する必要があります。各 API リクエストは、再生リスト エントリの edit URL に送信される必要があります。
次のサンプル API リクエストは、再生リスト エントリの削除方法を示すものです。再生リスト内の動画のリストを取得するとき、各 <entry> タグに再生リスト内の各動画に関する情報が含まれます。再生リストのエントリを更新または削除するために必要な URL は、<entry> タグ内の <gd:feedLink> タグで示されます。
DELETE /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
次に、再生リスト エントリを削除する一般的なユース ケースを示します。
このユース ケースは特定の再生リストを取得するリクエストから始まります。
アプリケーションが、再生リストのエントリを一覧表示します。各エントリの横にはチェックボックスが表示され、ユーザーが削除するエントリを選択できるようになっています。
アプリケーションは選択されたエントリをループして、再生リストから削除する各エントリに対する HTTP DELETE リクエストを送信します。アプリケーションは、削除される再生リスト エントリに対するそれぞれの API リクエストを、edit URL に送信します。
再生リストを削除すると、再生リスト全体が削除されます。次のサンプル API リクエストは、再生リストの削除方法を表しています。
DELETE /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
次に、再生リストを削除するための一般的なユース ケースを示します。
このユース ケースは、ユーザーの再生リストのフィードを取得するリクエストから始まります。
ユーザーがリストから再生リストを選択して削除すると、再生リスト削除の API リクエストが送信されます。
チャンネル登録とは、新しい動画がアップロードされたときにユーザーに通知するエンティティ表します。ユーザーは他のユーザのチャンネル、他のユーザーのお気に入りリスト、またはキーワード タグにチャンネル登録することができます。ユーザーは自分のアカウント ページでチャンネル登録のリストを表示したり、編集したりすることができます。また、ユーザーのチャンネル登録は他の YouTube ユーザーにも公開されます。
ユーザーは、YouTube Data API によってチャンネル登録を作成したり、削除したりすることができます。
このセクションでは、特定のユーザーのチャンネル登録を示すフィードを取得する方法について説明します。ユーザーによっては、チャンネル登録をまったく作成していない場合もあります。
現在ログインしているユーザーのチャンネル登録のフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別できます。
http://gdata.youtube.com/feeds/api/users/default/subscriptions
別のユーザーのチャンネル登録のフィードをリクエストするには、HTTP GET リクエストを次の URL に送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username/subscriptions
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。
次の XML は、チャンネル登録フィードを含む API レスポンスの例を示したものです。レスポンスには複数の <entry> タグが含まれ、その各エントリにチャンネル登録が記述されます。ユーザーは、YouTube チャンネル、他のユーザーのお気に入りの動画、キーワード タグにチャンネル登録できます。チャンネル登録フィードの各エントリには <category> タグが含まれます。これに対する scheme 属性の値は、http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat です。この <category> タグに対する term 属性の値によって、チャンネル、お気に入りリスト、キーワード タグのいずれに対するチャンネル登録であるかが示されます。
フィード エントリが YouTube チャンネルに対するチャンネル登録を表している場合、<category> タグの term 属性は channel の値を持ちます。エントリには <yt:username> 要素も含まれます。これはチャンネルの所有者を指定するものです。
フィード エントリが、別のユーザーのお気に入りの動画へのチャンネル登録について表している場合、<category> タグの term 属性はfavorites の値を持ちます。エントリには <yt:username> 要素も含まれます。これは、チャンネル登録されるお気に入りの動画の所有者であるユーザーを指定するものです。
フィード エントリがあるキーワードへのチャンネル登録を表している場合、<category> タグの term 属性は query の値を持ちます。 エントリには <yt:queryString> 要素も含まれます。これは、登録されるキーワードを指定するものです。
次の XML は、チャンネル登録フィードを含む API レスポンスの例を示したものです。レスポンスには、3 つの <entry> タグが含まれます。このタグはそれぞれチャンネル、キーワード、お気に入り動画へのチャンネル登録の例を示しています。各エントリの <gd:feedLink> タグは、そのチャンネル登録に含まれる動画を取得する URL を示します。2 番目、3 番目のエントリには、最初のエントリにある同じタグとは異なる値を含むタグのみが表示されます。
<?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: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/users/andyland74/subscriptions?start-index=1&max-results=25</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#subscription'/> <title type='text'>andyland74's Subscriptions</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_subscriptions?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?start-index=1&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#subscription'/> <title type='text'>Videos published by : NBC</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_videos?user=NBC'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>NBC</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/nbc/uploads'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='query'/> <title type='text'>Videos matching : surfing</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/results?search_query=surfing'/> ... <yt:queryString>surfing</yt:queryString> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#video.query' href='http://gdata.youtube.com/feeds/api/videos?vq=surfing'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='favorites'/> <title type='text'>Favorites of : kemlye</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_favorites?user=kemlye'/> ... <yt:username>kemlye</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/kemlye/favorites'/> </entry> </feed>
チャンネル登録を作成するには、登録を作成している認証済みユーザーの YouTube ユーザー名を指定する必要があります。また、<category> タグを使用して、そのユーザーがチャンネル、お気に入りリスト、キーワードのどれにチャンネル登録するのかを示す必要があります。認証されたユーザーがチャンネルまたはお気に入りリストにチャンネル登録する場合は、登録対象のチャンネルまたはお気に入りリストに関連付けられるユーザー名を <yt:username> タグで指定します。認証されたユーザーがキーワード検索にチャンネル登録している場合は、新規チャンネル登録に関連付けるキーワードを <yt:queryString> タグで指定します。
次のリクエストは、チャンネル登録作成の XML 形式を示すものです。
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="channel"/> <yt:username>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="favorites"/> <yt:username>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="query"/> <yt:queryString>Dog Skateboarding</yt:queryString> </entry>
次に、一般的なチャンネル登録作成のユース ケースを示し、それぞれのユース ケースに関連する API コールについて説明します。
ユーザーが動画を見て、動画の所有者のチャンネルにチャンネル登録します。
このユース ケースは、特定の動画の情報を取得する API リクエストから始まります。
動画を見た後、ユーザーはリンクをクリックして動画所有者のチャンネルにチャンネル登録します。
アプリケーションが http://gdata.youtube.com/feeds/api/users/default/subscriptions に API リクエストを送信してチャンネル登録を作成します。リクエストに含まれる XML エントリの <yt:username> タグの値は動画所有者の YouTube ユーザー名を示し、<category> タグの term 属性には channel の値を指定します。
ユーザーが動画を見て、その動画に関連するキーワードに一致するすべての動画にチャンネル登録します。
このユース ケースは、動画を検索する、または特定の動画のフィードを取得する API リクエストから始まります。
ユーザーがステップ 1 で取得した結果の中から動画をクリックすると、その動画の情報を取得する API リクエストが送信されます。このステップで、ユーザーは選択した動画を見るページに移動します。
ユーザーが動画を見るページには、動画に関連するキーワードのリストが表示され、ユーザーは個々のキーワードにチャンネル登録することができます。ユーザーがリンクをクリックして、あるキーワードに対してチャンネル登録します。
アプリケーションが http://gdata.youtube.com/feeds/api/users/default/subscriptions に API リクエストを送信してチャンネル登録を作成します。リクエストに含まれる XML エントリの <yt:queryString> タグは、登録対象のキーワードを値に持ちます。<category> タグの term 属性の値は query です。
次のサンプル API リクエストは、チャンネル登録の削除方法を示すものです。
DELETE /feeds/api/users/USER_ID/subscriptions/SUBSCRIPTION_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
次に、チャンネル登録を削除するための一般的なユース ケースを示します。
ユーザーがチャンネル登録のリストを見て、そこから 1 つまたは複数を削除します。
このユース ケースは、ユーザーのチャンネル登録のフィードを取得するリクエストから始まります。
アプリケーションがユーザーのチャンネル登録リストを表示し、ユーザーは 1 つまたは複数のチャンネル登録を選択して削除します。
アプリケーションは選択したチャンネル登録のの中をループして HTTP DELETE リクエストを送信し、ユーザーのチャンネル登録リストからそれぞれを削除します。それぞれの API リクエストは、チャンネル登録の edit URL に送信されます。
ユーザー プロフィールには、ユーザーの趣味、職業、好きな本、音楽、映画などの情報が含まれます。ユーザー プロフィール フィードに表示されるすべての個人情報は、YouTube ウェブサイトでユーザー自身が入力して公開したものです。YouTube Data API によって、ユーザー プロフィールを取得することができます。
このセクションでは、特定のユーザーのプロフィールに関する情報を含むエントリを取得する方法について説明します。
現在ログインしているユーザーのプロフィールをリクエストするには、HTTP GET リクエストを次の URL に送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別します。
http://gdata.youtube.com/feeds/api/users/default
別のユーザーのプロフィールをリクエストするには、HTTP GET リクエストを次の URL に送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。
ユーザー プロフィールのリクエストに対する API レスポンスに含まれる <entry> タグは、1 つだけです。プロフィール エントリに含まれる情報は、次の通りです。
yt 名前空間のタグは、ユーザーの年齢、好きな本、職業、学校など、ユーザーが YouTube プロフィールに入力した個人情報を示します。
<media:thumbnail> タグはユーザーがプロフィールにアップロードした写真を含みます。また、写真がない場合はデフォルトのイメージを含みます。
<yt:statistics> タグはユーザーに関する統計情報を含みます。たとえば、ユーザーのプロフィールを見た人の数、ユーザーが見た動画の数、ユーザーがアップロードした動画をチャンネル登録した人の数などです。
一連の <gd:feedLink> タグは、ユーザーのアップロードした動画、お気に入りの動画、再生リスト、登録チャンネル、コンタクトを取得する URL を示します。
次の XML は、ユーザー プロフィールを含む API レスポンスの例を示したものです。
<?xml version='1.0' encoding='UTF-8'?> <entry xmlns='http://www.w3.org/2005/Atom' 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/users/andyland74</id> <published>2006-10-16T00:09:45.000-07:00</published> <updated>2008-02-26T11:48:21.000-08:00</updated> <category scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat' term='Standard'/> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#userProfile'/> <title type='text'>andyland74 Channel</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=andyland74'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:age>33</yt:age> <yt:username>andyland74</yt:username> <yt:books>Catch-22</yt:books> <yt:gender>m</yt:gender> <yt:company>Google</yt:company> <yt:hobbies>Testing YouTube APIs</yt:hobbies> <yt:location>US</yt:location> <yt:movies>Aqua Teen Hungerforce</yt:movies> <yt:music>Elliott Smith</yt:music> <yt:occupation>Technical Writer</yt:occupation> <yt:school>University of North Carolina</yt:school> <media:thumbnail url='http://i.ytimg.com/vi/YFbSxcdOL-w/default.jpg'/> <yt:statistics viewCount='9' videoWatchCount='21' subscriberCount='1' lastWebAccess='2008-02-25T16:03:38.000-08:00'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites' href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts' countHint='1'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.inbox' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox' countHint='0'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.playlists' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.subscriptions' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/andyland74/uploads' countHint='1'/> </entry>
YouTube Data API によって、コンタクトを追加、更新、削除することができます。
このセクションでは、特定のユーザーのコンタクトのリストを含むフィードの取得方法について説明します。
現在ログインしているユーザーのコンタクト リストをリクエストするには、HTTP GET リクエストを次の URL に送信します。注意: このリクエストでは、HTTP リクエストの Authorization ヘッダーに認証トークンを提示する必要があります。YouTube は認証トークンによってユーザーを識別します。
http://gdata.youtube.com/feeds/api/users/default/contacts
別のユーザーのコンタクト リストをリクエストするには、HTTP GET リクエストを次の URL に送信します。このリクエストには、認証は必要ありません。
http://gdata.youtube.com/feeds/api/users/username/contacts
上記の URL の username は、ユーザーの YouTube ユーザー名に置き換えてください。
コンタクト リストのリクエストに対する API レスポンスには、複数の <entry> タグが含まれます。それぞれのタグには、個々のコンタクトに関する以下の情報が含まれます。
edit URL。コンタクトの更新または削除に使用します。フィード エントリの edit URL を識別する方法については、動画エントリに関連するフィードの識別セクションをご覧ください。
<category> タグは、そのコンタクトが友だちなのか家族なのかを示します。
<yt:username> タグは、そのコンタクトの YouTube ユーザー名を示します。
<yt:status> タグは、そのコンタクトのステータスを示します。このタグが表示されるのは、現在認証されているユーザーのコンタクトを取得している場合のみです。このタグには、以下のいずれかの値が含まれます。
次の XML は、コンタクトを含む 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:yt='http://gdata.youtube.com/schemas/2007'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25</id> <updated>2008-02-28T18:43:32.084Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>andyland74's Contacts</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_friends?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=26&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>100</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu</id> <published>2007-01-06T09:38:08.000-08:00</published> <updated>2008-02-28T18:43:32.082Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>danidanciu</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/danidanciu'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=danidanciu'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>danidanciu</yt:username> <yt:status>accepted</yt:status> </entry> </feed>
コンタクトを追加するには、2 人のユーザー (コンタクトを追加するユーザーと、コンタクトに追加されるユーザー) を指定する API リクエストを送信します。リクエストに <category> タグを使用して、そのコンタクトをユーザーの友だちとしてリストに追加するのか、家族として追加するのかを指定することもできます。リクエストでコンタクトのカテゴリを指定しない場合は、コンタクトはユーザーのコンタクト リストに表示されますが、家族カテゴリにも友だちカテゴリにも含まれません。
次のリクエストはコンタクトを追加する際の URL と XML 形式を示すものです。
POST /feeds/api/users/default/contacts HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Friends"/> <yt:username>CONTACT_ID</yt:username> </entry>
次に、コンタクトを追加するための一般的なユース ケースを示します。
ユーザーが動画を見て、動画の所有者を友だちとして追加します。
このユース ケースは、特定の動画の情報を取得するリクエストから始まります。
動画を見た後、ユーザーはリンクをクリックして動画所有者のプロフィールを表示します。
アプリケーションが、動画所有者のプロフィールを取得する API リクエストを送信します。
動画所有者に関する情報を表示するサイト上のページには、動画の所有者を友だちとして追加するリンクが表示されます。ユーザーがこのリンクをクリックすると、アプリケーションがコンタクトを作成する API リクエストを http://gdata.youtube.com/feeds/api/users/default/contacts に送信します。リクエストの <yt:username> タグで、コンタクトに追加する YouTube ユーザーを指定します。また、<category> タグの term 属性はそのコンタクトが友だちか (term="Friends")、家族か (term="Family") を示します。
コンタクトを更新するには、そのコンタクトの edit URL に HTTP PUT リクエストを送信します。次の XML の抜粋は、コンタクト エントリに edit URL がどのように表示されるかを示しています。
<entry> <id>http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID</id> ... <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/> ... </entry>
ユーザーがこの API によってコンタクトを更新する方法は、2 つあります。
ユーザーは、ステータスが requested となっているコンタクトを受け付けることができます。この方法によってコンタクトを更新するには、API リクエストで、次に示すサンプル リクエストのように <yt:status> タグの値を accepted に設定します(同様に、コンタクトを拒否するには、<yt:status> タグの値を rejected に設定します)。
コンタクトは、友だちまたは家族として分類されます。ユーザーは、API を使ってコンタクトをこのいずれかのグループに再分類することができます。コンタクトを友だちとして分類する場合は、<category> タグの term 属性の値を Friends とする必要があります。コンタクトを家族として分類する場合は、<category> タグの term 属性の値を Family とする必要があります。
次のサンプル リクエストは、コンタクトの更新方法を示すものです。この例では、コンタクトが受け付けられて家族として分類されます。この例の変数 USER_ID はコンタクトを追加するユーザーを示し、変数 CONTACT_ID は追加されるコンタクトを示します。
PUT /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Family"/> <status>accepted</status> </entry>
次のユース ケースは、ユーザーがコンタクトを変更する場合のシナリオです。
このユース ケースは、ユーザーのコンタクト リストを取得するリクエストで始まります。API レスポンスに含まれるそれぞれの <entry> タグは、1 件のコンタクト情報を表しています。コンタクトを更新または削除するために必要な URL は、<entry> タグ内の <id> タグで指定されます。
アプリケーションによって、コンタクト リストが表示されます。各コンタクトの横には選択メニューが表示され、ユーザーはコンタクトを家族か友だちに再分類できます。また、ユーザーはステータスが pending または requested となっているコンタクトを受け付けたり、拒否したりすることができます。
ユーザーが 1 つまたは複数のコンタクトを変更し、変更内容を送信します。
アプリケーションがコンタクトのリストをループして、HTTP PUT リクエストを送信して変更された各コンタクトを更新します。アプリケーションは、更新するコンタクトの edit URL に対してそれぞれ API リクエストを送信します。
次のサンプル API リクエストは、コンタクトの削除方法を示すものです。
DELETE /feeds/api/playlists/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
次に、コンタクトを削除するための一般的なユース ケースを示します。
コンタクト更新のユース ケースと同様に、このユース ケースはユーザーのコンタクト リストを取得するリクエストで始まります。
アプリケーションによって、コンタクト リストが表示されます。各コンタクトの横にはチェックボックスが表示され、ユーザーはコンタクトを削除することができます。
ユーザーは 1 つまたは複数のコンタクトのチェックボックスをオンにして、変更内容を送信します。
アプリケーションがコンタクトのリストをループして、HTTP PUT リクエストを送信して選択された各コンタクトを削除します。アプリケーションは、対応するコンタクトの edit URL に対してそれぞれ API リクエストを送信します。
このセクションでは、API リクエストの失敗に伴う XML レスポンスについて説明します。API が返す HTTP レスポンス コードに関する詳細については、リファレンス ガイドをご覧ください。
API リクエストが失敗すると、YouTube は一般的な失敗を示す HTTP 4xx または 5xx レスポンス コードを返すとともに、失敗の原因となったエラーに関して XML レスポンスを返して、より具体的な情報を提供します。各エラーの XML レスポンスは <domain> 要素と<code> 要素を含み、さらに <location> 要素を含む場合もあります。次の項では、これらの要素が取り得る値について説明し、各エラーのサンプル エラー レスポンスを示します。エラー レスポンスには複数のエラーが含まれる場合もあります。
検証エラー (<domain> タグの値が yt:validation) は、エントリ挿入または更新のリクエストに含まれる XML 要素の値に関する問題をレポートします。動画その他のデータの挿入または更新のための API 関数によって、yt:validation エラーがレポートされることがあります。通常、検証エラーは HTTP 400 のレスポンス コードでレポートされます。
すべての検証エラーでは、<location> タグによってエラーの場所が Xpath として示されます。この Xpath は、リクエスト失敗を引き起こした XML タグの位置を示します。Xpath の場所は、リクエスト内の <entry> タグからの相対位置を示します。
検証エラーの場合、<code> タグには次のいずれかの値が含まれます。
required - このコードは、必要なフィールドが存在しないか、そのフィールドの値が空であることを示します。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>required</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
deprecated - このコードは、要素の値が使われなくなり、有効ではなくなったことを示します。たとえば、使われなくなった動画カテゴリ名を、新規に追加または更新する動画に関連付けることはできません。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>deprecated</code> <location type='xpath'> media:group/media:category[@scheme='http://gdata/youtube.com/schemas/2007/categories.cat']/text() </location> </error> </errors>
invalid_format - このコードは、XML 要素の値が期待される形式と合っていないことを示します。たとえば、<gml:pos> タグに無効な座標を指定すると、このエラーが返されます。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>invalid_format</code> <location type='xpath'>georss:where/gml:point/gml:pos/text()</location> </error> </errors>
invalid_character - このコードは、XML フィールドの値に無効な文字列が含まれていることを示します。たとえば、動画のタイトルに記号「<」を含めることはできません。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>invalid_character</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
too_long - このコードは、XML 要素の値が長すぎることを示します。たとえば、動画タイトルは 60 文字以下である必要があります。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>too_long</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
クォータ エラー (<domain> タグの値が yt:quota) は、API の使用率に関する問題を示します。
クォータ エラーの場合、<code> タグには次のいずれかの値が含まれます。
too_many_recent_calls - このコードは、ある時間内に同じ呼び出し元から呼び出された API コールの数が多すぎることを示します。このエラーでは、場所は特定されません。このタイプのエラーでは、API レスポンスに <location> タグは含まれません。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:quota</domain> <code>too_many_recent_calls</code> </error> </errors>
too_many_entries - このコードは、ユーザーがアカウントの制限容量を超えようとしており、新しいエントリを追加する前に既存のエントリを削除する必要があることを示します。このタイプのエラーでは、エラーを引き起こしているフィードが <location> タグによって示されます。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:quota</domain> <code>too_many_entries</code> <location type='other'>http://gdata.youtube.com/feeds/users/username/uploads</location> </error> </errors>
認証エラー (<domain> タグの値が yt:authentication) は、ユーザー認証が必要な API リクエストの認証に関する問題を示します。認証エラーは、HTTP 401 または 403 レスポンス コードで示されます。
認証エラーには、<location> タグが含まれる場合があります。その場合、タグの値によって認証エラーを引き起こしているヘッダーが示されます。
認証エラーの場合、<code> タグには次のいずれかの値が含まれます。
InvalidToken - このコードは、Authorization ヘッダーで指定された認証トークンが無効であることを示します。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:authentication</domain> <code>InvalidToken</code> <location type='header'>Authorization: GoogleLogin</location> </error> </errors>
TokenExpired - このコードは、Authorization ヘッダーで指定された認証トークンが期限切れであることを示します。
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:authentication</domain> <code>TokenExpired</code> <location type='header'>Authorization: GoogleLogin</location> </error> </errors>