Live Services (Outlook.com, OneDrive, etc) 開発


2015/10 追記 : 今後、商用向け (Commercial) の Office 365 (Azure AD のアイデンティティ) と一般向け (Consumer) の Office 365 (Microsoft Account のアイデンティティ) の Idenity Endpoint と REST Endpoint が統一される予定です。詳細は「Office 365 API の Commercial & Consumer の Unified 開発」を参照してください。

こんにちは。

以下に、Live Services 開発 (Outlook.com, OneDrive などの開発) についてまとめておきます。

なお、かなり昔 (数年前) に「Office & Office 365 Development Sample」にサンプル プログラムをアップしましたので、そちらもご参照ください。(この中のサンプル「SharePoint Online へのファイル保存」で OneDrive への保存も実装しています。一部、古い API を使ってましたので、本日、修正版のコードを push しておきました。。。)

今回、改めて流れを解説しておきます。

ここでは、おおまかな概念を紹介しますので、API Reference などの詳細は「MSDN : Windows Live Services」を参照してください。

 

Live Services と Office 365

Live Services では、サービスとして、Outlook.com (旧 Hotmail)、連絡先リスト (People)、Calendar、OneDrive (旧 SkyDrive)、および関連する Office Online (OneNote Online 含む) を対象としています。
Microsoft には他にも似たようなサービスのラインアップがありましたね。そうです、本日解説した Office 365 です。

Office 365 が Enterprise (Business) 利用を想定しているのに対し、Live Services は Consumer 利用を想定しており、SLA なども異なっています。
開発者にとって重要な点は、Identity 基盤として、Office 365 では Azure Active Directory (Azure AD) を使用しているのに対し、Live Services は Microsoft Account (MSA) を使用している点です。
接続先のエンドポイントはもちろん異なりますし、Windows Live Services には「管理者」という概念もないので、例えば、Azure AD におけるユーザー管理用の API なども提供されていません。(ユーザーの Bulk 作成も不可能です。)

しかし、基本概念は本日紹介した OAuth 2.0 をベースとしているので、Office 365 はもちろん、Facebook、Twitter、Google、LinkedIn など昨今のインターネット サービスの開発を一度でも扱ったことがある方なら、容易に受け入れられるでしょう。
以下に手順を記載しますが、以前このブログで紹介した「Office 365 API 入門」と ほぼ同様の流れです。

補足 (2015/10 追記) : OneDrive など Consumer サービス (一般向けサービス) の有償版として、Office 365 Home (日本では Office 365 Solo) が提供されています。(現在、Office 365 ブランドとして統一されています。)

 

Register your application

では、以下に基本的なフローを紹介します。

まず、OAuth 2.0 を使った認証フローを実装する前に、Application を Live Services に登録します。
Microsoft Account で Application Registration Portal (https://apps.dev.microsoft.com/) にログインし、[アプリケーションの作成] リンクをクリックして登録します。

Application 登録の際、必ず [Live SDK support] にチェックを付けておいてください

また、下図の [Redirect URL] にこのアプリケーションの URL を設定してください。(受け取ったトークンを処理する URL です。) OAuth のフローでログイン直後に戻る URL になります。
なお、Azure AD と異なり localhost は指定できないようなので、Debug をおこなう際には工夫が必要です。このようなときこそ、Microsoft Azure Web Sites を “開発環境” として使うと便利ですね。(Remote Debug が簡単におこなえます。)

登録が完了したら、作成された Client ID と Client Secret の値をメモ帳などにコピーしておきます。(下図)

 

HTTP Flow – Authentication (認証)

では、HTTP Flow を見てみましょう。OAuth 2.0 で認証をおこない、OneDrive のフォルダー一覧を取得するサンプルを紹介します。

まず、Web Browser (Mobile アプリの場合は、Browser Component など) を使って以下の URL にアクセスします。
下記で client_id と redirect_uri には、上記の値を設定します。
また、処理の内容に応じ、下記の scope を設定します。今回は、ログインをおこなって OneDrive の情報の読み込むため、下記の通り、wl.signin と wl.skydrive を「wl.signin wl.skydrive」のように空白 (Space) で区切って指定します。(指定可能な scope については、「MSDN : Windows Live Services – Scopes and permissions」を参照してください。)

GET https://login.live.com/oauth20_authorize.srf?response_type=code&client_id=<client id>&scope=wl.signin%20wl.skydrive&redirect_uri=<redirect uri>

この Url にアクセスすると、Web Browser (Browser Component) は、下図のような SignIn 画面を表示するので、Microsoft Account でログインします。
Azure AD 同様、Microsoft Account で二要素認証 (多要素認証) を使っている場合などでも、必要な処理はすべて Browser がおこなってくれるので、開発者は、こうした応用的なインフラ構成に対しても特別な処理 (追加の処理) を実装する必要はありません。

なお、ユーザーがはじめて この Appication を使用する場合、下図のような Consent UI が表示されます。
ここでは、このアプリケーション (LiveDemoApp01) に OneDrive の情報を参照する権限 (アクセス許可) の付与を求めており、一度、[はい] (Yes) をクリックすると、以降、この Consent UI は表示されません。

補足 : このアクセス許可は、Microsoft Account の管理画面 (Consent 管理)で削除できます。(あとでこのアプリが信用できなくなった場合は、利用者自身が、この画面で削除できます。この辺りも、Google Account, Facebook など他と同様です。)

認証に成功すると、Browser は下記の Url にリダイレクトします。auth code には、認証結果としての Authorization code (auth code) が入っています。

<redirect uri>?code=<auth code>

例えば、以下のような Url です。

https://tsmatsuz-test1.azurewebsites.net/?code=f8244459-53...

つぎに、上記で取得した auth code を使って、下記の POST 要求 (Request) を出します。

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<auth code>&client_id=<client id>&client_secret=<client secret>&redirect_uri=<redirect uri>

この POST 要求の結果として、下記の Json フォーマットの Response Body が返ってきます。
下記の通り、access token と呼ばれるものが取得できています。

{
  "access_token": "EwAwAq1DBAAUGCCXc8w...",
  "authentication_token": "eyJhbGciOiJIUzI1NiI...",
  "expires_in": 3600,
  "scope": "wl.signin wl.skydrive",
  "token_type": "bearer"
}

なお、scope として wl.offline_access を指定すると、下記の通り refresh token と呼ばれるものが取得できます。
refresh token は、access token が期限切れになった場合の取り直しなどで必要になります。(既定では 1 時間で期限切れになります。) Mobile Application などでは、この wl.offline_access も設定しておくと良いでしょう。

{
  "access_token": "EwA4Aq1DBAAUGCCXc8w...",
  "authentication_token": "eyJhbGciOiJIUzI1NiI...",
  "expires_in": 3600,
  "refresh_token": "tzUSQAAAHgA%241R4eG...",
  "scope": "wl.offline_access wl.signin wl.skydrive",
  "token_type": "bearer"
}

 

HTTP Flow – Service 呼び出し

2015/10 追記 : 今後、OneDrive, Outlook.com, Skype などの一般向け (Consumer 向け) 開発では、商用版の Office 365 との共通化がおこなわれます。(既に OneDrive, Outlook では、共通の REST API が正式提供されています。) 詳細は、「Office 365 API 開発 – OneDirve API」、「Office 365 API 開発 – Outlook REST API」を参照してください。(下記は、古い REST API です。)

あとは、取得した token を使って、必要なサービスを呼び出します。
今回は、OneDrive の (root の) Folder 一覧を取得するため、以下の通り GET 要求 (Request) を出します。

GET https://apis.live.net/v5.0/me/skydrive/files?access_token=EwA4Aq1DBAAUGCCXc8w...

上記の結果として、OneDrive の REST サービスは、以下のような Json フォーマットの Body を返します。

{
  "data":
  [
    {
      "id": "folder.9c0af81b735e29ea.9C0AF81B735E29EA!2386", 
      "from":
      {
        "name": "Tsuyoshi Matsuzaki", 
        "id": "9c0af81b735e29ea"
      }, 
      "name": "Test Folder 1",
      "description": "", 
      "parent_id": "folder.9c0af81b735e29ea", 
      "size": 63701264, 
      "upload_location": "https://apis.live.net/v5.0/folder.9c0af81b735e29ea.9C0AF81B735E29EA!2386/files/", 
      . . .

    },
    {
      "id": "folder.9c0af81b735e29ea.9C0AF81B735E29EA!4010", 
      "from": {
        "name": "Tsuyoshi Matsuzaki", 
        "id": "9c0af81b735e29ea"
      }, 
      "name": "Test Folder 2", 
      "description": "", 
      "parent_id": "folder.9c0af81b735e29ea", 
      "size": 4489499, 
      "upload_location": "https://apis.live.net/v5.0/folder.9c0af81b735e29ea.9C0AF81B735E29EA!4010/files/", 
      . . .

    },
    . . .

  ]
}

OneDrive にファイルをアップロードする場合には、scope に wl.skydrive_update を設定し、POST メソッドで登録します。
OneDrive API (REST) の詳細については「MSDN : OneDrive API」を参照してください。

補足 : 実は、Live Services では、他に、下記の OAuth Endpoint も使えます。ただし、下記の Endpoint では、後述する wl.imap など、一部の新しい scope には対応していないので注意してください。(古い Endpoint です。)

https://oauth.live.com/authorize

https://oauth.live.com/token

なお、下記の通り response_type=token とすることで、URI Fragment の一部として access token を返す Implicit Grant Flow にも対応できます。(例えば、https://tsmatsuz-test1.azurewebsites.net/#access_token=EwB4Aq1D…&authentication_token=eyJhbGci…&token_type=bearer&expires_in=3600&scope=wl.signin%20wl.offline_access&user_id=6b58b4a… などのフォーマットで戻されます。)
JavaScript からのアクセスなどに向いています。

https://login.live.com/oauth20_authorize.srf?response_type=token&client_id=<client id>&scope=<scopes>&redirect_uri=<redirect uri>

 

Live Services API で可能なこと

上記では OneDrive の読み込みをおこないましたが、「MSDN : Windows Live Services」に記載されている通り、以下のような処理が可能です。(2014/06 月現在)

  • Profile 情報との連携
  • OneDrive への読み書き (Document, Photo, Video など含む)
  • Outlook.com を使用したメールの送受信や Sync
  • Calendar (カレンダー) との連携
  • Contacts (連絡先) リストへの読み書き
  • OneNote Service API の使用

なお、Outlook.com (旧 Hotmail) では、SMTP (server: smtp-mail.outlook.com)、ActiveSync (server: s.outlook.com) に加え、昨年 (2013 年) 秋に OAuth 2.0 サポートと IMAP (server: imap-mail.outlook.com) にも対応しました。
IMAP なので、メール受信の通知なども実装できます。

補足 : Outlook.com の設定で POP も有効 (Enable) にできます。(既定では、POP は Disable になっています。)

例えば、下記のプログラムは、上記の Flow で取得した Access Token を使って、Mail を送信する Node.js のプログラムです。(このプログラムを outlook_oauth2_test.js と仮定します。)
Node.js パッケージの nodemailer を使っています。
(ただし、Access token を取得する際、scope に wl.imap を指定する必要があります。)

var nodemailer = require("nodemailer");

var trans = nodemailer.createTransport("SMTP", {
  host: 'smtp-mail.outlook.com',
  port: 587,
  ssl: false,
  use_authentication: true,
  auth: {
    XOAuth2: {
      user: "tsuyoshi.matsuzaki@hotmail.com",
      clientId: "00000000401235B7",
      clientSecret: "2ZDjDbVgm0wm20...",
      accessToken: "EwB4Aq1DBAAUGC..."
    }
  }
});

var options = {
  from: "tsuyoshi.matsuzaki@hotmail.com",
  to: "naoki0311@gmail.com",
  subject: "Are you busy ?",
  generateTextFromHTML: true,
  html: "<b>Are you busy ?</b>"
};

trans.sendMail(options, function(err, res) {
  if (err) {
    console.log(err);
  } else {
    console.log(res);
  }
  trans.close();
});

以下のコマンドで nodemailer をインストールして、上記プログラム (outlook_oauth2_test.js) を実行すると、OAuth 2.0 と SMTP による Outlook.com からの Mail 送信がおこなわれます。

npm install nodemailer
node outlook_oauth2_test.js

C# (.NET) の場合、.NET 標準の System.Net.Mail.SmtpClient は OAuth に対応していないため、NuGet から取得可能な Mail.dll などを使用すると良いでしょう。(コードは省略します。)

 

Live SDK

上記では Live Services 開発の HTTP Flow を紹介しましたが、こうした処理を API 化した Live SDK が提供されています。
この SDK は、以下で使用可能です。

  • Windows store app の Managed Code (.NET)
  • Windows phone app の Managed Code (.NET)
  • Windows store app の JavaScript (JavaScript)
  • Web アプリ (JavaScript)
  • iOS
  • Android

例えば、下記は、[Login] ボタンを押すと Microsoft Account の SignIn 画面を表示してログインをおこない、[Get Folders] ボタンを押すと OneDrive からフォルダー一覧を取得する Web Application のサンプルです。

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title></title>
  <script src="http://blogs.msdn.com//ajax.aspnetcdn.com/ajax/jquery/jquery-1.9.0.min.js"></script>
  <script src="http://blogs.msdn.com//js.live.net/v5.0/wl.debug.js"></script>
  <script>
    $(document).ready(function () {
      WL.Event.subscribe('auth.login', function () {
        // change to enabled !
        $('#foldersBtn').removeAttr('disabled');
      });
      WL.init({
        client_id: '00000000401235B7′,
        redirect_uri: 'https://tsmatsuz-test1.azurewebsites.net/',
        response_type: 'token'
      });
      $('#loginBtn').click(function () {
        WL.login({ scope: 'wl.signin wl.skydrive' }).then(
          function (res) {
            // some post login processes...
          },
          function (res) {
            alert('error occured !');
          });
      });
      $('#foldersBtn').click(function () {
        WL.api({
          path: 'me/skydrive/files',
          method: 'GET'
        }, function (res) {
          if (res.error) {
            alert(res.error.message);
          } else {
            $.each(res.data, function (i, val) {
              alert(val.name);
            });
          }
        });
      });
    });
  </script>
</head>
<body>
  <button id="loginBtn">Login</button>
  <button id="foldersBtn" disabled>Get Folders</button>
</body>
</html>

以下の通り、内部の Access token も取得できます。

WL.getLoginStatus(function (status) {
  var access_token = status.session.access_token;
  alert(access_token);
});

実は、この Live SDK、内部では複雑なことをやっています。
例えば、上記の Web Application 用の Live SDK では、別の Window (Web Browser) を Popup してログイン (SignIn) 画面を表示し、上記の Implicit Grant Flow により access token を取得して、返された access token を呼び出し元の Window (親 Window) に渡して Popup 画面を閉じます。
OneDrive API の呼び出しでは、JSONP を使って access token を受け渡すことで Cross-Domain 呼び出しの問題を回避しています。(Cross-Domain 呼び出しの考え方については、「クロス ドメイン (Cross-Domain) 問題の回避と諸注意」を参照してください。)

これら一連の流れは、すべて Live SDK のライブラリー自身が内部で処理しているので、開発者 (API 利用者) は、こうした複雑な Flow を意識する必要はありません。

 

※ 修正記録

2016/04/21  Live Connect Developer Site (https://account.live.com/developers/applications/) から Application Registration Portal (https://apps.dev.microsoft.com/) に変更


Comments (0)

Skip to main content