Outlook REST API 開発 (Outlook.com 対応も)

Uncategorized

By Tsuyoshi Matsuzaki on 2015-08-24 • ( Leave a comment )

Outlook REST API (以降の https://outlook.office.com または https://outlook.office365.com) は 2022/11/30 に終了予定です。今後は Microsoft Graph (統一エンドポイント) を使用してください。

Office 365 API

• Office 365 API 入門
• HTML ハイブリッド アプリでの使用 (JavaScript for Cordova)
• Web フロントエンド (JavaScript) での使用 (CORS)
• PHP, Node.js からの使用
• Outlook REST API を使った開発 (Outlook.com 対応)
• Outlook REST API での通知 (Webhook) ・同期 (Sync) の処理
• OneDrive API を使った開発
• OneDrive API での通知 (Webhook)・同期 (Sync) の処理
• Yammer API を使った開発

(Skype API は こちら)

以降、Microsoft Graph では下記を使用してください。
/users/{id}/messages
/users/{id}/calendar/calendarView
/users/{id}/events
/users/{id}/contacts

こんにちは。

今回は、Outlook REST API を例に、企業・学校ユーザー向けの Office 365 Exchange Online と、一般ユーザー向け (管理者不要) の Outlook.com (旧 Hotmail) の双方に対応した開発手法を紹介します。

Outlook REST API には、大きく、Mail、Calendar、Contact の 3 つのオブジェクトがありますが、ここでは Mail を例に紹介します。

2015/11 追記 : Outlook Rest API v2.0 (https://outlook.office.com/api/v2.0)、および Microsoft Graph で Outlook.com に正式対応しました。

 

Outlook for Exchange, Outlook.com (旧 Hotmail) に対応した Unified REST API

Office 365 には、Office 365 Business 版や Enterprise 版に代表される商用 (Commercial) 向けと、Office 365 Home や Personal (日本の場合、家電量販店などで見かける Office 365 Solo など) に代表される一般ユーザー (Consumer) 向けが提供されています。(以前も解説した通り、相互の要件には「管理者が必要か or 必要でないか」などの大きな相違があり、このように区別されています。)

MS の技術を長く見てこられた方はご存じの通り、この「商用向け」と「一般向け」で使用されているサービス (OneDrive など) は、その歴史的経緯からエンジンやアクセスする際の API も異なっていました。
例えば、あるアプリケーションに「Office 365 でサインアップ」といったボタンがあり、Exchange や SharePoint など商用版の Office 365 と連携するアプリを想像してください。一般ユーザーの感性としては、当然、自分が持っている Office 365 Solo (Home or Personal) でも使えるだろうと期待するでしょう。しかし実際は、商用向けに開発された機能のほとんどは、一般向けの Office 365 アカウントでは使用できません。

de:code のセッション「Office / Office 365 新機能紹介」でも紹介したように (あるいは、以前 MSDN Flash でも触れたように)、今後、こうした「商用向けサービス」と「一般向けサービス」の間の API が統一化される予定です。(← すみません、この de:code のセッション動画は、未公開 Bits を使用しているため公開していません。)

ここでは、この双方にいちはやく対応した Outlook REST API を例に、この統合開発の流れを紹介します。

補足 : 従来も、双方 (企業向けと一般ユーザー向け) に対応したアプリを作れなかった訳ではありません。「Office 365 API 入門」でも紹介したように、https://api.office.com/discovery/me/FirstSignIn を使って Azure AD と Microsoft Account (MSA) の相互の振り分けが可能で、どちらでログインしたかアプリで判断して、例えば、Exchange ベースの Outlook REST API や Outlook.com (旧 Hotmail) の SMTP などを呼び分けるプログラミングが可能でした。
しかし、この双方の API 間の機能差は大きく、完全な 2 重開発となってしまいます。

補足 : 従来の一般 (Consumer) 向け Office 365 (Office 365 Solo など) の開発技術については「Office 365 Home (Outlook.com, OneDrive, etc) 開発」を参照してください。

 

アプリケーションの登録

今回紹介する新しい Flow も、一般の OAuth & REST API と何ら変わりありません。(Office の開発に慣れていない方も、基本は Facebook, Twitter, LinkedIn 等々の開発の概念と変わりません。)
しかし、今回紹介する統合開発では、これまでの Azure AD の Endpoint (v1 endpoint) と異なり、v2 endpoint と呼ばれる新しい Endpoint を使用します。

補足 (2016/02 追記) : v2 endpoint を使って可能な実装シナリオ (および制限事項) の詳細は、「v2.0 endpoint の OAuth を使った Client 開発」にまとめましたので参照してください。

まず、OAuth を使用した認証フローを実装するため、Azure Portal から Azure Active Directory の管理画面に行き、あらかじめ作成する Application を登録し、必要な構成情報を入力してください。(設定手順詳細は「Office 365 API 入門」を参照してください。)

このあと、登録したアプリケーションの以下の情報を使用しますので、コピーしておいてください。

Application Id	Application を一意に識別する重要な Id です。(従来 client id と呼んでいたものです。) ここは自動で設定されますので、内容をメモ帳などにコピーしておいてください。
Application Secrets	Web アプリの Flow では必須です。(このあとの Flow で使用します。) [Generate New Password] ボタンを押して Secret を作成し、メモ帳などにコピーしておいてください。
Redirect URIs	Login (SignIn) 後に戻される Redirect URI を指定します。 この情報も このあと使いますおぼえておいてください。

 

HTTP Flow の実装

登録が完了したら、Authentication をおこなうための OAuth Flow を処理するため、最初に、Web Browser (Mobile の場合は Browser Component など) を使って以下の URL にアクセスします。(下記で v2.0 が使用されている点に注目してください。)

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
response_type=code
&response_mode=query
&client_id=9dd1bcbf-0c29...
&scope=https%3a%2f%2foutlook.office.com%2fmail.read
&redirect_uri=https%3a%2f%2flocalhost%2ftest1

ここで、いくつか注意点があります。

まず、上記の接続先のアドレスに v2.0 と書かれている点に注意してください。今回は、このように、Azure AD と Microsoft Account (MSA) の双方を処理できる新しい v2 endpoint を使用します。

上記の query string の client_id には上記で取得した Application Id を指定し、redirect_uri には上記で設定した Redirect URI の URL エンコード文字列を指定します。(処理が終わると、この URL に戻されます。)
scope には、処理の内容を記述します。今回の場合、Outlook のメール読み込みをおこなうため、https://outlook.office.com/mail.read を指定しています。(scope を複数指定する場合は空白で区切ります。例えば、メールの読み込みと送信をおこなう場合は、https%3a%2f%2foutlook.office.com%2fmail.read%20https%3a%2f%2foutlook.office.com%2fmail.send と指定します。)

補足 : refresh token を取得する場合は、scope に offline_access を追加してください。(今回は指定していません。)

なお、現 Preview 段階では Outlook (Outlook for Exchange と Outlook.com) の Mail, Contact, Calendar しか対応していません (Unified Outlook Services API のみ)。
例えば、de:codeで、Unified Onedrive API の暫定プレビューを紹介しましたが、これも現時点はまだ同じステータスのままで (認証も分離されたままです)、Skype API も未対応ですので注意してください。(Skype については Office 365 版もまだ提供されていません。)

上記の URL にアクセスすると、Web Browser (または Browser Component) は、下図の SignIn 画面を表示します。下記メッセージの通り、この画面では、ビジネス向けの Azure AD Acccount (組織アカウント) と、一般向けの Microsoft Account の双方を受け付けます。

Azure AD Account か、Microsoft Account を入力して、認証をおこないます。
認証に成功すると、初回アクセス時は下図の Consent 画面を表示し、このアプリが Mail の Read をおこなうことをユーザーに通知します。
ユーザーはこのアプリが信頼できる場合に、[承諾] (はい) のボタンを押します。

Azure AD の場合 :

Microsoft Account の場合 :

補足 : なお、現時点では、Consent された App は、Azure AD、Microsoft Account (MSA) のそれぞれの App 管理の画面で削除してください。(Azure AD の場合は https://myapps.microsoft.com/、MSA の場合は https://account.live.com/consent/Manage です。)

認証に成功すると、Web Browser は (今回の場合) 下記の Url にリダイレクトされます。auth code には、認証結果としての Authorization code (アルファベットや数字の羅列) が入っています。

https://localhost/test1?code=<auth code>

Application 側では、上記で取得した auth code を使って、下記の POST 要求 (Request) を出します。(ここで、上記でコピーした Secret を使用します。)
なお、ここでも同様に、v2 endpoint が使用されている点に注意してください。

POST https://login.microsoftonline.com/common/oauth2/v2.0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<received auth code>
&client_id=9dd1bcbf-0c29...
&client_secret=9tjybWC1HYJv...
&redirect_uri=https%3A%2F%2Flocalhost%2Ftest1
&scope=https%3A%2F%2Foutlook.office.com%2Fmail.read

この結果として、下記の Json フォーマットの Response が返ってきます。
ここで、access token と呼ばれるものが取得できます。(user 情報や token の有効期限など、必要な情報は access token の中に書き込まれています。)

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "scope": "https://outlook.office.com/mail.read",
  "access_token": "EwB4Aul3BAAUo4xe..."
}

補足 : 現 Preview では、Microsoft Account の際に返される access token は compact tickets であり、「Azure AD : Service の開発」で解説した同じ方法で検証できません。(通常、Microsoft Account で検証が必要な場合は authentication token を使用しますが、このフローではサポートされていません。)
この相違については、今後解決される予定です。(現 Preview 段階での制限です。)

補足 : refresh token の取得方法については上述 (補足) を参照してください。

今回は、以下の通り GET 要求 (Request) を出すことで、取得した access_token を使って、メールボックス (Inbox) からメールを取得します。(最初の 20 件の、タイトル、受信日、送信者のみを取得しています。)
Outlook for Exchange (商用版の Office 365) か Outlook.com (旧 Hotmail) かに関係なく、同じ URI で取得できます。つまり、ここに至るすべてのコードで、「商用向け」と「一般向け」での相違 (異なるコード) はありません。

GET https://outlook.office365.com/api/v1.0/me/messages?
$orderby=DateTimeSent%20desc
&$top=20
&$select=Subject,DateTimeReceived,From
Accept: application/json
Authorization: Bearer EwB4Aul3BAAUo4xe...

Microsoft Account でログインした Outlook.com の場合でも、下記の通り、ちゃんと結果を返します。
Outlook.com にも、ようやく (待望の) REST API 到来です !

{
  "@odata.context": "https://outlook.office365.com/api/v1.0/$metadata#Me/Messages(Subject,DateTimeReceived,From)",
  "value": [
    {
      "@odata.id": "https://outlook.office365.com/api/v1.0/Users('appdev14@outlook.com')/Messages('AQMkADAwATN...')",
      "@odata.etag": "W/"CQAAABYAAAA/ywOhHYtLTIFtKce5fzrrAAA8OjDI"",
      "Id": "AQMkADAwATN...",
      "Subject": "Test Mail 02",
      "DateTimeReceived": "2015-08-25T04:28:05Z",
      "From": {
        "EmailAddress": {
          "Address": "tsmatsuz@microsoft.com",
          "Name": "Tsuyoshi Matsuzaki"
        }
      }
    },
    {
      "@odata.id": "https://outlook.office365.com/api/v1.0/Users('appdev14@outlook.com')/Messages('AQMkADAwATN...')",
      "@odata.etag": "W/"CQAAABYAAAA/ywOhHYtLTIFtKce5fzrrAAAtQRez"",
      "Id": "AQMkADAwATN...",
      "Subject": "Test Mail 01",
      "DateTimeReceived": "2015-07-28T08:28:09Z",
      "From": {
        "EmailAddress": {
          "Address": "demouser01@o365demo01.onmicrosoft.com",
          "Name": "Taro Demo"
        }
      }
    },
    ...
  ]
}

なお、Outlook.com を使用している場合、現在 Preview (2015/08 時点) が出ている New Outlook.com を使用する必要があります。(de:code 2015 でも紹介した新 UI の Preview 版です。) つまり、皆さんが普段お使いの Outlook.com アカウントでは、まだ使用できないので注意してください。現在、順次、この新しいプラットフォームに展開 (移行) が進められていますので、もしお使いのアカウントが New Outlook.com に対応していない場合は少々お待ちください。(2016/02 追記)
対応していない Outlook.com アカウントを使用した場合、Status 404 (Not Found) の下記 Response が返されます。

{
  "error": {
    "code": "MailboxNotEnabledForRESTAPI",
    "message": "REST API is not yet supported for this mailbox."
  }
}

 

Outlook REST API で可能なこと

Outlook REST API では、Mail、Calendar、Contact の読み書き (送受信) などの基本操作以外に、下記の高度な処理も可能です。

• メール (Message) 受信などの通知 (Webhook)、予定表 (Calendar) などの同期 (Synchronization) が可能です。
  詳細は「Outlook REST API : 通知 (Webhook) と同期 (Synchronization) を処理する」を参照してください。
• カスタム プロパティの利用が可能になりました。(Data Extension、Extended Property)
• 不在設定 (Automatic Reply Setting) が可能になりました。(/me/mailboxSettings/automaticRepliesSetting)
  詳細は「Microsoft Graph : Update automatic reply settings」を参照してください。
• 空き時間検索 (Free/Busy 検索) が可能な Find Meeting Times API が提供されました。(/me/FindMeetingTimes)
  詳細は「Microsoft Graph : user: findMeetingTimes」を参照してください。

 

※  変更履歴

2016/04/14  タイトル変更 (伴って、目次も変更)、BUILD 2016 での発表内容を反映

 

Categories: Uncategorized

Tagged as: Azure, Office