Office 365 API はじめの一歩

こんにちは SharePoint サポートの森　健吾 (kenmori) です。

今回の投稿は、Office 365 API 入門です。これまで全く触ったことがない人は、是非ご参考にしていただけますと幸いです。

Office 365 API とは

Office 365 API は、これまで存在していた SharePoint や Exchangeが製品として、これまで提供してきた API とは異なる、別の新しい Office 365 として提供された API のセットです。

カスタムのクライアント アプリケーション (ネイティブ アプリケーション)、Web アプリケーション、携帯アプリなどから、Office 365 のサービスや機能を外部から使用するために適した API 群です。Office 365 にログインしたユーザーに紐づく OneDrive for Business 上のファイル、メール、連絡先、予定表などにアクセスができます。従来の API (CSOM や Web サービス) のように、テナントごとの接続先エンド ポイントを意識する必要がありません。

オンプレミスで SharePoint 内部に組み込めるファーム ソリューションや、サイトに対しコンテキスト ベースで SharePoint オンプレミス/Online 双方にアドインを組み込める SharePoint アプリとは特性が異なります。何かの形式を使用することを特別に推奨するわけではございませんので、実装するソリューションに適した形式のものを選択いただくことをお勧めします。

Office 365 API は、実現できるソリューション実装の幅を広げるために、様々な API が展開されております。これにより、既存の API やカスタマイズ手法が非推奨になるということもありませんので、Office 365 API にこだわらず、実装するソリューションに合わせて最適なカスタマイズ手法を選択いただければと思います。

タイトル : Office 365 APIs platform overview
アドレス : https://msdn.microsoft.com/en-us/office/office365/howto/platform-development-overview

Office 365 API をどのようにはじめるか？

Office 365 API という言葉をよく聞くけれど、何やら難しそうで、どこから始めたらいいかわからないという言葉をよく聞きます。私からのお勧めは、まず dev.office.com にあるサンプルを動作させることです。

このサイトに保管されているサンプルは最小構成のものが多いです。しかし、着手してみたものの、想像しているより巨大なプロジェクトであり、もっと小さなサンプルがあるのではないのかと疑う方もいらっしゃるかもしれません。

プロジェクトが大きな理由は Office 365 API が、Office 365 アプリ認証を必須としている点にあります。アプリ認証はシングル サインオンが前提のため、カスタム アプリケーションと Office 365 で認証されたユーザーを同一にする必要があります。そのため、カスタム アプリケーション側にも Office 365 や Azure AD などと連携するためにどうしても Open ID などの認証基盤を組み込む必要があり、最小構成のコードが大きくなります。慣れてしまえば大きな問題ではありません。

多くのプログラマーは、とりあえず手元でデバッグ実行し、コードが動く状況をつかめれば、イメージが湧くという人が多いのではないでしょうか。REST API を内部実行する API であるため Fiddler で採取した HTTP トレースを眺めていても、概要イメージがどんどんつかめて来るでしょう。

今回の投稿は、とりあえず動かすための手順を記載するために絞り、手元で動かしてみて理解する人のための投稿となります。

準備事項 1. Visual Studio 2013 + Update 4 以降

準備事項 2. Azure Portal に Office 365 ドメインを追加する

実践編 : 実際にコードを動かす

準備事項 1. Visual Studio 2013 + Update 4 以降

Office 365 API を使用するための前提というわけではありませんが、Azure Portal を開かずとも Visual Studio 上でアプリの登録や、アクセス許可の設定などが実施できるため、生産性が大きく違います。
これから始める方は Visual Studio 2013 に最新の Update を適用しましょう。

タイトル : Description of Visual Studio 2013 Update 4
アドレス : https://support.microsoft.com/en-us/kb/2994375

準備事項 2. Azure Portal に Office 365 ドメインを追加する

Office 365 は、内部的に Azure AD を使用しています。そのため、Office 365 ドメインを Azure Portal に登録することで、同じ基盤で動作する Office 365 ドメインを Azure Portal 上で管理することができるようになります。

1. Azure ポータルにログインします。
2. [+新規] - [APP SERVICES] - [Active Directory] - [ディレクトリ] -[カスタム作成] をクリックします。

3. ディレクトリの追加画面にて、"既存のディレクトリの使用" を選択し、"サインアウトする準備ができました。" にチェックを入れ、右下の完了ボタン (チェック アイコン) をクリックします。

4. Office 365 のログイン情報を入力して、ログインします。

5. Office 365 ドメインを Azure に追加するために [Continue] をクリックします。

6. [Sign out now] をクリックして、サインアウトします。

実践編 : 実際にコードを動かす

1. https://dev.office.com/ に行き、[GET CODE SAMPLES] をクリックします。
2. 画面右上の検索画面にて、starter と検索し、今回は以下のサンプルを使用してみましょう。

3. [SHOW THE CODE] をクリックします。

4. GitHut のソース管理画面に遷移したら、画面右下の [Download ZIP] をクリックします。

5. 展開されたソリューション ファイル (O365-APIs-Start-Windows.sln) を Visual Studio 2013 + Update 4 で開きます。

6. ソリューション エクスプローラより [参照設定] を右クリックし、[NuGet パッケージの管理] をクリックします。

7. 画面右上の [復元] をクリックし、足りないパッケージをダウンロードします。

8. ソリューション エクスプローラーよりプロジェクトを右クリックし、[追加] - [接続済みサービス] をクリックします。

9. サービス マネージャ ダイアログが表示されます。Microsoft アカウントの入力画面が表示された場合は閉じます。
10. サービス マネージャ ダイアログより [Office 365] - [Office 365 API] - [アプリを登録する] をクリックします。

11. Office 365 へのログイン情報を入力します。

12. Github のページ上の Register app to consume Office 365 APIs に記載がある通り、アプリのアクセス許可を指定し、[OK] をクリックします。

1. 1. • (Calendar) – Read and write to your calendars.

1. 1. • (Contacts) - Read and write to your contacts.

1. 1. • (My Files) – Read and write your files.

1. 1. • (Users and Groups) – Sign you in and read your profile.

1. 1. • (Users and Groups) – Access your organization's directory.

1. 1. • (Mail) - Read and write to your mail.

1. 1. • (Mail) - Send mail as you.

13. 処理が完了するまでしばらく待機します。

<<ここからいくつか修正を実施します。>>

14. ソリューション エクスプローラ よりApp.xaml をダブルクリックし、Application.Resources の欄に ida:ClientId と ida:AuthorizationUri が記載されていることを確認します。

15. Helpers\Authentication をダブルクリックし、下記のコードを修正します。

(修正前)

private static readonly string CommonAuthority = App.Current.Resources["ida:AADInstance"].ToString() + @"Common";

(修正後)

private static readonly string CommonAuthority = App.Current.Resources["ida: AuthorizationUri"].ToString() + @"Common";

16. [F5] を押して、デバッグ実行します。

ここまでの手順を実行し、デバッグしながら、Azure AD に対する認証や Office 365 API の実装を眺めてください。Office 365 API が使用しやすいようにクラス化されていて、画面を作り替えるだけでもかなり色々なことができることがわかると思います。

今回の投稿は以上となります。