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とシームレスな連携も特徴です。

昨年の11月にアップデートがあり、さらにモバイル向けアプリが12月に公開されています。アップデートでは、共有機能の強化や、右クリックによるメニューの表示、ドラッグドロップによるファイルのアップロードなど、使いやすいUIが提供されています。

昨年からSkyDriveはHTML5やCSS3の機能を積極的に利用し、Internet Explorer 10や最新のGoogle Chrome、Firefoxで動作する機能もあります。Windows 8でもクラウドストレージとして重要な役割を担うと予想されます。まだ利用してみたことがない方は、今のうちに使ってみてください。もし改善点などの要望があれば、フィードバックを「ご意見ご感想」から送信するとよいでしょう。

SkyDrive APIのできること・できないこと

それでは、APIの内容についてみていきましょう。ちなみにSkyDrive APIという言葉は、正式なドキュメントには出てきていません。SkyDriveへのアクセスは、Live Connectで接続できるリソースのひとつにすぎません。言い換えると、SkyDrive以外のリソースにもこれから紹介する同様の手法でアクセス可能です。

Live Connectを利用すると、WebサービスのSkyDriveと同じものが作れるかというとそうではありません。今のところ、フォルダーやファイルの操作は限定されています。また扱えるファイルの種類も制限されています。

フォルダー・ファイルのアクセス

Live Connectで、フォルダーとファイルについて可能な操作は、次の通りです。

• フォルダー・ファイル情報の取得
• フォルダー・ファイル情報の変更
• フォルダーの作成
• フォルダー・ファイルの削除
• ファイルのダウンロード
• ファイルのアップロード
• フォルダー・ファイルの共有リンクの作成
• ファイルの埋め込み用HTMLコードの取得
• フォルダー・ファイルの移動
• ファイルのコピー
• フォルダー・ファイルのコメント取得

SkyDriveでは、アルバムという特別なフォルダーがあります。アルバムは、写真やビデオ、音楽ファイルの保存を目的としたもので、SkyDriveのUIでは「写真」メニューから、まとめて表示できます（図2⁠）⁠。通常のフォルダーとアルバムの変更は、フォルダーの種類（図3）から行います[2]⁠。

写真・ビデオ・音楽ファイルは特別なファイルとして扱われ、サムネイルなどファイルより多くの情報を持っています。

アルバムと写真などのファイルについても、フォルダーやファイルと同様の操作ができます。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を指定します。

アクセストークンの取得については、第45回で詳しく説明していますので、そちらも参照してください。

SkyDriveのアクセスについて、ユーザーから認可を得るときに指定する許可の内容Scope（スコープ）は、次の通りです。

ファイルの読み取りだけが必要な場合は、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⁠）⁠。

このフォルダーの情報を表すFolderオブジェクトの内容は、次の通りです。

ひとつのフォルダー情報を取得する場合は、パスに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

フォルダー情報を返すリソースのパスは、次の通りです。

上記の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オブジェクトの内容は次の通りです。

Folderオブジェクトとほぼ同じ内容ですが、ファイルサイズなどファイル特有の情報が含まれています。公開しているファイルにはコメントを付けることができ、その情報を取得できます。また、PowerPointなどの文書はWebページに貼り付けるHTMLコードが生成できます。その埋め込み可否の情報もあります。

ひとつのファイル情報を取得する場合は、パスにFileオブジェクトIDを指定してHTTP GETメソッドでアクセスします。

• https://apis.live.net/v5.0/FILE_ID?access_token=ACCESS_TOKEN

ファイル情報が含まれるリソースのパスは次の通りです。

以上が、ファイル情報の取得についてです。

PHPでフォルダー・ファイルの表示

ここまでの内容をふまえて簡単なサンプルコードを示します。Live Connectは、特定のプラットフォームやプログラミング言語に依存していません。基本的にはHTTP(S)通信とテキスト処理だけです。OAuthの認可処理のみWebブラウザーコントロールなどを使う必要があります。

ここでは、PHPを使って記述します。マイクロソフトからGitHub上に各種プラットフォームや言語でのサンプルコードが提供されていますので、そちらも確認してみるとよいでしょう。

サンプルは、SkyDriveのアイテム一覧を表示する単純なものです（図6⁠）⁠。フォルダー（またはアルバム）の場合は、リンクとして表示して下の階層へ移動できるようにしています。

• サンプルを実行する

PHPによるOAuthの認可処理とREST API呼出しは、第45回でも登場しています。そのときは、サインインしたユーザー名の表示を行いました。今回のコードでの違いはSkyDriveの情報の表示になっているだけで大きな違いはありません。以下にすべてのコードを示します。

<?php
    define('CLIENT_ID',     'xxxxx'); // Client ID と Client Secret を設定してください
    define('CLIENT_SECRET', 'xxxxx'); // 
    define('REDIRECT_URI',  'http%3A%2F%2Fkatamari.jp%2Fgihyo%2Flive%2F48.php'); // Redirect 先を設定してください

    // Access Token 処理
    if (isset($_GET['code']) && preg_match('/^[A-Fa-f0-9\-]+$/', $_GET['code'])) {
        // 認可画面からのリダイレクト
        
        // Access Token 取得
        $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'];
    }

    // ***.php?folder_id=xxx のようにクエリーに Folder オブジェクトの ID が
    // 指定されている場合、そのフォルダー内のアイテムを表示する
    if (isset($_GET['id']) && preg_match('/^[A-Za-z0-9!\.]+$/', $_GET['id'])) {
        $path = $_GET['id'] . '/files';
    } else {
        $path = 'me/skydrive/files';
    }
    
    // REST API 呼び出しと HTML 生成
    if ($token && !$body) {
        $body = createList($token, $path);
    }
    
    // サインインしていない場合は認可画面へのリンクを表示
    if (!$body) {
        $signInUri = 'https://oauth.live.com/authorize' .
            '?client_id=' . CLIENT_ID .
            '&scope=wl.signin%20wl.skydrive' . // Scope に wl.skydrive を指定
            '&response_type=code' .
            '&display=popup' .
            '&locale=ja' .
            '&redirect_uri=' . REDIRECT_URI;
    }
   
    // REST API 呼出しと HTML 生成
    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);
        
        // エラーの場合 false を返す
        $res = curl_exec($ch);
        if ($no = curl_errno($ch)) {
            return false;
        }
        curl_close($ch);
        return json_decode($res, true);
    }
    
    // REST API の呼び出し (GET メソッドのみ 対応)
    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);
        
        // エラーの場合 false を返す
        $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のアクセスについて紹介する予定です。