Outlook アドインから Web サービスを呼び出す

アドインは、Exchange Server を実行しているコンピューター、アドインの UI のソースの場所を提供するサーバーで使用できる Web サービス、またはインターネットで使用できる Web サービスから Exchange Web サービス (EWS) を使用できます。 この記事では、Outlook アドインからどのように EWS の情報を要求できるかを示す例を説明します。

Web サービスを呼び出す方法は、Web サービスの場所によって異なります。 次の表に、場所に基づいて Web サービスを呼び出すさまざまな方法を示します。

makeEwsRequestAsync メソッドを使用して EWS 操作にアクセスする

mailbox.makeEwsRequestAsync メソッドを使用して、ユーザーのメールボックスをホストしている Exchange サーバーに EWS 要求を行うことができます。

EWS では、Exchange サーバー上のさまざまな操作がサポートされています。たとえば、アイテムをコピー、検索、更新、または送信するアイテム レベルの操作や、フォルダーを作成、取得、または更新するためのフォルダー レベルの操作などです。 EWS 操作を実行するには、その操作の XML SOAP 要求を作成します。 操作が完了すると、操作に関連するデータを含む XML SOAP 応答が返されます。 EWS SOAP の要求と応答は、Messages.xsd ファイルで定義されているスキーマに従います。 他の EWS スキーマ ファイルと同様に、Message.xsd ファイルは EWS をホストする IIS 仮想ディレクトリにあります。

makeEwsRequestAsync メソッドを使用して EWS 操作を開始するには、次のコマンドを指定します。

• データ パラメーターの引数として、その EWS 操作の SOAP 要求の XML

• コールバック関数 ( コールバック 引数として)

• そのコールバック関数の任意の入力データ ( userContext 引数として)

EWS SOAP 要求が完了すると、Outlook は、 AsyncResult オブジェクトである 1 つの引数を使用してコールバック関数を呼び出します。 コールバック関数は、AsyncResult オブジェクトの 2 つのプロパティ (EWS 操作の XML SOAP 応答を含む value プロパティ) と、必要に応じて、userContext パラメーターとして渡されたデータを含む asyncContext プロパティにアクセスできます。 通常、コールバック関数は SOAP 応答の XML を解析して関連情報を取得し、それに応じてその情報を処理します。

EWS 応答を解析するためのヒント

EWS 操作から SOAP 応答を解析する場合は、ブラウザーに依存する次の問題に注意してください。

• Internet Explorer と Trident Webview のサポートを含めるために、DOM メソッド getElementsByTagNameを使用する場合は、タグ名のプレフィックスを指定します。

  getElementsByTagName ブラウザーの種類に応じて動作が異なります。 たとえば、EWS 応答には、次の XML を含めることができます (表示目的で書式設定され、省略されます)。

  <t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
  PropertyName="MyProperty" 
  PropertyType="String"/>
  <t:Value>{
  ...
  }</t:Value></t:ExtendedProperty>
  

  次のように、コードは Chrome などのブラウザーで動作し、 ExtendedProperty タグで囲まれた XML を取得します。

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("ExtendedProperty")
  });
  

  Trident (Internet Explorer) Webview の場合は、タグ名の t: プレフィックスを次のように含める必要があります。

  const mailbox = Office.context.mailbox;
  mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
       const response = $.parseXML(result.value);
       const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
  });
  

• 次のように、DOM プロパティ textContent を使用して、EWS 応答でタグの内容を取得します。

  content = $.parseJSON(value.textContent);
  

  などのその他のプロパティは、EWS 応答の一部のタグの Trident (Internet Explorer) Webview では機能しない場合があります。

例

次の例では、 makeEwsRequestAsync を呼び出して GetItem 操作を使用して項目の件名を取得します。 この例には、次の 3 つの関数が含まれています。

• getSubjectRequest – 項目 ID を入力として受け取り、指定した項目の GetItem を呼び出す SOAP 要求の XML を返します。

• sendRequest – getSubjectRequest を呼び出して選択した項目の SOAP 要求を取得し、SOAP 要求とコールバック関数 callbackを渡して makeEwsRequestAsync して、指定した項目の件名を取得します。

• callback – 指定した項目に関する件名やその他の情報を含む SOAP 応答を処理します。

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

アドインでサポートしている EWS 操作

Outlook アドインは、 makeEwsRequestAsync メソッドを使用して EWS で使用できる操作のサブセットにアクセスできます。 EWS 操作に慣れていない場合や、 makeEwsRequestAsync メソッドを使用して操作にアクセスする方法については、SOAP 要求の例から始めて データ 引数をカスタマイズします。

次に、 makeEwsRequestAsync メソッドを使用する方法について説明します。

1. XML 内のアイテム ID および関係する EWS 操作属性を適切な値に置き換えます。

2. makeEwsRequestAsyncのデータ パラメーターの引数として SOAP 要求を含めます。

3. コールバック関数を指定し、 makeEwsRequestAsyncを呼び出します。

4. コールバック関数で、SOAP 応答の操作の結果を確認します。

5. 必要に応じて EWS 操作の結果を使用します。

次の表は、アドインがサポートしている EWS 操作を示しています。 SOAP の要求と応答の例を表示するには、各操作のリンクを選択します。 EWS 操作の詳細については、「 Exchange での EWS の操作」を参照してください。

makeEwsRequestAsync の認証とアクセス許可について

makeEwsRequestAsync メソッドを使用すると、現在のユーザーの電子メール アカウント資格情報を使用して要求が認証されます。 makeEwsRequestAsyncメソッドは、要求で認証資格情報を指定する必要がないように、資格情報を管理します。

makeEwsRequestAsync メソッドを使用するには、アドインがマニフェストでメールボックスの読み取り/書き込みアクセス許可を要求する必要があります。 マークアップはマニフェストの種類によって異なります。

• アドインのみのマニフェスト: <Permissions> 要素を ReadWriteMailbox に設定します。
• Microsoft 365 の統合マニフェスト: "authorization.permissions.resourceSpecific" 配列内のオブジェクトの "name" プロパティを "Mailbox.ReadWrite.User" に設定します。

メールボックスの読み取り/書き込みアクセス許可の使用については、「メールボックスの読み取り/書き込みアクセス許可」を参照してください。

関連項目

• Office アドインのプライバシーとセキュリティ
• Office アドインにおける同一生成元ポリシーの制限への対処
• Exchange 用 EWS リファレンス
• Exchange での Outlook 用メール アプリと EWS

ASP.NET Web API を使用したアドインのバックエンド サービスの作成については、次を参照してください。

• ASP.NET Web API を使用して Office アドイン用 Web サービスを作成する
• ASP.NET Web API を使用した HTTP サービスの構築に関する基本