Live ConnectとSkyDrive
前回 から日が開いてしまいましたが、本年も引き続きLive Connect を紹介していきます。よろしくお願いいたします。
Live Connectは、Windows Liveサービスと統合したアプリ開発を可能にするAPIコレクションです。2011年12月にLive Connectのアップデートのアナウンスがありました(Inside Windows Live ) 。これまでのDeveloper Preview版から、若干の修正を加え、正式なバージョンとしてAPIを利用できるようになっています。
アップデートに伴い、開発者向けのサイト、Live Connect Developer Center も更新され、新しいLive SDK もリリースされています。詳しく知りたい方は、こちらもチェックしてみてください。
さて、今回はSkyDrive です。Live Connectを利用するとSkyDriveにアクセスできます。SkyDriveのAPIを待望していた人も多いのではないでしょうか。Live Connectの前身であるMessenger Connectでも限定的なアクセスはできていましたが、オブジェクトの作成やアップロードなどの操作は、今回のLive Connectからできるようになりました。Live Connectは特定のプラットフォームに限定されたものではありません。iOSやAndroidなどからも使えます。Windows PhoneやWindows 8では、便利に使えるAPIが用意されています。ぜひSkyDriveと連携したアプリ開発にトライしてみてください。
新しいSkyDrive
はじめにSkyDriveのサービス自体について紹介します。SkyDrive は、無償のオンラインストレージサービスです。写真やファイルを保存、そして共有できます。容量は25GBまで利用できます[1] 。Office文書の作成・表示・共有などOffice Web Appsとシームレスな連携も特徴です。
図1 SkyDrive
昨年の11月にアップデートがあり、さらにモバイル向けアプリ が12月に公開されています。アップデートでは、共有機能の強化や、右クリックによるメニューの表示、ドラッグドロップによるファイルのアップロードなど、使いやすいUIが提供されています。
昨年からSkyDriveはHTML5やCSS3の機能を積極的に利用し、Internet Explorer 10や最新のGoogle Chrome、Firefoxで動作する機能もあります。Windows 8でもクラウドストレージとして重要な役割を担うと予想されます。まだ利用してみたことがない方は、今のうちに使ってみてください。もし改善点などの要望があれば、フィードバックを「ご意見ご感想」から送信するとよいでしょう。
[1]
ひとつのファイルは100MBまでのサイズ制限があります。少しややこしいのですが、Live Meshを利用すると5GBのストレージを追加で利用でき、ひとつのファイルサイズの制限もありません。また、Liveグループを利用するとグループ専用の5GBのストレージが利用できます。
SkyDrive APIのできること・できないこと
それでは、APIの内容についてみていきましょう。ちなみにSkyDrive APIという言葉は、正式なドキュメントには出てきていません。SkyDriveへのアクセスは、Live Connectで接続できるリソースのひとつにすぎません。言い換えると、SkyDrive以外のリソースにもこれから紹介する同様の手法でアクセス可能です。
Live Connectを利用すると、WebサービスのSkyDriveと同じものが作れるかというとそうではありません。今のところ、フォルダーやファイルの操作は限定されています。また扱えるファイルの種類も制限されています。
フォルダー・ファイルのアクセス
Live Connectで、フォルダーとファイルについて可能な操作は、次の通りです。
フォルダー・ファイル情報の取得
フォルダー・ファイル情報の変更
フォルダーの作成
フォルダー・ファイルの削除
ファイルのダウンロード
ファイルのアップロード
フォルダー・ファイルの共有リンクの作成
ファイルの埋め込み用HTMLコードの取得
フォルダー・ファイルの移動
ファイルのコピー
フォルダー・ファイルのコメント取得
SkyDriveでは、アルバムという特別なフォルダーがあります。アルバムは、写真やビデオ、音楽ファイルの保存を目的としたもので、SkyDriveのUIでは「写真」メニューから、まとめて表示できます(図2 ) 。通常のフォルダーとアルバムの変更は、フォルダーの種類(図3 )から行います[2] 。
図2 写真フォルダーの表示
図3 フォルダーの種類の変更
写真・ビデオ・音楽ファイルは特別なファイルとして扱われ、サムネイルなどファイルより多くの情報を持っています。
アルバムと写真などのファイルについても、フォルダーやファイルと同様の操作ができます。Live Connectでは、通常のフォルダーやファイルと区別して操作でき、アルバム内の写真の一覧の取得といった操作も可能です。また、ユーザーはアプリに対して、アルバム情報のみアクセスを許可するといったこともできます。アルバム関連で可能な操作は次の通りです。
アルバム情報の取得
アルバム情報の変更
アルバムの作成
アルバムの削除
写真、ビデオ、音楽情報の取得
写真、ビデオ、音楽情報の変更
写真、ビデオ、音楽のアップロード
写真、ビデオ、音楽の削除
タグ情報の取得
以上が、SkyDriveのフォルダーやファイルに対してできる操作です。これ以外の操作、たとえば、共有設定の変更などはできません。
サポートしているファイル
扱うファイルにも制限があります。サポートしているファイルは、次の通りです。
ドキュメント(PDF、テキストファイル、マイクロソフトOffice文書)
写真(一般的なファイルフォーマットのみ)
ビデオ(H.264およびWindows Media Video)
音楽(アップロードはWaveファイルのみ)
大きく分類して、ドキュメント・写真・ビデオ・音楽の4種類があります。サポートしていない形式(拡張子)は、アップロードできません。ただし、参照やダウンロードは可能です。
APIを利用したアプリの開発
Live Connectは、ユーザーの認証に、標準的なプロトコルのOAuth 2.0 を利用しています。OAuthの仕組みに従って、アプリは利用者からリソースのアクセス許可を得て、SkyDriveなどのリソースを操作します。Live ConnectとOAuthについては、第45回 で詳しく説明していますので、そちらをご覧ください。また、事前にアプリケーション設定サイト で、アプリの登録が必要です。新しくガイドライン が提供されています。こちらも開発する前に併せて確認してください。
Live Connectでは、リソースのアクセスにREST API を利用します。一部のリソースを除いて、すべてHTTP(S)の通信と、JSON形式のデータのやりとりで行います。基本的にどのアプリもこのREST APIを利用してリソースアクセスを行います。
Webブラウザー上で動作するアプリとWindows 8およびWindows Phone向けには、JavaScript API とManaged API も利用できます。ライブラリーとして提供されていて、内部ではOAuthによる認可処理とREST APIの呼び出しが行われていますが、より簡単にそして各プラットフォームに適したUIが提供されています。JavaScript APIは、これまでにも紹介していますので、以前の連載内容を参照してください。
今回の簡単なサンプルコードでは、REST APIのみを使用します。それでは、SkyDriveに関係するREST APIをみていきましょう。
フォルダー情報の取得
最初にフォルダーの情報を取得してみましょう。たとえば、SkyDriveのルートフォルダーの情報は次のURLにアクセスすると得られます。
https://apis.live.net/v5.0/me/skydrive?access_token=ACCESS_TOKEN
URLのACCESS_TOKENには、OAuthのAccess token (アクセストークン )を指定します。手っ取り早くアクセストークンを得るには、Webブラウザーに次のURLを入力します。認可画面(図4 )に移動し、認可後のURLを参照するとアクセストークンが含まれています。
https://oauth.live.com/authorize?client_id=CLIENT_ID &scope=wl.skydrive &response_type=token&locale=ja &redirect_uri=https://oauth.live.com/desktop
CLIENT_IDには、アプリ登録時に取得したClient ID を指定します。
図4 認可画面
アクセストークンの取得については、第45回 で詳しく説明していますので、そちらも参照してください。
SkyDriveのアクセスについて、ユーザーから認可を得るときに指定する許可の内容Scope (スコープ )は、次の通りです。
Scopeの値
説明
wl.skydrive
SkyDriveのフォルダー・ファイルの参照
wl.contacts_skydrive
SkyDriveで共有されているフォルダー・ファイルの参照(wl.skydriveの内容を含む)
wl.skydrive_update
SkyDriveのフォルダー・ファイルの作成・編集・削除(wl.contacts_skydriveの内容を含む)
ファイルの読み取りだけが必要な場合は、wl.skydriveを指定し、作成などのアクセスも含める場合は、wl.skydrive_updateを指定します。アプリに必要な許可のみユーザーに要求するようにしましょう。上記以外にも、よりアルバムや写真のアクセスに操作を制限した、wl.photos や、wl.contacts_photos も指定できます。
最初のURLにアクセスすると、ルートフォルダーの情報が、次のようなJSON形式で取得できます。
{
"id" : "folder.xxxxx" ,
"from" : {
"name" : null ,
"id" : null
},
"name" : "SkyDrive" ,
"description" : null ,
"parent_id" : null ,
"upload_location" : "https://apis.live.net/v5.0/folder.xxxxx/files/" ,
"count" : 4 ,
"link" : "https://skydrive.live.com?cid\xxxxx" ,
"type" : "folder" ,
"shared_with" : {
"access" : "Just me"
},
"created_time" : null ,
"updated_time" : "2012-01-09T14:00:00+0000"
}
Webブラウザーでも、簡単に内容を確認できます(図5 ) 。
図5 フォルダー情報の取得
このフォルダーの情報を表すFolder オブジェクトの内容は、次の通りです。
プロパティ
型
説明
data
array
Folderオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
Folderオブジェクトの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
オブジェクトの種類 フォルダーの場合は、folder
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
ひとつのフォルダー情報を取得する場合は、パスにFolderオブジェクトIDを指定してHTTP GETメソッドでアクセスします(URLのFOLDER_IDには、FolderオブジェクトのIDを指定します) 。
https://apis.live.net/v5.0/FOLDER_ID ?access_token=ACCESS_TOKEN
フォルダー内のアイテムを取得する場合は、パスに/filesを付けて次のようにします。
https://apis.live.net/v5.0/FOLDER_ID /files?access_token=ACCESS_TOKEN
フォルダー情報を返すリソースのパスは、次の通りです。
パス
説明
/FOLDER_ID
特定のフォルダー
/FOLDER_ID/files
特定のフォルダー内のアイテム
/me/skydrive
サインインユーザーのSkyDriveのルートフォルダー
/me/skydrive/files
サインインユーザーのSkyDriveのフォルダー内のアイテム
/me/skydrive/shared または /me/skydrive/shared/files
サインインユーザーのSkyDriveの共有フォルダー内のアイテム
/USER_ID/skydrive/files
特定のユーザーのSkyDriveのフォルダー内のアイテム
/ALBUM_ID/files
特定のアルバム内のアイテム
上記のUSER_IDは、パス「/me」などで得られるユーザーのIDです。ALBUM_IDは、今回紹介しませんが、アルバムを表すAlbumオブジェクトのIDです。
フォルダーに格納できるアイテムは、フォルダー、ファイル、写真、ビデオ、音楽の5種類です。実際に、写真などが含まれているフォルダーのファイル一覧を取得してみるといろいろな情報が得られると思います。
ファイル情報の取得
次はファイル情報を取得してみましょう。フォルダーのパスに「/files」を付けると、フォルダー内のアイテムが取得できます。ひとつのファイル情報は、次のようなJSON形式で取得できます。
{
"id" : "file.xxxxx" ,
"from" : {
"name" : "梓 中野" ,
"id" : "xxxxx"
},
"name" : "prpr.txt" ,
"description" : null ,
"parent_id" : "folder.xxxxx" ,
"size" : 1234 ,
"upload_location" : "https://apis.live.net/v5.0/file.xxxxx/content/" ,
"comments_count" : 0 ,
"comments_enabled" : false ,
"is_embeddable" : false ,
"source" : "http://storage.live.com/xxxxx" ,
"type" : "file" ,
"shared_with" : {
"access" : "Just me"
},
"created_time" : "2011-12-13T14:42:23+0000" ,
"updated_time" : "2011-12-13T14:42:23+0000"
}
ファイルの情報を表す、File オブジェクトの内容は次の通りです。
プロパティ
型
説明
data
array
Fileオブジェクトを含む配列(複数のアイテムを含む結果の場合)
id
string
FileオブジェクトのID
from
object
ファイル作成者の情報
name(fromオブジェクト)
string
作成者の名前
id(fromオブジェクト)
string
作成者のユーザーID
link
string
SkyDrive上でのファイルのURL
name
string
ファイル名(編集可能)
description
string
説明(編集可能)
size
number
ファイルのサイズ(バイト単位)
comments_count
number
ファイルに付けられたコメント数
comments_enabled
true/false
ファイルにコメント可能かどうか
is_embeddable
true/false
埋め込み用のHTMLコードを取得可能かどうか
source
string
ファイルのダウンロード用のURL(一時的なURLで使う場合は取得後すぐに参照します)
upload_location
string
アプリからファイルをアップロードするためのURL
type
string
オブジェクトの種類 ファイルの場合は、file
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
Folderオブジェクトとほぼ同じ内容ですが、ファイルサイズなどファイル特有の情報が含まれています。公開しているファイルにはコメントを付けることができ、その情報を取得できます。また、PowerPointなどの文書はWebページに貼り付けるHTMLコードが生成できます。その埋め込み可否の情報もあります。
ひとつのファイル情報を取得する場合は、パスにFileオブジェクトIDを指定してHTTP GETメソッドでアクセスします。
https://apis.live.net/v5.0/FILE_ID ?access_token=ACCESS_TOKEN
ファイル情報が含まれるリソースのパスは次の通りです。
パス
説明
/FILE_ID
特定のファイル
/FOLDER_ID/files
特定のフォルダー内のアイテム
/me/skydrive/files
サインインユーザーのSkyDriveのアイテム
/me/skydrive/shared または /me/skydrive/shared/files
サインインユーザーのSkyDriveで共有されているアイテム
/USER_ID/skydrive/files
特定のユーザーのSkyDriveのアイテム
以上が、ファイル情報の取得についてです。
PHPでフォルダー・ファイルの表示
ここまでの内容をふまえて簡単なサンプルコードを示します。Live Connectは、特定のプラットフォームやプログラミング言語に依存していません。基本的にはHTTP(S)通信とテキスト処理だけです。OAuthの認可処理のみWebブラウザーコントロールなどを使う必要があります。
ここでは、PHPを使って記述します。マイクロソフトからGitHub 上に各種プラットフォームや言語でのサンプルコードが提供されていますので、そちらも確認してみるとよいでしょう。
サンプルは、SkyDriveのアイテム一覧を表示する単純なものです(図6 ) 。フォルダー(またはアルバム)の場合は、リンクとして表示して下の階層へ移動できるようにしています。
図6 サンプルの実行結果
PHPによるOAuthの認可処理とREST API呼出しは、第45回 でも登場しています。そのときは、サインインしたユーザー名の表示を行いました。今回のコードでの違いはSkyDriveの情報の表示になっているだけで大きな違いはありません。以下にすべてのコードを示します。
<? php
define ( 'CLIENT_ID' , 'xxxxx' );
define ( 'CLIENT_SECRET' , 'xxxxx' );
define ( 'REDIRECT_URI' , 'http%3A%2F%2Fkatamari.jp%2Fgihyo%2Flive%2F48.php' );
if ( isset ( $_GET [ 'code' ]) && preg_match ( '/^[A-Fa-f0-9\-]+$/' , $_GET [ 'code' ])) {
$tokens = getTokens ( $_GET [ 'code' ]);
if (! $tokens ) {
$body = "Error" ;
} else if ( array_key_exists ( 'error' , $tokens )) {
$body = htmlspecialchars ( $tokens [ 'error' ][ 'error_description' ], ENT_QUOTES , 'UTF-8' );
} else {
$token = $tokens [ 'access_token' ];
setcookie ( 'AccessToken' , $token , 0 );
}
} else if ( isset ( $_COOKIE [ 'AccessToken' ])) {
$token = $_COOKIE [ 'AccessToken' ];
}
if ( isset ( $_GET [ 'id' ]) && preg_match ( '/^[A-Za-z0-9!\.]+$/' , $_GET [ 'id' ])) {
$path = $_GET [ 'id' ] . '/files' ;
} else {
$path = 'me/skydrive/files' ;
}
if ( $token && ! $body ) {
$body = createList ( $token , $path );
}
if (! $body ) {
$signInUri = 'https://oauth.live.com/authorize' .
'?client_id=' . CLIENT_ID .
'&scope=wl.signin%20wl.skydrive' .
'&response_type=code' .
'&display=popup' .
'&locale=ja' .
'&redirect_uri=' . REDIRECT_URI ;
}
function createList ( $token , $path ) {
$res = callRestApi ( $token , $path );
if ( $res === false ) {
return "Error" ;
} else if ( array_key_exists ( 'error' , $res )) {
return htmlspecialchars ( $res [ 'error' ][ 'message' ], ENT_QUOTES , 'UTF-8' );
} else {
$body = '<ul>' ;
foreach ( $res [ 'data' ] as $val ) {
$name = htmlspecialchars ( $val [ 'name' ], ENT_QUOTES , 'UTF-8' );
if ( $val [ 'type' ] === 'folder' || $val [ 'type' ] === 'album' ) {
$body .= '<li><a href="?id=' . $val [ 'id' ] . '">' . $name . '</a></li>' ;
} else {
$body .= '<li>' . $name . '</li>' ;
}
}
$body .= '</ul>' ;
return $body ;
}
}
function getTokens ( $code ) {
$ch = curl_init ();
curl_setopt ( $ch , CURLOPT_URL ,
'https://oauth.live.com/token' .
'?client_id=' . CLIENT_ID .
'&redirect_uri=' . REDIRECT_URI .
'&client_secret=' . CLIENT_SECRET .
'&code=' . $code .
'&grant_type=authorization_code' );
curl_setopt ( $ch , CURLOPT_RETURNTRANSFER , true );
curl_setopt ( $ch , CURLOPT_SSL_VERIFYPEER , false );
curl_setopt ( $ch , CURLOPT_SSL_VERIFYHOST , 0 );
$res = curl_exec ( $ch );
if ( $no = curl_errno ( $ch )) {
return false ;
}
curl_close ( $ch );
return json_decode ( $res , true );
}
function callRestApi ( $token , $path ) {
$ch = curl_init ();
curl_setopt ( $ch , CURLOPT_URL ,
'https://apis.live.net/v5.0/' .
$path .
'?access_token=' . $token );
curl_setopt ( $ch , CURLOPT_RETURNTRANSFER , true );
curl_setopt ( $ch , CURLOPT_HTTPGET , true );
curl_setopt ( $ch , CURLOPT_SSL_VERIFYPEER , false );
curl_setopt ( $ch , CURLOPT_SSL_VERIFYHOST , 0 );
$res = curl_exec ( $ch );
if ( $no = curl_errno ( $ch )) {
return false ;
}
curl_close ( $ch );
return json_decode ( $res , true );
}
?>
<!DOCTYPE html>
<html lang = "ja" >
<head>
<meta charset = "utf-8" />
<title> SkyDrive Sample </title>
</head>
<body>
<? php
if ( $signInUri ) {
?>
<div> <a href=" <? php echo $signInUri ; ?> ">サインイン </a></div>
<? php
} else {
echo $body ;
}
?>
</body>
</html>
少しごちゃごちゃとしていますが、単純なREST処理のみでSkyDriveにアクセスできることがわかるかと思います。サンプルでは、下の階層へ移動するため、一時的にCookieにアクセストークンを保存しています。アクセストークンには有効期限がありますが、コードでは考慮していません。
おわりに
今回はここまでです。いかかでしたでしょうか。今回は、SkyDriveのフォルダーとファイル情報の取得まで紹介しました。SkyDriveの操作は制限されているとはいえ、作成・削除など多くの操作ができ、まだまだ紹介できていない内容があります。次回以降もLive Connectを利用してSkyDriveのアクセスについて紹介する予定です。