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

[アーティクル]
04/12/2024

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

重要

EWS の呼び出しと操作は、Outlook on Android と iOS で実行されているアドインではサポートされていません。

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

Web サービスの場所	Web サービスを呼び出す方法
クライアントメールボックスをホストする Exchange サーバー	mailbox.makeEwsRequestAsync メソッドを使用して、アドインがサポートしている EWS 操作を呼び出します。また、メールボックスをホストしている Exchange サーバーも EWS を公開します。
アドインの UI のソースの場所を提供する Web サーバー	標準の JavaScript の手法を使用して Web サービスを呼び出します。 UI フレーム内の JavaScript コードは、UI を提供する Web サーバーのコンテキストで実行されます。そのため、クロスサイトスクリプトエラーを発生させることなく、そのサーバーで Web サービスを呼び出すことができます。
上記以外の場所	UI のソースの場所を提供する Web サーバー上で、Web サービスのプロキシを作成します。プロキシを作成しないと、クロスサイトスクリプトエラーによってアドインを実行できなくなります。プロキシを作成する方法の 1 つは JSON/P を使用することです。詳細については、「 Office アドインのプライバシーとセキュリティ」を参照してください。

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

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

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

DOM メソッドgetElementsByTagNameを使用する場合は、タグ名のプレフィックスを指定して、インターネットエクスプローラーと Trident Webview のサポートを含めます。

getElementsByTagName ブラウザーの種類に応じて動作が異なります。たとえば、EWS 応答には、次の XML を含めることができます (表示目的で書式設定され、省略されます)。
```
<t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
PropertyName="MyProperty" 
PropertyType="String"/>
<t:Value>{
...
}</t:Value></t:ExtendedProperty>
```
次のように、コードは Chrome などのブラウザーで動作し、タグで囲まれた XML を ExtendedProperty 取得します。
```
const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("ExtendedProperty")
});
```
Trident (Internet エクスプローラー) 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);
```
などのinnerHTMLその他のプロパティは、EWS 応答の一部のタグの Trident (インターネットエクスプローラー) Webview では機能しない可能性があります。

例

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

getSubjectRequest – 項目 ID を入力として受け取り、指定した項目を呼び出 GetItem す SOAP 要求の XML を返します。
sendRequest– を呼び出getSubjectRequestして、選択した項目の SOAP 要求を取得し、SOAP 要求とコールバック関数を渡してmakeEwsRequestAsync、callback指定した項目の件名を取得します。
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 アドインは、メソッドを介して EWS で使用できる操作のサブセットに makeEwsRequestAsync アクセスできます。 EWS 操作に慣れていない場合や、メソッドを使用 makeEwsRequestAsync して操作にアクセスする方法については、SOAP 要求の例から始めて データ 引数をカスタマイズします。

メソッドの使用方法を次に makeEwsRequestAsync 示します。

XML 内のアイテム ID および関係する EWS 操作属性を適切な値に置き換えます。
の データ パラメーター makeEwsRequestAsyncの引数として SOAP 要求を含めます。
コールバック関数を指定し、を呼び出します makeEwsRequestAsync。
コールバック関数で、SOAP 応答の操作の結果を確認します。
必要に応じて EWS 操作の結果を使用します。

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

EWS 操作	説明
CopyItem 操作	指定したアイテムをコピーし、Exchange ストア内の指定のフォルダーに新しいアイテムを入れます。
CreateFolder 操作	Exchange ストア内の指定の場所にフォルダーを作成します。
CreateItem 操作	Exchange ストアに指定したアイテムを作成します。
ExpandDL 操作	配布リストの完全なメンバシップを表示します。
FindConversation 操作	Exchange ストアの指定したフォルダー内のスレッドのリストを列挙します。
FindFolder 操作	指定したフォルダーのサブフォルダーを検索し、一群のサブフォルダーを記述した一群のプロパティを返します。
FindItem 操作	Exchange ストアの指定したフォルダー内にあるアイテムを特定します。
GetConversationItems 操作	スレッドでノードに整理された 1 つまたは複数のアイテムセットを取得します。
GetFolder 操作	Exchange ストアから、指定したプロパティとフォルダーの内容を取得します。
GetItem 操作	Exchange ストアから指定したプロパティとアイテムの内容を取得します。
GetUserAvailability 操作	指定された期間のユーザー、部屋、およびリソースのセットの詳細な空き時間情報を提供します。
MarkAsJunk 操作	電子メールメッセージを [迷惑メール] フォルダーに移動し、それらのメッセージの差出人を受信拒否リストに追加したり、リストから削除したりします。
MoveItem 操作	アイテムを Exchange ストア内の単一のフォルダーに移動します。
ResolveNames 操作	あいまいな電子メールアドレスおよび表示名を解決します。
SendItem 操作	Exchange ストアにある電子メールメッセージを送信します。
UpdateFolder 操作	Exchange ストアの既存のフォルダーのプロパティを変更します。
UpdateItem 操作	Exchange ストアの既存のアイテムのプロパティを変更します。

注:

FAI (フォルダー関連情報) アイテムをアドインから更新 (または作成) することはできません。これらの非表示メッセージはフォルダーに保存され、さまざまな設定と補助データを格納するときに使用されます。 UpdateItem 操作を使用しようとすると、ErrorAccessDenied エラー (「Office 拡張機能はこのような種類のアイテムの更新を許可されていません」) がスローされます。代わりに、EWS マネージ API を使用して、Windows クライアントまたはサーバーアプリケーションからこれらのアイテムを更新することができます。内部の service-type データ構造は変更対象であり、ソリューションが破損する可能性があるため注意してください。

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

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

注:

サーバー管理者は、メソッドが EWS 要求を行えるようにするためにmakeEwsRequestAsync、クライアントアクセスサーバー EWS ディレクトリで OAuthAuthentication パラメーターをにtrue設定するには、New-WebServicesVirtualDirectory コマンドレットまたは Set-WebServicesVirtualDirectory コマンドレットを使用する必要があります。

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

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

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

次の方法で共有

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

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

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

例

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

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

関連項目

フィードバック

その他のリソース