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

第48回SkyDrive API 概要(1)

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
図1 SkyDrive

昨年の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]⁠。

図2 写真フォルダーの表示
図2 写真フォルダーの表示
図3 フォルダーの種類の変更
図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 APIManaged 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 認可画面
図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 フォルダー情報の取得
図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 サンプルの実行結果
図6 サンプルの実行結果<a nam

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のアクセスについて紹介する予定です。

おすすめ記事

記事・ニュース一覧