Uncategorized

yammer App の Programming

By on • ( Leave a comment )

Office 365 API
(※ 現在、統一エンドポイントとして Microsoft Graph がご利用いただけます)

(Skype API は こちら)

こんにちは。

今回は、yammer API がどのようなものかざっくり記載しておこうと思います。(Cross Domain 接続や Authentication など、どのような考え方で yammer API が提供されているか掴んでおいてください。)

この流れを理解しておけば、SharePoint の yammer App のようなカスタム アプリケーションへの yammer フィードの統合や、yammer と連携して動作するスマートフォン アプリケーションなど、さまざまな実装が可能です。

なお、以下では、yammer id を使用している場合と、Office 365 (Azure AD) の id を使用している場合の双方について解説します。(2015/06 追記)

 

App の登録と認証 (Authentication) – yammer id の場合

yammer API を使用する前に、まず、作成する App (Application) を yammer に登録します。はじめに、yammer basic など yammer id を使用しているケースについて解説します。

yammer  のアプリケーション (App) 管理ページ (https://www.yammer.com/client_applications) を表示します。(この際、yammer のログインが必要です。)

[App Directory] をクリックして、作成するアプリケーションの Redirect Url、アイコン イメージ なども設定し、[Deploy] ボタンを押します。

yammer にログインして、右上の […] – [App] を選択して表示される https://www.yammer.com/<your network>/apps を表示してみてください。Deploy をおこなうと、下図の通り、自分の Network (所属企業など) の範囲で App が公開されます。
(なお、デバッグだけなら Deploy は不要です。どうも、1 度作ったら消せないみたいなのでご注意を . . .)

注記 : つまり、皆さんのネットワーク (所属企業など) の全ユーザーが見れてしまいます。マナーとして、App をちゃんと構築してから公開するようにしましょう。

なお、Network 以外の yammer の一般ユーザーに公開する場合は、[App Directory] をクリックして下図の Global App Directory の [Submit for review] をクリックします。

作成すると、下図の通り、client id と client secret が作成されるのでメモしておいてください。

以上で Application の登録は完了です。

つぎに、Application (アプリケーション) を yammer と連携して動作させるために (yammer API を呼び出すために) 専用のトークンが必要です。
このため、まず、このトークンを取得する処理から構築しますが、ここでは、その HTTP フローを簡単に示します。(フローがわかれば、C#、PHP、Java など、お使いの言語で その流れを実装できます。JavaScript からアクセスする場合については後述します。)

まず、ブラウザー (Web アプリの場合) やブラウザー コンポーネント (ネイティブ アプリの場合) など使用して、最初に以下の URI にアクセスします。
client_id には上記でコピーした client id を、redirect_uri には App のリダイレクト先の URI を設定してください。(この URI は、上記で登録時に設定した URI、もしくは、そのサブディレクトリを指定します。)

GET https://www.yammer.com/dialog/oauth/?client_id=IFa9hU...&display=page&redirect_uri=https%3A%2F%2Fyammerapp01.azurewebsites.net&response_type=code

上記の URL にアクセスすると、yammer はブラウザーの Login チェックをおこなって、もしログイン済でないなら以下の Login 画面を表示します。

また、ユーザーがはじめてこの App を使用する際は、App への許可を与えるための下記の UI (Consent UI) が表示されます。
利用者がこの UI で許可してしまうと、この App は利用者の情報の参照や更新などが可能になります。このため、通常、利用者は、信頼できる App の場合のみ、[Allow] ボタンを押してアクセスを許可します。(今回は開発なので、とにかく押してください。)

なお、一度信頼された App は、下図の通り、自分の yammer の Profile (Profile – My Applications) に登録されます。あとで消すこと (Revoke) もできます。

認証 (ログイン) と App へのアクセス許可が完了すると、
上記の redirect_uri で指定した URI に Redirect されます。この際、下記の通り、code が付与されて戻ってきます。

GET https://yammerapp01.azurewebsites.net/?code=owqheQbmMp5...

補足 : 上記の Request で response_type=token とすると、以下のフォーマットで Access Token が返されます。
http://<redirect_uri>#access_token=<access_token&gt;
アンカー (#) が使用されている点からもおわかりの通り、この方式は、Client-Side の連携 (JavaScript からの動的連携など) で使用可能です。(HTTP の仕様において、アンカーの内容は、ネットワーク上を URI の一部として流れることはありません。)

つぎに、App は、上記で受け取った code を使用して以下の HTTP リクエストを投げます。
下記で client_id, client_secret は、上記の登録時にコピーしたものを設定してください。

GET https://www.yammer.com/oauth2/access_token.json?client_id=IFa9hU...&client_secret=2WUQV4...&code=owqheQbmMp5...

上記の HTTP Request により、以下の HTTP Response が返ってきます。
下記の token の箇所に Access Token が含まれています。(下のほうは、ログインしている User や、そのユーザーが属する Network の情報です。)

Content-Type: application/json; charset=utf-8ETag: "5eda28541978c4ed2c9d4791fd5ee792". . .{  "access_token":  {"user_id":119876,"network_id":107,"network_permalink":"microsoft.com","network_name":"Microsoft","token":"pfNNq. . .","view_members":true,"view_groups":true,"view_messages":true,"view_subscriptions":true,"modify_subscriptions":true,"modify_messages":true,"view_tags":true,"created_at":"2014/03/28 04:17:45 +0000","authorized_at":"2014/03/28 04:17:45 +0000","expires_at":null  },  "user":  {"type":"user","id":119876,"network_id":107,"state":"active","guid":"54162cb9-452b-49f2-af4a-093fc9d04a82","job_title":"Evangelist","location":"TOKYO-SHINAGAWA/25BFS",. . .  }}

なお、上記のフローは、AD FS 連携 (Active Directory 連携) を構成している場合でも何の問題もなく動作します。上記でログイン画面が表示されることを説明しましたが、AD FS とのフェデレーションを構成している場合は、そのログイン フローで AD FS が処理され、上記のフロー (code を付与したリダイレクト) に戻ってくるだけです。(つまり、プログラマーは、AD FS をいっさい意識する必要はありません。)

 

App の登録と認証 (Authentication) – Office 365 の場合

※ 本項は 2015/06 追記

Office 365 の yammer enterprise を使用している場合、Office 365 の Identity 基盤 (Azure Active Directory) を使った Sign-in が可能になりました。これにより、「Office 365 API 入門」で解説した方法でトークンの取得をおこない、yammer API を呼び出すことができます。(Application を Office 365 を使って認証し、yammer だけでなく、Exchange, SharePoint などのさまざまなサービスと連携させることができます。)
以降は、この方法を解説します。

この場合も、基本的な流れは、上記と同様です。(下記)

  1. Application の登録 (Registration)
  2. 認証と token の取得 (Authentication)

Office 365 で Application を登録するには、「Office 365 API 入門」で解説したように Azure Portal を使用します。Azure Portal で Azure AD (Azure Active Directory) の管理画面を表示して、Application を追加します。(下図)
なお、アプリケーションのプログラミングで使用するため、上記同様、追加した Application の Client Id と redirect uri をコピー (メモ) しておいてください。(Web Application の場合は、client secret (key) も作成して、その文字列をコピーしておきます。)

作成した Application の Configure (構成) 画面を表示し、下図の通り、この Application に対して [Office 365 Yammer] の Delegated Permission を設定します。

以上で Application の登録は完了です。
つぎに、下記の HTTP Flow で認証と token の取得をおこないます。(現実の開発では、Browser Component とプログラミング言語などを使用して下記のフローを実装してください。)

まず、ブラウザーを使って下記の URL にアクセスします。
下記で、client_id と redirect_uri は上記でコピーした内容を設定し、resource id は https://www.yammer.com/ を使用してください。(いずれも、URL Encode してください。)

https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=e4dfdaa2-fb86-406c-b154-ba488d3e83df&resource=https%3a%2f%2fwww.yammer.com%2f&redirect_uri=https%3a%2f%2fyammerapp01.azurewebsites.net%2f

アクセスすると、今回は、Office 365 の Sign-in 画面 (Azure Active Directory が出すログイン画面) が表示されます。
また、ログイン時、ユーザーがはじめてこの Application を使用すると、上記同様、Application への許可を与えるための UI (Consent UI) も表示されます。(見た目は上図と異なり、Azure AD 専用の Consent UI です。「Azure Active Directory の Common Consent Framework」を参照してください。)

上記で Office 365 の account / password を入力すると、下記の通り code を伴って (redirect_uri に) 戻ってきます。

https://yammerapp01.azurewebsites.net/?code=AAABAAAAiL...&session_state=...

取得した code を使用して下記の POST メソッドを投げます。

POST https://login.microsoftonline.com/common/oauth2/tokenContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=AAABAAAAiL...&client_id=e4dfdaa2-fb86-406c-b154-ba488d3e83df&redirect_uri=https%3A%2F%2Fyammerapp01.azurewebsites.net%2F

すると、下記の通り access token が HTTP Response の Body に返ってきます。
これで、token の取得は完了です。

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "expires_in": "3600",  "token_type": "Bearer",  "scope": "user_impersonation",  "expires_on": "1435730953",  "not_before": "1435727053",  "resource": "https://www.yammer.com/",  "access_token": "pfNNq. . .",  "refresh_token": "AAABA...",  "id_token": "eyJ0e..."}

 

REST API の呼び出し

Token が取得できたら、あとは下記の通り、この Token を Authorization ヘッダーに設定して REST API を呼び出すだけです。(yammer id を使用している場合も、Office 365 を使用している場合も、以降は同じフローです。)
例えば、下記は、Inbox でやり取りされた自分の Private Message の一覧を Json で取得します。(HTTP Response については省略します。)

GET https://www.yammer.com/api/v1/messages/private.jsonHost: www.yammer.comAuthorization: Bearer pfNNq. . .

REST API を使って、こうした参照だけでなく、登録も含め、さまざまな操作が可能です。(権限さえあれば、管理機能なども構築できます。)
また、Embbed によるフィードの表示なども可能ですので、SharePoint の yammer App のように、外部アプリケーションと yammer フィードを統合したカスタム アプリなども構築できます。

yammer の REST API については「yammer Developers : REST API」に記載されていますので是非参考にしてください。

 

yammer SDK と JavaScript と Cross Domain アクセス

上記の処理を yammer SDK を使用して処理することもできます。
SDK には、JavaScript、Ruby、Python が提供されているようですが、特に JavaScript で構築する場合は、「Cross Domain 接続が容易になる」という恩恵も受けることができます。(サーバー サイドの場合と異なり、JavaScript を使ってフロントエンドでプログラミングする場合は、yammer SDK が必須と考えて良いでしょう。)

まず、yammer SDK を使った下記のサンプル コード (Web アプリのサンプル) を見てください。この App を、いったんブラウザーで yammer にログインした後で表示すると、ちゃんと動作します。
ご覧の通り、コードの中にはログイン処理らしきもの (Access Token の取得フローなど) はまったく記述されていません。

<!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 type="text/javascript"  data-app-id="<your app client id>"  src="https://assets.yammer.com/platform/yam.js">  </script></head><body>  <button onclick="getinbox();">get private messages !</button>  <script>function getinbox() {  yam.request({url: "https://www.yammer.com/api/v1/messages/private.json",method: "GET",success: function (msg) {  alert('message count is ' + msg.messages.length);  for (var i = 0; i < msg.messages.length; i++) {alert(msg.messages[i].body.plain);  }},error: function (err) {  alert("error !");}  });  }  </script></body></html>

しかし、ブラウザーを開きなおして、今度は yammer にログインせずに上記を実行すると error になります。

もう勘の良い方はお分かりかと思いますが、JavaScript の yammer SDK では、「JSONP などクロス ドメイン (Cross-Domain) 問題の回避と諸注意」で解説した XDM (Cross Document Messaging) の方式を使って Cross-Domain Request (xdr) の問題を回避しています。(即ち、iframe を使用した方式です。)
試しに、IE の F12 開発ツールなどで見ていただくと、以下の通り iframe が挿入されているのがわかります。

注意 : yam.js と platform_js_sdk.js について
上記のサンプル コードでは https://assets.yammer.com/platform/yam.js のライブラリーを使用していますが、yammer Developer で紹介されている https://assets.yammer.com/assets/platform_js_sdk.js を使用している場合はアクセス方法が異なるので注意してください。platform_js_sdk.js の場合は、「JSONP などクロス ドメイン (Cross-Domain) 問題の回避と諸注意」で紹介した CORS (Cross-Origin Resource Sharing) が使用されています。この場合は、下図の通り、yammer App の管理画面の [Javascript Origins] に、あらかじめアクセス可能なドメインを設定しておき、yam.platform.setAuthToken で取得した Access Token を設定し、yam.platform.request で REST API を処理します。

もし、yammer にログインせずにアクセスされる可能性のある App の場合は、下記太字のような yammer のログイン ボタンを配置して、このボタンでログインをおこなうことも可能です。(下記の場合、ログインしていれば「Welcome to Yammer!」と表示され、ログインしていなければ下図のような yammer のログイン ボタンが表示されます。)

<!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 type="text/javascript"  data-app-id="<your app client id>"  src="https://assets.yammer.com/platform/yam.js">  </script></head><body>  <span id="yammer-login"></span>  <button onclick="getinbox();">get private messages !</button>  <script>yam.connect.loginButton('#yammer-login', function (resp) {  if (resp.authResponse) {document.getElementById('yammer-login').innerHTML  = 'Welcome to Yammer!';alert('Access token is ' + resp.access_token.token);  }});function getinbox() {  yam.request({url: "https://www.yammer.com/api/v1/messages/private.json",method: "GET",success: function (msg) {  alert('message count is ' + msg.messages.length);  for (var i = 0; i < msg.messages.length; i++) {alert(msg.messages[i].body.plain);  }},error: function (err) {  alert("error !");}  });  }  </script></body></html>

補足 : yam.login について
この他に、yam.login を使用してボタンを表示せずにログイン フローを処理することもできますが、
この API は Window Popup を使用するため、必ず UI 操作の中などで使用してください。(UI なしで処理すると、ちゃんとしたブラウザーの場合、ブロックされるはずです。)

 

※ 変更履歴 :

2015/06/30 Office 365 の yammer enterprise を使用している場合の token の取得方法を追加

 

Categories: Uncategorized

Tagged as:

Leave a Reply