環境: Microsoft Online Services, Visual Studio 2008

Exchange Online 開発

• EWS (Web サービス) による開発入門
• 通知 (Notification) の実装
• 自動検出 (Autodiscover) と EWS Managed API
• OAuth Token 認証

注意 (重要) : ここでは Basic Authentication を使用していますが、今後、Exchange Online の API アクセスでは、Token 認証を使用してください。Token 認証については、「EWS (Managed API) の OAuth Token 認証」に記載しました。(Basic 認証は 2020/10/13 に終了予定です。)
また、クラウドの Exchange Online に対するデータアクセスには、今後 Microsoft Graph を使用してください。(2022/09/30 以降、Exchange Online 上で新規の EWS アプリの作成はできません。また、2026 年 01 月以降、Exchange Online の EWS の呼び出しはブロックされます。)

こんにちは。

今後のセミナーの準備として、現在 (Exchange 2007 ベース) の Exchange Online (BPOS) の開発手法について復習しておきます。

利用環境の設定

まずは、Microsoft Online Services にサインインをおこない、使用環境を設定してください。(30 日間利用可能なトライアル版もあります。)
ここでは詳細を省略しますが、おおまかに手順を記載すると、以下の通りです。

1. Microsoft Online Services の申請と 管理サイト (下記) でのセットアップをおこないます
2. 管理サイト(下記) で、ユーザーを新規作成します
   • この際、このユーザーの一時パスワードを設定します
3. 作成したユーザーで、サインイン ツール、もしくは ポータルサイト(下記) にログインします
   • ここで、ユーザーの正式なパスワードを設定します
   • この設定により、受信メールボックスなどが作成されます
4. Outlook、または OWA サイト (下記) でログインして、メール (Exchange Online) を使用できます
   (ポータルサイトから、サインイン ツールをダウンロードして、インストール、ログインすると、Outlook クライアントなどもすべて設定してくれます。ただし、今回は、必要ありません。)

注意 : デモなどで、複数ユーザーの設定をポータルサイトでおこなう場合は、使用するユーザーごとに、ブラウザのクッキー、パスワード等を (IE の [インターネット オプション] で) 毎回 クリアしていただくことをお薦めします。(ポータルサイトは、ブラウザに記録されているこれらの情報を参照しています)

上記の「管理サイト」、「ポータルサイト」、「OWA サイト」、そして、このあと説明する EWS (Exchange Web Services) で使用するサービスの接続先の URL は、以下になります。(サイトの URL については、こちら や、こちら に説明されています。)

管理サイト / ポータルサイト :

https://portal.microsoftonline.com/

EWS (Exchange Web Services) の接続先 (red003 は日本の場合の接続先です) :

https://red003.mail.apac.microsoftonline.com/EWS/Exchange.asmx (new Office 365 の場合 : https://outlook.office365.com/EWS/Exchange.asmx)

補足 : Office 365 の URL, IP アドレスについては、こちら を参照してください。SMTP、POP などのアドレスについては、OWA (Outlook Web App) から確認できます。

EWS (Exchange Web Services) を使用した開発の概要

Exchange Server へのアクセスは、COM の CDO (Collaboration Data Objects) や、MAPI、WebDAV など、従来より、多くのクライアント アクセス手法が提供されてきましたが、ご存じの通り、Exchange Server 2007 から、Exchange Web Services (EWS) など .NET 周辺の手法が充実しています。(ここではクライアント アクセス手法に注目していますが、サーバー系では、PowerShell や、CAS の Managed Transport API など、.NET 周辺の管理・拡張手法も整備されています。)

この .NET のアクセス手法 (EWS) は、従来のさまざまな手法を包括したオープンなアクセス手法として、今後 (Exchange 2010 以降も) ますます投資されていく傾向にあり、今回テーマとしている Exchange Online でも、この手法を標準的に使用します。
ここでは省略しますが、SOAP Web Services ですので、Java など他言語からも接続可能で、例えば、GMail と Exchange Online の相互接続をおこなうアプリケーションなど、さまざまな応用例が考えられます。(エンベロープをそのまま渡せば、SOAP Web Service を扱えない開発言語からも接続できます。)

なお、EWS を使用した Exchange Online の開発手法については、下記のドキュメントが提供されていますので、是非参考にしてみてください。(しかし、いくつかドキュメントにはないポイントもあるので、ここでは、その辺りも解説します。)

ダウンロードセンター : Microsoft Exchange Online 開発者ガイド
http://www.microsoft.com/downloads/details.aspx?FamilyID=0ffa787d-79cd-43fd-b528-b47d45c7ea0d&displaylang=ja

追記 : 現在、Exchange Web Services (EWS) は NuGet から取得 (インストール) 可能です。

プロジェクトの新規作成

EWS は、その名の通り、”旧来の” (という言い方はご幣がありますが . . .) SOAP Web サービスを使用しています。いまさら解説をするまでもないと思いますが、.NET 3 以降では、Web サービスも含めた包括的な通信テクノロジーとして WCF が提供されており、今回のサンプルでも、Visual Studio 2008 を使用して、WCF で、この Web サービスに接続をおこないます。

WCF の開発では、慣れてきたら ChannelFactory を使用した自前での開発を是非おすすめしたいのですが、このあとのサンプルで見るように、非常に膨大なクラスやコントラクトを使用しますので (これらを 1 から定義するのは嫌なので)、あまり好きな方法ではありませんが、以降では、「サービスの参照」(svcutil.exe) でこれらのコントラクト情報を自動作成します。(多くのコードが自動作成されますが、使用されている認証方法などがわかるように、適宜、解説を入れていきます。)
なお、バインディング、認証方法など、基本をちゃんとおさえておけば、ChannelFactory を使用して接続も可能です。

では、早速 作成していきましょう。

まず、Visual Studio を起動します。
そして、WPF アプリケーション、Windows フォーム アプリケーションなどのプロジェクトを 適宜 作成します。

ソリューション エクスプローラーでプロジェクトを右クリックして、[サービス参照の追加] (add service reference) を選択し、表示される画面で、アドレス欄に、上記のサービスの URL (https://. . ./EWS/Exchange.asmx) を入力して、[OK] ボタンを押します。

補足 : new Office 365 の場合、https://outlook.office365.com/EWS/Services.wsdl に接続 (add service reference) をしてメタデータ (wsdl) を取得してください。

この際、ユーザー名とパスワードの入力を促されるため、メール送受信が可能な Exchange Online のユーザー (上記の「利用環境の設定」で作成したユーザー) のユーザー ID / パスワードを入力します。

注意 : ご存じの通り、ここで入力するユーザー ID は、必要なメタデータなどを取得するための一時的なユーザーであり、ここで指定するユーザーでアプリケーションにログインするわけではありません。(何度かやりとりをするため、複数回 同じダイアログ ボックスが出てきますが、すべて入力してください。)

構成 (.config) の記述

上記の「サービス参照の追加」 (svcutil.exe) で、WCF のクライアント用のプロキシコードや接続用の構成 (.config) が自動作成されますが、実は、この設定のままでは接続することはできません。
そこで、プロジェクトの .config ファイル (App.config など) を開いて、自動作成された構成情報をすべて削除し、以下の通り記載してください。

<?xml version="1.0" encoding="utf-8" ?><configuration>  <system.serviceModel>    <client>    <endpoint name="MyBPOSEndpoint"          address="https://outlook.office365.com/EWS/Exchange.asmx"          binding="basicHttpBinding"          bindingConfiguration="ExchangeServiceBinding"          contract="ServiceReference1.ExchangeServicePortType" />    </client>    <bindings>      <basicHttpBinding>        <binding name="ExchangeServiceBinding">          <security mode="Transport">          <transport clientCredentialType="Basic"/>          <message clientCredentialType="UserName"               algorithmSuite="Default"/>          </security>        </binding>      </basicHttpBinding>    </bindings>  </system.serviceModel></configuration>

上記の構成について、軽く解説しておきます。

まず、前述したように、EWS は、WS-* ではない、従来の Web サービス (Web Services) のプロトコルを使用しているため、BasicHttpBinding を使用します。(もちろん、カスタム バインディング (CustomBinding) を使用して構成しても構いません。)
また、Contract を見ていただくとおわかりの通り、内部では、サービスコントラクトとして ExchangeServicePortType が使用されます。以降で解説するコードでは、svcutil.exe が作成した ExchangeServicePortTypeClient をそのまま使用していますが、自動生成される ExchangeServicePortTypeClient のプロキシ コードでは、内部で、この ExchangeServicePortType を使用しており、ChannelFactory を使って、このサービス コントラクトで処理することも可能です。

セキュリティについては、「https:// . . .」というアドレスからもお分かりの通り、SSL を使用しています。また、Exchange Online の認証は、既定で (特別な設定をしていない場合)、基本認証 (Basic 認証) が使用されます。
このため、Security の mode は、SSL 有りの Basic 認証 (WCF の既定の Basic 認証の構成) で良いので、TransportCredentialOnly ではなく、Transport を指定しています。

ここではコードを簡単にするため、必要最低限の設定しか記述していませんが、本運用では、必要に応じて、バッファー サイズ、スロットルの設定などを記述してください。

補足 : 現行の SharePoint Online (SharePoint Server 2007 ベースのオンライン サービス) も、同様の構成で、WCF を使って .asmx の Web サービスに接続できます。

コードの記述

では、上記の構成を使用して、プログラムの記述をおこなってみましょう。今回は、Exchange Online にログインし、メールを送信します。

上記で解説したように、今回は、svcutil.exe が自動作成した ExchangeServicePortTypeClient をそのまま使用します。

using MailTestApplication.ServiceReference1;. . .// 接続 (See above notation for authentication ...)ExchangeServicePortTypeClient cl = new ExchangeServicePortTypeClient("MyBPOSEndpoint");cl.ClientCredentials.UserName.UserName = "demouser1@tsmatsuz.apac.microsoftonline.com";cl.ClientCredentials.UserName.Password = "XXXXXXX";cl.Open();// リクエストの作成CreateItemType requestObj = new CreateItemType();requestObj.MessageDisposition = MessageDispositionType.SendAndSaveCopy;requestObj.MessageDispositionSpecified = true;// メッセージの作成MessageType message = new MessageType();message.Subject = "テスト";message.Body = new BodyType{    BodyType1 = BodyTypeType.Text,    Value = "松崎参上"};message.From = new SingleRecipientType(){    Item = new EmailAddressType()    {        EmailAddress = @"demouser1@tsmatsuz.apac.microsoftonline.com"    }};EmailAddressType[] toAddressArray = new EmailAddressType[1];toAddressArray[0] = new EmailAddressType(){    EmailAddress = @"demouser2@tsmatsuz.apac.microsoftonline.com"};message.ToRecipients = toAddressArray;// 送信実行 !ItemType[] items = new ItemType[1];items[0] = message;requestObj.Items = new NonEmptyArrayOfAllItemsType();requestObj.Items.Items = items;CreateItemResponseType responseObj;//// When BPOS (Exchange 2007)//cl.CreateItem(//    null,//    null,//    "ja-JP",//    null,//    null,//    requestObj,//    out responseObj);//// When new Office 365 (Exchange 2013)cl.CreateItem(  null, //ExchangeImpersonationType  new MailboxCultureType()  {    Value = "ja-JP"  }, //MailboxCultureType  new RequestServerVersion()  {    Version = ExchangeVersionType.Exchange2013  }, //RequestServerVersion  new TimeZoneContextType()  {    TimeZoneDefinition = new TimeZoneDefinitionType()    {      Id = "Tokyo Standard Time"    }  }, //TimeZoneContextType  requestObj, //CreateItemType  out responseObj //CreateItemResponseType  );// 切断cl.Close();// 応答の解析ResponseMessageType[] responseMessages =    responseObj.ResponseMessages.Items;foreach (ResponseMessageType res in responseMessages){    if (res.ResponseClass == ResponseClassType.Error)        MessageBox.Show(res.MessageText, "応答", MessageBoxButtons.OK, MessageBoxIcon.Error);    else if (res.ResponseClass == ResponseClassType.Warning)        MessageBox.Show(res.MessageText, "応答", MessageBoxButtons.OK, MessageBoxIcon.Warning);}MessageBox.Show("処理終了");

ここは、とにかくコードを追っていただければ、どのような処理をおこなっているか容易に想像していただけるでしょう。(特に解説はおこないません。)
ポイントは、CreateItemType、MessageType、ItemType 等々、非常に多くのコントラクトが使用されているという点です。(これらの定義は、svcutil.exe によって自動作成されています。)

ここでは、demouser1@tsmatsuz.apac.microsoftonline.com でログインして、demouser2@tsmatsuz.apac.microsoftonline.com にメールを送信する簡単なサンプルですが、メールに関するその他の処理はもちろん、予定表 (Calendar) と連携したアプリケーションなども同様に構築可能です。

渡しているエンベロープ

なお、上記の処理によって、以下の Envelope が渡されています。Java、.NET 以外の SOAP Web Service を扱えない環境であっても、HTTP 要求さえ処理できれば、簡単な Basic 認証 (Base64 によるエンコード、など) と下記のエンベロープを使って、プログラムから Exchange に処理を要求できます。

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">  <s:Header>    <h:MailboxCulture      xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"      xmlns="http://schemas.microsoft.com/exchange/services/2006/types"      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"      xmlns:xsd="http://www.w3.org/2001/XMLSchema">      ja-JP    </h:MailboxCulture>    <h:RequestServerVersion Version="Exchange2013"      xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"      xmlns="http://schemas.microsoft.com/exchange/services/2006/types"/>    <h:TimeZoneContext      xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"      xmlns="http://schemas.microsoft.com/exchange/services/2006/types">      <TimeZoneDefinition Id="Tokyo Standard Time"/>    </h:TimeZoneContext>  </s:Header>  <s:Body    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:xsd="http://www.w3.org/2001/XMLSchema">    <CreateItem MessageDisposition="SendAndSaveCopy"      xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">      <Items>        <Message xmlns="http://schemas.microsoft.com/exchange/services/2006/types">          <Subject>テスト</Subject>          <Body BodyType="Text">松崎参上</Body>          <ToRecipients>            <Mailbox>              <EmailAddress>demouser2@tsmatsuz.apac.microsoftonline.com</EmailAddress>            </Mailbox>          </ToRecipients>          <From>            <Mailbox>              <EmailAddress>demouser1@tsmatsuz.apac.microsoftonline.com</EmailAddress>            </Mailbox>          </From>        </Message>      </Items>    </CreateItem>  </s:Body></s:Envelope>

今後

このようにやや面倒な手続きが必要ですが、実は、この EWS を使った Managed API (.NET の API) や Java API も使用可能で、より簡易にコードを記述することができます。(2010/10/08 追記 : Managed API については、第 3 回 に記載しました。)

これらについては、是非、セミナーなどでご紹介したいと思います。