はじめに

前回、Windows Liveサービスと統合したアプリ開発を可能にするMessenger ConnectというAPIコレクションについて概要を紹介しました。今回からもう少し詳しくAPIや仕組みについて紹介していきます。

今回は、Webブラウザーベースのアプリ開発を可能にするJavaScript APIの利用を紹介します。

JavaScript APIオブジェクト

JavaScript APIは、前回で紹介したようにscriptタグでライブラリーを参照して利用します。JavaScript APIを利用すると、短いコードでWindows Liveと統合したWebアプリが作成可能です。またPHPなどを使ってサーバー側の処理を記述する必要ありません。

<script src="https://js.live.net/v5.0/ja/wl.js" type="text/javascript"></script>

ライブラリーを参照すると、WLオブジェクトが使えるようになります。WLオブジェクトの各メソッドを呼出し、Windows Liveサービスへのサインイン・サインアウトや、イベント処理、ユーザーデータのアクセスなどを行います。

WLオブジェクトに用意されているメソッドは次の通りです。

また、WLオブジェクト以外に登場するオブジェクトは次の通りです。

以上のように、現在のJavaScript APIはシンプルな構成になっています。Messenger ConnectのJavaScript APIは、Facebookなどのサービスと連携したアプリへの機能追加も考慮し、シンプルな構成で記述できるようになっています。このAPIの構成はFacebookのJavaScript SDKと同等になっています。FacebookのSDKを利用したことのある方であれば、同様の記述でWindows Live統合のアプリを作成したり、既存アプリに機能を追加することが簡単に可能です。

それでは、WLオブジェクトの機能を順に見ていきましょう。

初期化処理

WLオブジェクトのinitメソッドで、ライブラリーの初期化処理を行います。イベントの関連付け処理を除いて、WLオブジェクトのほかのメソッドを呼ぶ前にinitメソッドを呼びます。

メソッドには、アプリのClient IDやリダイレクト先をJSON形式で渡します。Client IDは、アプリの登録時にアプリケーション設定サイトで取得した値です。

WL.init({
    client_id: "xxxxxxxx",
    redirect_uri: "http://***.jp/sample.html"
});

指定できるプロパティは次の通りです。通常はclient_idのみ使います。サインインした後のページを変更したい場合は、redirect_uriも指定します。

ログは、Internet Explorerの開発者ツールでは図1のように表示されます。

サインインコントロール

uiメソッドを使用すると、UIコントロールを簡単にWebページに設置できます。現在は、サインインコントロール（図2）のみ用意されています。

サインインコントロールをユーザーがクリックすると、Windows Liveの認可ウィンドウが開きます。

uiメソッドでは、見た目の指定と、ユーザーに求める許可（Scope）を指定します。

WL.ui({
    name: "signin",
    element: "signInButton",
    scope: ["wl.signin", "wl.basic"]
});

必須のプロパティは次のふたつです。

nameの値がsigninの場合、Scopeの指定と、見た目をカスタマイズできます。

Scopeは、上記コードのように「wl.signin」などの文字列を配列形式で指定します（Scopeがひとつの場合は、配列ではなく文字列形式でも指定可⁠）⁠。省略した場合、自動サインインの許可を表す「wl.signin」です。

見た目と動作に関するプロパティは次の通りです。

typeの値にsigninを指定した場合“⁠サインイン⁠”“⁠サインアウト⁠”⁠、loginの場合“⁠ログイン⁠”“⁠ログアウト⁠”⁠、connectの場合“⁠接続⁠”“⁠サインアウト⁠”のテキストが使用されます。customを指定した場合、自由にボタンのテキストを変更できます。

コード例は次のようになります。

WL.ui({
    name: "signin",
    element: "signInButton",
    scope: ["wl.signin"],
    brand: "hotmail",
    type: "custom",
    sign_in_text: "Connect with Hotmail",
    sign_out_text: "Disconnect"
});

見た目をカスタマイズした結果は図3のようになります。

サインインとサインアウト

サインイン処理は、サインインコントロールのほかに、loginとlogoutメソッドでも可能です。独自のコントロールやサインイン・サインアウト用のリンクを用意する場合に、コードからサインインとサインアウトができます。

loginメソッドは、要求するScopeとサインイン後に移動するリダイレクト先のURLの指定が可能です。Scopeの指定は必須です。

WL.login({
    scope: ["wl.signin", "wl.basic"],
    redirect_url: "http://****.jp/sample.html"
});

また、サインイン処理が完了後に実行する関数の指定も可能です。

WL.login({
    scope: ["wl.signin", "wl.basic"]
}, function() {
    alert("サインイン完了");
});

logoutメソッドを呼ぶと、サインアウトします。

WL.logout();

サインアウト完了後に実行する関数も指定できます。

WL.out(function() {
    alert("サインアウト完了");
});

サインイン状態の取得

ユーザーのサインイン状態は、getLoginStatusメソッドで取得できます。getLoginStatusメソッドは非同期のメソッドで、引数に結果を受け取るコールバック関数を指定します。

コールバック関数で、statusオブジェクトを受け取ります。オブジェクトのstatusプロパティの値によって、サインイン状態を知ります。値は、connected・notConnected・unknownのいずれかです。

WL.getLoginStatus(
    function(r) {
        if (r.status == "connected") {
            alert("サインイン状態");
        } else if (r.status == "notConnected") {
            alert("サインアウト状態");
        } else {
            // status == "unknown"
            alert("不明");
        }
    }
);

getLoginStatusメソッドの第２引数にtrueを指定した場合、Windows Liveサービスに毎回接続し状態を取得します。

WL.getLoginStatus(function(r) {/*省略*/}, true);

セッション情報の取得

セッション情報は、getSessionメソッドで取得できます。このメソッドは同期メソッドで、セッション情報が存在する場合、戻り値はsessionオブジェクトです。

var session = WL.getSession();
if (session) {
    alert("有効なセッション");
}

sessionオブジェクトの内容は、OAuthの仕様に関する内容です。詳細は割愛しますが、オブジェクトのプロパティは次の通りです。

sessionオブジェクトは、statusオブジェクトのsessionプロパティからも取得できます。

WL.getLoginStatus(function(r) {
    if (r.session) {
        alert("有効なセッション");
    }
});

イベント処理

あらかじめイベントに対応する関数を関連付けておくと、サインインやサインアウトしたときに、アプリに必要な処理が可能です。

イベントの関連付けには、WL.Event.subscribeメソッドを使います。subscribeメソッドの引数には、イベント名とイベントが発生したときに呼ばれるコールバック関数を指定します。

WL.Event.subscribe("auth.login", function() {
    alert("サインイン完了");
});

用意されているイベントは次の通りです。

アクセストークンは、OAuthの仕様に関する値で、ユーザーデータアクセスに必要な文字列です。auth.sessionChangeイベントは、ユーザーデータにアクセスできるようになった、または、できなくなったときに起こります。

関連付けの削除にはWL.Event.unsubscribeメソッドを使います。

WL.Event.unsubscribe("auth.login");

上記のコードの場合は、auth.loginイベントのすべての関連付けを削除します。特定の関連付けのみ削除する場合は、次のように第2引数に関数を指定して記述します。

// イベントの関連付け
WL.Event.subscribe("auth.login", onLogin);

// 関連付けの削除
WL.Event.unsubscribe("auth.login", onLogin);

function onLogin() {
    // (サインイン完了時の処理)
}

login・logoutメソッドでサインイン・サインアウト完了時の処理を指定した場合、auth.login・auth.logoutイベントは起こりません。

REST APIの呼び出し

REST APIを呼び出しには、apiメソッドを使います。REST APIは、ユーザーデータにアクセスするためのAPIで、ユーザー名などのリソースをURLで表し、HTTPメソッドでアクセスします。データのやりとりにはJSON形式を用います。apiメソッドを使用すると、短いコードでREST APIの利用が簡単に可能です。

指定できるプロパティは次の通りです。

ユーザーのSkyDriveのアルバムへのパスは、https://apis.live.net/v5.0/me/albums です。この場合、pathには「/me/albums」または「me/albums」と指定します。コード例は次のようになります。

WL.api({
    path: "/me/albums",
    method: "GET"
}, function (res) {                    
    if (res.error) {
        alert(res.error.message);
    } else {
        alert("Album count = " + res.data.length);
    }
});

第2引数には、REST APIのレスポンスを処理するコールバック関数を指定します。レスポンスの内容は、取得するデータによって異なります。上記コードでは、アルバムの数を表示しています。

REST APIの内容は、連載で順に紹介していく予定です。

SkyDriveのアルバム情報を参照するには、Scopeに「wl.photos」を指定する必要があります。

おわりに

最後に、今回のJavaScript APIを利用したSkyDriveのアルバム一覧を表示するサンプルを示します。実行するには、アプリ登録時に指定したドメイン上にWebページをアップロードしてアクセスする必要があります。

<html lang="ja">
    <head>
        <meta charset="utf-8" />
        <title>SkyDrive Albums</title>
        <script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.6.2.min.js"></script>
        <script src="https://js.live.net/v5.0/ja/wl.js"></script>
        <script>
            $(function(){

                function onLogin() {
                    var session = WL.getSession();
                    if (!session) {
                        return;
                    }

                    WL.api({path: "me/albums"}, function (r) {
                        $("#albums").html("");
                        if (r.error) {
                            alert(r.error.message);
                            return;
                        }

                        var list = r.data;
                        for (var i = 0; i < list.length; ++i) {
                            $("#albums").append('<li><a href="' + list[i].link + '">' + list[i].name + '</a></li>');
                        }
                    });

                }

                function onLogout() {
                    $("#albums").html("");
                }

                WL.Event.subscribe("auth.login", onLogin);
                WL.Event.subscribe("auth.logout", onLogout);

                WL.init({client_id: "*** Client ID ***"});
                WL.ui({
                    name: "signin",
                    element: "btn",
                    brand: "skydrive",
                    scope: ["wl.photos"]
                });

            });
        </script>
    </head>
    <body>
        <div id="btn"></div>
        <div>
            <ul id="albums"></ul>
        </div>
    </body>
</html>

実行結果は図4のようになります。ユーザーの許可を得ると、ユーザーのみ閲覧できるプライベートなアルバム情報も取得できていることがわかります。

• サンプルを実行する

今回は以上です。いかがでしたでしょうか。次回はJavaScript APIを活用したアプリ開発の予定です。