SkyDriveのメディアファイルにアクセス
SkyDrive APIの3回目です。今回は、写真・ビデオ・音楽などのメディアファイルにアクセスしてみましょう。SkyDriveでは、これらのファイルは特別なファイルとして扱い、サムネイルなど通常のファイルよりも多くの情報を持っています。またAPIでは、これらを格納するフォルダーをアルバム として通常のフォルダーと区別して扱います。
SkyDriveのWebサイトでは、アルバムという名称は使われていません。フォルダーで統一されています。フォルダーの種類(図1 )が写真のものがアルバムになります。
図1 フォルダーの種類
アルバムは、以前のWindows Liveサービスで使用されていたので、その名残といえるでしょう。
アルバムは、ユーザーからアクセス許可を得るときに関係しています。SkyDriveのアクセスに必要な、OAuthのScope (スコープ )は、次の3種類を前回までに紹介しています。
Scopeの値
説明
wl.skydrive
SkyDriveのフォルダー・ファイルの参照
wl.contacts_skydrive
SkyDriveで共有されているフォルダー・ファイルの参照(wl.skydriveの内容を含む)
wl.skydrive_update
SkyDriveのフォルダー・ファイルの作成・編集・削除(wl.contacts_skydriveの内容を含む)
上記のScopeよりもアクセスが制限されたScopeも用意されています。それが次のアルバムを対象とした読み取り専用のアクセスです。さらに、アルバム内の写真とビデオのみ情報を取得できます。
Scopeの値
説明
wl.photos
SkyDriveのアルバムと写真・ビデオの参照
wl.contacts_photos
SkyDriveで共有されているアルバムと写真・ビデオの参照(wl.photosの内容を含む)
写真・ビデオのみにアクセスするアプリの場合は、これらのScopeを選択しましょう。もし、写真やビデオのアップロードなどを行う場合は、wl.skydrive_update の許可が必要です。
wl.photos を指定したときの認可画面は図2 のようになります。
図2 認可画面
それでは、アルバムや画像・ビデオ・音楽ファイルについて、APIで扱う場合をもう少し詳しくみていきましょう。APIで可能な、アルバムとメディアファイルの操作は次の通りです。
アルバム情報の取得
アルバム情報の変更
アルバムの作成
アルバムの削除
写真、ビデオ、音楽情報の取得
写真、ビデオ、音楽情報の変更
写真、ビデオ、音楽のアップロード
写真、ビデオ、音楽の削除
タグ情報の取得
これらの操作は、前回 紹介したフォルダーとファイルの操作と同等に可能です。アルバムとメディアファイルの操作は、特徴的な操作のみピックアップして紹介します。一部の内容は次回でも紹介する予定です。
アルバム情報の取得
アルバムはフォルダーと同じ情報を持っています。SkyDrive直下のアルバム一覧を取得する場合、次のURLにアクセスすると得られます。
https://apis.live.net/v5.0/me/albums ?access_token=ACCESS_TOKEN
URLにアクセスすると、次のようにJSON形式でアルバム情報を取得できます。
{
"data" : [
{
"id" : "folder.xxxxx" ,
"from" : {
"name" : "梓 中野" ,
"id" : "xxxxx"
},
"name" : "ビデオ" ,
"description" : null ,
"parent_id" : "folder.XXXXX" ,
"count" : 16 ,
"link" : "https://skydrive.live.com/redir.aspx?cid..." ,
"type" : "album" ,
"created_time" : "2010-10-30T14:00:00+0000" ,
"updated_time" : "2012-01-25T11:00:00+0000"
}
]
}
アルバムの情報を表すAlbum オブジェクトの内容は、次の通りです。これは第48回 で紹介したFolder オブジェクトとまったく同じです。ただし、写真・ビデオのアクセス許可しかない場合、一部の項目は取得できません。
プロパティ
型
説明
data
array
Albumオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
AlbumオブジェクトのID
from
object
アルバム作成者の情報
name(fromオブジェクト)
string
作成者の名前
id(fromオブジェクト)
string
作成者のユーザーID
name
string
アルバムの名前(編集可能、新規作成時必須)
description
stringまたはnull
アルバムの説明(編集可能)
count
number
アルバム内のアイテム数
link
string
SkyDriveでのアルバムのURL
upload_location
string
アプリから、このアルバムへファイルをアップロードするためのURL
Scope 「 wl.skydrive」が必要
parent_id
string
このアルバムの上位階層のリソースID(親フォルダーのID)
type
string
オブジェクトの種類
アルバムの場合は、album
created_time
string
アルバムの作成日時(ISO 8601形式)
updated_time
string
アルバム内のコンテンツの更新日時(ISO 8601形式)
shared_with
object
アルバムの共有情報
Scope 「 wl.skydrive」が必要
access(shared_withオブジェクト)
string
アルバムの共有情報
次の値のいずれか
People I selected
Just me
Everyone (public)
Friends
My friends and their friends
People with a link
フォルダーとアルバムでは、type の値が「folder」と「album」で異なります。
アルバム情報を返すリソースのパスは次の通りです。あわせて第48回のフォルダー情報を返すリソースのパスも参照してください。
パス
説明
/ALBUM_ID
特定のアルバム
/ALBUM_ID/files
特定のアルバム内のアイテム
/me/albums
サインインユーザーのSkyDriveのルートにあるアルバム
/me/skydrive/shared/albums
サインインユーザーのSkyDriveの共有フォルダー内のアルバム
/USER_ID/albums
特定のユーザーのSkyDriveのルートにあるアルバム
アルバムの作成
アルバムを作成する場合は、Scope「wl.skydrive_update 」の許可が必要です。作成方法は、第49回 で紹介したフォルダー作成と同じです。アルバムはSkyDrive直下にのみ作成可能で、「 /me/albums」へHTTP POST メソッドでデータを送信します。HTTPの通信内容は次のようになります。
POST https://apis.live.net/v5.0/me/albums?access_token=ACCESS_TOKEN HTTP/1.1
Content-Type: application/json
Host: apis.live.net
Content-Length: 31
Connection: Keep-Alive
{name: "新しいアルバム"}
写真情報の取得
次は、写真ファイルについてみてみましょう。写真ファイルはサムネイルなど多くの情報を持っています。多く情報を得られることを除いては、基本的な内容は通常のファイル(Fileオブジェクト)と同じです。ひとつの写真の情報は次のようなJSON形式で取得できます。
{
"data" : [
{
"id" : "file.xxxxx" ,
"from" : {
"name" : "梓 中野" ,
"id" : "xxxxx"
},
"name" : "azusa.jpg" ,
"description" : null ,
"parent_id" : "folder.XXXXX" ,
"size" : 486730 ,
"comments_count" : 0 ,
"comments_enabled" : false ,
"tags_count" : 0 ,
"tags_enabled" : true ,
"picture" : "http://storage.live.com/..." ,
"source" : "http://storage.live.com/..." ,
"images" : [
{
"height" : 380 ,
"width" : 800 ,
"source" : "http://storage.live.com/..." ,
"type" : "normal"
}, {
"height" : 83 ,
"width" : 176 ,
"source" : "http://storage.live.com/..." ,
"type" : "album"
}, {
"height" : 45 ,
"width" : 96 ,
"source" : "http://storage.live.com/..." ,
"type" : "thumbnail"
}, {
"height" : 975 ,
"width" : 2048 ,
"source" : "http://storage.live.com/..." ,
"type" : "full"
}
],
"link" : "https://skydrive.live.com/redir.aspx?cid..." ,
"when_taken" : null ,
"height" : 975 ,
"width" : 2048 ,
"type" : "photo" ,
"created_time" : "2012-02-09T15:00:00+0000" ,
"updated_time" : "2012-02-09T17:00:00+0000"
}
]
}
写真を表すPhoto オブジェクトの内容は次の通りです。Fileオブジェクトにはない項目は太字にしています。images配列からサムネイル画像を取得できます。また、SkyDriveでは、写真に人物タグを付けられます。このタグ情報の有無も取得できます。
プロパティ
型
説明
data
array
Photoオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
PhotoオブジェクトのID
from
object
作成者の情報
name(fromオブジェクト)
string
作成者の名前
id(fromオブジェクト)
string
作成者のユーザーID
name
string
写真のファイル名(編集可能)
description
string
説明(編集可能)
parent_id
string
この写真の上位階層のリソースID(親フォルダーのID)
size
number
写真のサイズ(バイト単位)
comments_count
number
写真に付けられたコメント数
comments_enabled
true/false
写真にコメント可能かどうか
tags_count
number
写真に付けられたタグ数
tags_enabled
true/false
写真にタグ埋め込み可能かどうか
picture
写真のURL
source
string
写真のダウンロード用のURL(一時的なURLで使う場合は取得後すぐに参照します)
images
array
異なる大きさの写真の情報
height (images配列)
number
高さ(ピクセル)
width (images配列)
number
幅(ピクセル)
source (images配列)
string
特定の大きさの写真のURL
type (images配列)
string
大きさの種類
次の値のいずれか
full(最大2048x2048)
normal(最大800x800)
album(最大200x200)
small(最大100x100)
link
string
SkyDrive上での写真のURL
upload_location
string
アプリから写真をアップロードするためのURL
Scope「wl.skydrive」が必要
when_taken
string/null
撮影日時(ISO 8601形式)
height
number
高さ(ピクセル)
width
number
幅(ピクセル)
type
string
オブジェクトの種類
写真の場合は、photo
created_time
string
写真の作成日時(ISO 8601形式)
updated_time
string
写真の最終更新日時(ISO 8601形式)
shared_with
object
写真の共有情報
access(shared_withオブジェクト)
string
写真の共有情報
次の値のいずれか
People I selected
Just me
Everyone (public)
Friends
My friends and their friends
People with a link
Fileオブジェクトにあった、埋め込み用のHTMLコードの取得可否を示すis_embeddableはPhotoオブジェクトにはありません。APIでは、埋め込み用のHTMLコードを生成できませんが、SkyDriveのWebサイトでは生成できます(図3 ) 。
図3 写真の埋め込み
また、Webサイトでは、撮影したカメラ情報なども参照できますが、APIからは参照できません。
写真の表示
サムネイルやオリジナルの写真の表示は、Photoオブジェクトのimages配列の値が使えますが、次のURLにアクセスしても各サイズの写真を取得できます。
https://apis.live.net/v5.0/PHOTO_ID /picture?type=thumbnail &access_token=ACCESS_TOKEN
PHOTO_IDには、Photoオブジェクトのidの値を指定します。typeパラメーターには、thumbnailのほか、small、album、normal、fullを指定できます。
写真のアップロード
アップロード方法は、前回のファイルのアップロードと同等です。HTTP POSTまたはPUTメソッドで行います。詳しくは、前回 の内容を参照してください。
APIでは、2048×2048ピクセルより大きい写真をアップロードした場合、2048ピクセルまで縮小されてSkyDriveに登録されます。ちなみに、SkyDriveのWebサイトでは図4 のUIから縮小せずにアップロードできます。
図4 写真のアップロード
ビデオ情報の取得
次はビデオファイルです。ビデオファイルは、再生時間やビットレートなどの情報を持っています。ひとつのビデオの情報は次のようなJSON形式で取得できます。
{
"data" : [
{
"id" : "file.xxxxx" ,
"from" : {
"name" : "梓 中野" ,
"id" : "xxxxx"
},
"name" : "azusa.mp4" ,
"description" : null ,
"parent_id" : "folder.XXXXX" ,
"size" : 5819660 ,
"comments_count" : 0 ,
"comments_enabled" : false ,
"tags_count" : 0 ,
"tags_enabled" : true ,
"picture" : "http://storage.live.com/..." ,
"source" : "http://storage.live.com/..." ,
"link" : "https://skydrive.live.com/redir.aspx?cid..." ,
"height" : 360 ,
"width" : 640 ,
"duration" : 106138 ,
"bitrate" : 310190 ,
"type" : "video" ,
"created_time" : "2012-02-09T15:11:00+0000" ,
"updated_time" : "2012-02-09T15:12:00+0000"
}
]
}
ビデオを表すVideo オブジェクトの内容は次の通りです。Fileオブジェクトにはない項目は太字にしています。
プロパティ
型
説明
data
array
Videoオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
VideoオブジェクトのID
from
object
作成者の情報
name(fromオブジェクト)
string
作成者の名前
id(fromオブジェクト)
string
作成者のユーザーID
name
string
ビデオのファイル名(編集可能)
description
string
説明(編集可能)
parent_id
string
このビデオ上位階層のリソースID(親フォルダーのID)
size
number
ビデオのサイズ(バイト単位)
comments_count
number
ビデオに付けられたコメント数
comments_enabled
true/false
ビデオにコメント可能かどうか
tags_count
number
ビデオに付けられたタグ数
tags_enabled
true/false
ビデオにタグ埋め込み可能かどうか
picture
ビデオを表す画像(通常はサムネイル)のURL
source
string
ビデオのダウンロード用のURL(一時的なURLで使う場合は取得後すぐに参照します)
link
string
SkyDrive上でのビデオのURL
upload_location
string
アプリからビデオをアップロードするためのURL
Scope「wl.skydrive」が必要
duration
number
ビデオの再生時間(ミリ秒)
bitrate
number
ビットレート(bps)
type
string
オブジェクトの種類
ビデオの場合は、video
created_time
string
ビデオの作成日時(ISO 8601形式)
updated_time
string
ビデオの最終更新日時(ISO 8601形式)
shared_with
object
ビデオの共有情報
access(shared_withオブジェクト)
string
ビデオの共有情報
次の値のいずれか
People I selected
Just me
Everyone (public)
Friends
My friends and their friends
People with a link
Photoオブジェクトと同じく、埋め込み用のHTMLコードの取得可否を示すis_embeddableはVideoオブジェクトにはありません。SkyDriveのWebサイトでは埋め込みのHTMLコードの生成が可能です。
音楽情報の取得
音楽ファイルは、通常のファイルと扱いが同じです。Scope「wl.photos」で参照できず、「 wl.skydrive」の許可が必要となります。音楽を表すAudioオブジェクトの内容は次の通りです。Fileオブジェクトと同じ構造になっています。
プロパティ
型
説明
data
array
Audioオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
AudioオブジェクトのID
from
object
作成者の情報
name(fromオブジェクト)
string
作成者の名前
id(fromオブジェクト)
string
作成者のユーザーID
link
string
SkyDrive上での音楽のURL
name
string
音楽のファイル名(編集可能)
description
string
説明(編集可能)
parent_id
string
このビデオ上位階層のリソースID(親フォルダーのID)
size
number
音楽のサイズ(バイト単位)
comments_count
number
音楽に付けられたコメント数
comments_enabled
true/false
音楽にコメント可能かどうか
is_embeddable
true/false
埋め込み用のHTMLコードを取得可能かどうか
source
string
音楽のダウンロード用のURL(一時的なURLで使う場合は取得後すぐに参照します)
upload_location
string
アプリからファイルをダウンロードするためのURL
type
string
オブジェクトの種類
音楽の場合は、audio
created_time
string
音楽の作成日時(ISO 8601形式)
updated_time
string
音楽の最終更新日時(ISO 8601形式)
shared_with
object
音楽の共有情報
access(shared_withオブジェクト)
string
音楽の共有情報
次の値のいずれか
People I selected
Just me
Everyone (public)
Friends
My friends and their friends
People with a link
アップロードなどの操作も通常のファイルと同じです。ただし、APIでは、音楽のアップロードはWaveファイルに限られています。
おわりに
今回はここまでです。いかがでしたでしょうか。メディアファイルの中でも写真については、Windows Live APIで古くから共有する仕組みが提供されてきました。サードパーティのアプリによる写真の共有は、マイクロソフトが想定・希望している使い方かもしれませんね。Live ConnectによるSkyDriveアクセスで、写真のアップロードもAPIで可能になり、より多彩なアプリの開発ができるようになっています。ぜひAPIを活用してみてください。次回は、まだ紹介できていないファイル操作について紹介する予定です。