こんにちは。

Office 365 Connector のコンセプトや開発手法を簡単に紹介します。(ISV の方は、独自の Connector を Store に Publish できます。)

Office 365 Group について (事前説明)

追記 : Office 365 Connector は、(Office 365 Group Inbox だけでなく) Outlook の個人の Inbox, Microsoft Teams でも使用可能になりました。

現在 (2016/05)、Office 365 Connector は Office 365 Group にのみ使用できます。まず、Office 365 Connector の開発手法や動きを見る前に、Office 365 Group について紹介します。

ご存知の方も多いと思いますが、Office 365 には、Office 365 Group というグループ機能が使えます。
高齢化の進む日本 (私も含め) ではちょっとイメージしづらいかもしれませんが、インフォメーション ワーカーの世界では、US を中心に Millennial (ミレニアル) 世代と呼ばれる新しい若者層を中心としたワークスタイルが注目されており、階層化され硬直化された組織ではなく、ネットを活用することで、ある目的をもったアドホックかつ柔軟なチームを形成し適宜成果をコミットするようなワークスタイルで、IT のコモディティー化と社会の迅速な変化 (加速度的な変化) による必然的な流れと考えられています。(実際、いくつかの既存産業 (自動車等) でも、こうした自由で柔軟な発想を強みとして変化に対応できる若い会社が存在感を表してきています。企業寿命もますます短くなり、まだ先かもしれませんが、いつか「企業」という形そのものも問われてくるかもしれません。)
Office 365 Group は、こうした新しいワークスタイルを意識して (かなり前ですが) 登場した機能です。(下図は、1 年前の Ignite フィードバック説明会で使ったイメージです。。。)

(From: Microsoft Ignite 2015)

Office 365 Group の内部実装は Azure AD Group が使われていますが、Group のファイル共有領域、Group 共通の予定表、Group 共通のノートなど、Office 365 のさまざまな Group 専用機能が提供されていて、上述のようなワークスタイルを支えます。(これらの機能は、固定的な Group ではなく、よりアドホックな Group をイメージして提供されています。)

こうした Group 機能の 1 つとして、Group 内の会話 (スレッド) を管理できる Group 専用の Inbox があります。ここで紹介する Office 365 Connectors は、この Group Inbox と連携して動作します。
Office 365 Connector の Catalog から Built-in Connector を選択して、Trello, Github, BitBucket 等々の Light な生産性ツールを Office 365 をハブとして組み合わせることで、Outlook 以外のこうしたツールも組み合わせてメンバーどうしのコミュニケーションを橋渡しできます。

例えば、twitter の Connector に接続すると、特定のアカウントの特定のハッシュ タグなどへのツイートが、下図のように Office 365 Group の Thread (Inbox) に Card として表示され、この Card のボタンをクリックすると元の tweet 内容が閲覧できます。(今回は twitter のサンプルですが、対象の Application が Salesforce などのように Office 365 とシングル・サインオンを構成できる場合は、そのまま Application の情報がシームレスに表示されることになります。)

構築手順と処理の流れ

Dashboard への登録

Office 365 Connector は、Sandbox を使った簡単な動作確認、Incoming Webhook (着信 Web フック) による簡易イベント送信、Developer Portal を使った本格的な開発など、構築と確認のためのいくつかのユーティリティが提供されていて、すぐに試すことができます。

今回は、Office 365 Connector を開発する ISV 企業のために、Developer Portal (Dashboard) を使った方法で解説します。

まず、Office 365 アカウントでログインして、Connector Developer Portal (Dashboard) を表示してください。

上図の [New Connector] をクリックすると、新規に作成する Connector の情報が入力できるので、ここに必要事項を入力して Save します。
名前 (Connector Name)、ロゴ アイコン (Logo)、どんなイベントが送信されるか (List the events supported by your connector) などの基本情報以外に、後述の [Connect to Office 365] ボタンを押した際に飛ぶ Redirect Url も入力します。(開発時は、この値として localhost などを設定しても構いません。)

Landing Page と Connect Button

Connector のストア登録後、利用者がこの Connector を追加する際には、上図の [Landing Page for your users] (上図参照) に設定した Url が、下図のようにリンクとして表示されます。
例えば、Office 365 Connector に接続するために、ある Application への SignUp や SignIn が事前に必要な場合や、上記の twitter の場合のように「どのハッシュ タグを対象とするか」などの追加の設定が必要な場合があります。こうした場合には、この Landing Page でこれらを誘導 (ガイド) して、後述する [Connect to Office 365] ボタンを適切な場所に配置しておきます。
(以降の手順では、ストアへの発行はおこなわず、単純に、この Landing Page にボタンを配置して動作を確認します。)

Connector の新規登録をおこなうと、下図の通り、[Connect to Office 365] ボタンのスニペットが生成されます。このボタンは、皆さんの Application 内の適切な場所に配置しておきます。
なお、この URL (下図の https://outlook.office.com/connectors/Connect?state=myAppsState&app_id=4b560...&callback_url=https://mydeploy.azurewebsites.net/callback_test.php) の app_id は登録したアプリ固有の Id で、自動採番されます。また、callback_url は、上述で設定した Redirect Url です。state に設定した値は、Redirect Url の Query Parameter としてそのまま渡されるため、上述の個別の設定内容 (利用者が設定した内容) を渡したい場合や、状態によって処理を振り分けたい場合などには、この state に、適宜、値を設定します。(下図の通り、この初期値には、「myAppsState」というダミーの値が設定されていますので、適宜変更してください。)

動作を確認するため、今回は単純に、Landing Page (皆さんが提供する Application) に このボタンを配置してみましょう。(下図)

なお、この Connect Button は、Office 365 上から Connector を追加する場合だけでなく、ISV 企業のアプリケーション内の自由な場所に配置して構いません。
例えば、ISV が構築するタスク管理のアプリで、タスクを新規作成したタイミングで このボタンを表示して、このタスクをどの Inbox (Office 365 の Inbox) と連携するか新規作成時に毎回選ばせるようにしても良いでしょう。

Connector の追加

Office 365 Connector のインフラそのものは、Azure AD に既に登録済の (Microsoft があらかじめ登録した) マルチテナント アプリです。(Azure AD のアプリ開発については「Azure AD を使った API (Service) 連携の Client 開発 (OAuth 2.0 紹介)」を参照。)
このため、上図のボタンを押すと、まず Office 365 のログイン画面が表示されます。利用者はこのログイン画面で、この Connector が接続する Office 365 テナントにログインします。(既に Office 365 にログイン済の場合にはシングル・サインオンされます。)

ログインに成功すると、Office 365 Connector は、下図の通り、どの Inbox (Group Inbox) に このカスタムの Connector をアタッチするか選択する画面を表示します。この画面で、対象の Inbox を選択します。

Office 365 の Webhook 呼び出し

Group を選択して先に進むと、事前に設定しておいた Application の Redirect Url (上述の Connector Developer Portal で設定した Url) に、下記の通り query parameter が付与されて飛んできます。

https://{application redirect url}  ?state=myAppsState  &webhook_url=https%3A%2F%2Foutlook.office365.com%2Fwebhook%2F711aa...%403c839...%2F4b560...%2Fb766149197db4f0290881571a8cae74c%2Fcf258...  &group_name=planning%20v-team

補足 : Connector に接続すると、Office 365 Group の Thread (Inbox) に下図の通り通知されます。

補足 : 何らかの理由で Error が発生した場合は、https://{application redirect url}?error={error code} の形式で Redirect されます。

以降、Application では、この受け取った webhook_url に対して Json 形式でイベントを POST することで、Office 365 の Inbox (Group Inbox) にイベントを通知できます。

Card の表現

この Json の内容については「Office 365 Connectors API Reference」にまとめられていますので、是非参考にしてください。
下記に、HTTP Request と Card のサンプルをいくつか列挙します。

POST https://outlook.office365.com/webhook/711aa...@3c839.../4b560.../b766149197db4f0290881571a8cae74c/cf258...Content-Type: application/json{  "text": "Remember to get milk at the store!"  }

POST https://outlook.office365.com/webhook/711aa...@3c839.../4b560.../b766149197db4f0290881571a8cae74c/cf258...Content-Type: application/json{  "text": "Remember to get milk at the store!",  "title": "Today:"}

POST https://outlook.office365.com/webhook/711aa...@3c839.../4b560.../b766149197db4f0290881571a8cae74c/cf258...Content-Type: application/json{  "text": "Remember to [get milk at the store!](http://contoso.com/item/001/)",  "title": "Today:"}

POST https://outlook.office365.com/webhook/711aa...@3c839.../4b560.../b766149197db4f0290881571a8cae74c/cf258...Content-Type: application/json{  "text": " Remember to [get milk at the store!](http://contoso.com/item/001/)",  "title": "Today:",  "potentialAction": [{  "@context": "http://schema.org",  "@type": "ViewAction",  "name": "View in Test Connector",  "target": ["https://contoso.com/item/001/overview"]}  ]}

この他に、イメージの添付など、もっと複雑な Canvas の送信も可能です。(詳細は「Office 365 Connectors API Reference」を参照してください。)

Connector の Publish

Connector が完成したら、さいごに、Connector Developer Portal (Dashboard) から Store に Publish します。
審査に Pass すると、Connector は Built-in Connector として Office 365 の利用者から選択可能になります。(既に、いくつかの 3rd party 製の Connector が登録されていますので、参考にしてみてください。)