Office 365 API 入門 – Web アプリケーション編

Office 365 で用意されている Office 365 API を使用すると、例えばプログラムからメールボックスの内容を参照したり、メールを送信したりといったユーザーの操作を行うことができるようになります。Exchange 2007 から使用できる EWS のほうがより高度なことが実現でき、開発者の人口が多く情報が集まりやすいのは事実ですが、Office 365 API はいわゆる REST 通信となるので Windows や .NET 以外のプラットフォームの開発者から好まれるように思います。

Office 365 API のリファレンスは MSDN で公開されていますが、実際にリクエストを送信できるようにするまでが EWS と違い少し面倒です。そのため、「試しに触ってみよう」と思ってもハードルが少し高いです。

まずはどんなものなのかを試してみたいという人向けに、Office 365 API の入門をお届けしたいと思います。Office 365 API の認証で OAuth を使用するにあたり、その前提となる Azure Active Directory の準備と、Web アプリケーションとして Azure Active Directory にアプリケーションを登録した場合の Office 365 API の実行方法の一例をご紹介します。

それではさっそく始めましょう。

Office 365 API を使用するためには、Office 365 のテナントだけではなく Microsoft Azure のサブスクリプションも必要です。これは認証に OAuth を使用するためです。
まずは Office 365 の管理者アカウントで Microsoft Azure を管理できるようにします。

https://manage.windowsazure.com/ にアクセスして、Office 365 の管理者アカウントでサインインします。

20160403 (1)

Office 365 の試用版の管理者アカウントを使用したので、Microsoft Azure のサブスクリプションが見つからないという画面に誘導されます。

20160403 (2)

[MICROSOFT AZURE にサインアップ] をクリックします。無料試用版のサインアップ画面に進みますので、必要項目を入力してサインアップします。

20160403 (3)

少し時間がかかりますが、完了すると、[サービスの管理を開始する] というリンクが表示されます。クリックして Microsoft Azure の管理画面を表示します。

20160403 (4)

Azure Active Directory の管理を行うため、旧ポータル https://manage.windowsazure.com/ へ移動します。すべての項目を表示すると、Office 365 で使用している Azure Active Directory 以外には項目はありませんので、表示されている項目をクリックします。

20160403 (5)

Azure Active Directory の管理画面が開きました。[アプリケーション] をクリックします。

20160403 (6)

すでに Office 365 の各サービスが表示されていますが、ここで Office 365 API を使用するアプリケーションを登録します。[追加] をクリックします。

20160403 (7)

ウィザードに従ってアプリケーションの情報を入力します。ここでは [組織で開発中のアプリケーションを追加] をクリックします。

20160403 (8)

アプリケーションの名前を入力して、種類を選択します。ここでは [WEB アプリケーションや WEB API] を選択します。

20160403 (9)

[サインオン URL] には、このアプリケーションを使用するときにアクセスする URL を入力します。実際にアクセスできる必要はありません。例えば「http://localhost/webapp01」のようにします。[アプリケーション ID/URI] は一意である必要があるので、例えば「https://contoso.onmicrosoft.com/webapp01」のようにテナント名を指定するとよいでしょう。

20160403 (10)

アプリケーションの追加が完了したら、[構成] ページに移動します。[キー] のドロップダウンからキーの有効期限を任意で選択します。選択をしたら、[保存] をクリックします。

20160403 (11)

先ほどの場所にキーが表示されているので、控えておきます。このキーのことを、クライアント シークレットと呼びます。同じページに [クライアント ID] も表示されているのでこちらも控えておきます。

20160403 (12)

このアプリケーション経由でどのような操作ができるかを設定します。同じページの下に [他のアプリケーションに対するアクセス許可] がありますので、[アプリケーションの追加] をクリックします。

20160403 (13)

ここでは例として [Microsoft Graph] を追加します。

20160403 (14)

ここでは例として Exchange Online のメールの読み取りができるように、Microsoft Graph のデリゲートされたアクセス許可から [Read user mail] を選択して、保存します。

20160403 (15)

これで Azure Active Directory の準備は完了です。続いて、実際に Office 365 API を使用するために必要な Access Token を OAuth で取得します。OAuth なので開発言語にかかわらず実装することができますが、ここでは開発言語なしで流れを確認しながらとにかく試す方法を紹介します。

まずは Authorization Code を取得します。以下のように URL を作って、ブラウザーでアクセスします。

https://login.windows.net/common/oauth2/authorize?response_type=code&client_id=クライアント ID&redirect_uri=URL エンコードしたサインオン URL&resource=URL エンコードした Office 365 API エンドポイント&prompt=login

例えば、以下のようになります。ちなみに、「prompt=login」はなくても動作しますが、これを指定することで既存のサインイン情報を使用せずに必ず認証画面が表示されるようになります。すでに SSO を構築している環境でテストをするときには有用になります。

https://login.windows.net/common/oauth2/authorize?response_type=code&client_id=99bef61c-f239-4544-b869-51dbf50a6960&redirect_uri=http%3a%2f%2flocalhost%2fwebapp01&resource=https%3a%2f%2fgraph%2emicrosoft%2ecom%2f&prompt=login

URL にアクセスすると Office 365 のサインイン画面が表示されますので、Office 365 のユーザーでサインインします。

20160403 (16)

正しくサインインできると、アプリケーションのサインオン URL にリダイレクトされます。正しく表示できなくても、必要な情報はクエリ文字列から取得しますので問題ありません。例えば以下のような URL にリダイレクトされ、赤文字にした code の内容が Authorization Code となります。

http://localhost/webapp01?code=AAABAAAAiL9Kn2Z27UubvWFPbm0gLbt7QGxge9IusIusPtYoee4OLU4QyUD-inpPjED0yUfz36wLfTlKwWuGu3Ivqy1B4ATPHgwZdsB1O5_taTrPXBh6h7sNG68fRSNagfRSNagu-XfmCHD6Od9w0s_ovPf_BQO6QU4QVwfnM06hLpIe2tkLfSsIZMOkZNeqpm6lcwKj79–vavfxqZB8b6Veh90Dd1csFvm8cpNsUkzbVsRp400TvMkUQ-1hcULXYT3oZhvQc7TyzBU-2r40APNJX03MbTfv_1gp7kncP7o-cQQW166PjoktvbAf-w2GnO72CQqzQ_y4yGsYSH7xrP7RRmB_9Am4pFkFqTmRiEfjDq1zMKm1FNWeda21sysyTHM8cNwEYo-p9aX6FB1p9ChFBk9k512J1YuHnDqZEdfKh-C-AHnGNI6U88B-NFxxkOT5aGOaNctktfONHA0gJF1EH-IqiMIRrm6AivumgieWPq5eVhQiqrljmgvcYnyxZMXf2dzyfaT4isJYCTNuLUQ86fFAjHgRvfFAjHg_-Ym4zDEoKzkQrPTGq8gx8o5GbtRCxteW8xP-aRvOcLJpXx8DOx1tyAA&session_state=5a79e584-2223-4ef1-b681-1df3b70fd2b8

次に Access Token を取得します。ここでは POST リクエストを使用するので、Google Chrome のアプリ「Postman」を使用します。まずは Postman をインストールして起動します。

以下のようにリクエストを作って、https://login.windows.net/common/oauth2/token/ へPOST リクエストを送信します。Body は「x-www-form-urlencoded」を選択します。

grant_type : authorization_code
code : 取得した Authorization Code
redirect_uri : サインオン URL
client_id : クライアント ID
client_secret : クライアント シークレット

20160403 (17)

成功すると、以下のように応答が返ってきます。access_token が、Office 365 API で使用する Access Token です。

20160403 (18)

ついに Office 365 API のリクエストを送信します。メールの読み取り権限がるので取得してみたいと思います。https://graph.microsoft.com/v1.0/me/messages へ GET でリクエストします。この時、Authorization ヘッダーに Access Token をしてしますが、先頭に「Bearer」と半角スペースを追加します。「Bearer 1a2b3c4d…」のようになります。

20160403 (19)

リクエストが成功すると、JSON 形式のレスポンスでメールの内容が返されます。実際にアプリケーションから利用するときはこの内容をデシリアライズして画面表示するなどします。

20160403 (20)

他にもたくさんの操作が API には用意されています。必要なアクセス権を Azure Active Directory で設定して、その動作を試してみてください。