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

第43回JavaScriptでWindows Live統合アプリの開発

はじめに

前回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.init JavaScript APIの初期化
WL.login サインイン処理
WL.logout サインアウト処理
WL.getLoginStatus サインイン状態の取得
WL.getSession ユーザーのセッション情報の取得
WL.Event.subscribe イベントハンドラーの登録
WL.Event.unsubscribe イベントハンドラーの削除
WL.api REST APIの呼び出し
WL.ui UIの描画

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

status サインイン状態を示す値と、下記のsessionオブジェクトを持っています。
session 現在のセッション情報
OAuthのアクセストークンや認証トークン、Scopeなどの値を持っています。
APIレスポンス REST APIのレスポンス結果のJSONオブジェクト
構成はデータにより異なります。

以上のように、現在の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も指定します。

名前 説明
client_id アプリのClient ID(指定必須)
redirect_uri サインイン後に移動するURL。指定しない場合はサインインボタンをクリックしたページです。
logging trueを指定した場合、エラーなどのログをブラウザーのコンソールに出力します。規定値はtrue
status trueを指定した場合、Windows Liveからサインイン状態を取得します。自動サインイン機能に使用します。規定値はtrue
response_type codeまたはtokenを指定。OAuthの仕様に関する部分で今回は割愛します。規定値はtoken

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

図1 ログの表示
図1 ログの表示

サインインコントロール

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

図2 サインインコントロール
図2 サインインコントロール

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

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

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

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

名前 説明
name 描画するUIの種類
現在は、signinのみサポート
element UIを描画するDOM要素名

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

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

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

名前 説明
brand アイコンの種類
messenger, hotmail, windowslive, skydriveのいずれか
redirect_uri サインイン後に移動するページのURL
scope アプリが要求する許可(Scope)を示す文字列
type ボタンのテキストの種類
signin、login、connect、customのいずれか
sign_in_text サインアウト状態のときのテキスト
typeがcustomのとき有効
sign_out_text サインイン状態の時のテキスト
typeがcustomのとき有効

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のようになります。

図3 サインインコントロールのカスタマイズ
図3 サインインコントロールのカスタマイズ

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

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

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メソッドの第2引数にtrueを指定した場合、Windows Liveサービスに毎回接続し状態を取得します。

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

セッション情報の取得

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

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

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

名前 説明
access_token アクセストークン
authentication_token 認証トークン
scope Scopeの配列
expires_in アクセストークンが有効な残り時間(秒数)
expires セッションの有効期限(1970/1/1からの秒数)

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

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

イベント処理

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

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

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

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

イベント名 イベントの発生するタイミング
auth.login サインイン処理の完了時
auth.logout サインアウト処理の完了時
auth.sessionChange アクセストークンが変わったとき
auth.statusChange サインイン状態が変わったとき
wl.log エラー発生時

アクセストークンは、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の利用が簡単に可能です。

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

名前 説明
path ユーザーデータへのパス(必須)
method HTTPメソッド
GET(規定値)またはPOST
body POSTメソッド使用の場合
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のようになります。ユーザーの許可を得ると、ユーザーのみ閲覧できるプライベートなアルバム情報も取得できていることがわかります。

図4 サンプルの実行
図4 サンプルの実行

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

おすすめ記事

記事・ニュース一覧