使ってみよう! Windows Live SDK/API

第50回SkyDrive API 概要(3)─⁠─メディアファイルのアクセス

SkyDriveのメディアファイルにアクセス

SkyDrive APIの3回目です。今回は、写真・ビデオ・音楽などのメディアファイルにアクセスしてみましょう。SkyDriveでは、これらのファイルは特別なファイルとして扱い、サムネイルなど通常のファイルよりも多くの情報を持っています。またAPIでは、これらを格納するフォルダーをアルバムとして通常のフォルダーと区別して扱います。

SkyDriveのWebサイトでは、アルバムという名称は使われていません。フォルダーで統一されています。フォルダーの種類図1が写真のものがアルバムになります。

図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 認可画面
図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のルートにあるアルバム

アルバムの作成

アルバムを作成する場合は、Scopewl.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 写真の埋め込み 図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 写真のアップロード
図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を活用してみてください。次回は、まだ紹介できていないファイル操作について紹介する予定です。

おすすめ記事

記事・ニュース一覧