Exchange で EWS を使用して検索フォルダーを操作する
Exchange で EWS マネージ API または EWS を使用して、検索フォルダーを作成、取得、更新、削除する方法について説明します。
検索フォルダーとは、ユーザーのメールボックスにおける永続的で「常時使用可能」な検索機能のことです。 検索フォルダーは、通常のメールボックスのフォルダーと同様の外観で、同じように動作します。 ただし、アイテムそのものが含まれるのではなく、フォルダーに設定されている検索基準と一致する、検索範囲内にあるすべてのフォルダーのアイテムの「仮想」コピーが入っています。 アプリケーションとエンドユーザーのどちらも検索フォルダーを使用できます。 アプリケーションで、同じ検索を繰り返し実行する必要がありますか。 こうしたタスクに関して、検索フォルダーは優れたツールとなります。 ユーザーに対して、クライアントの検索フォルダーにアクセスして管理する機能だけを付与するということも可能です。 どのようなシナリオであっても、EWS マネージ API と EWS を使用して、アプリケーションが検索フォルダーと十分に対話するようにできます。
注:
この記事は、Outlook をオンライン モードで使用する場合にのみ適用されます。 検索フォルダーは同期されません。そのため、オンライン モードで作成された検索フォルダーはキャッシュ モードでは表示されません。
表 1. 検索フォルダーを処理するための EWS マネージ API メソッドと EWS 操作
| 目的… | EWS マネージ API で使用するもの | EWS で使用するもの |
|---|---|---|
| 検索フォルダーを作成する |
SearchFolder.Save |
CreateFolder 操作 |
| 検索フォルダ―を取得する |
SearchFolder.Bind |
GetFolder 操作 |
| 検索フォルダーを更新する |
SearchFolder.Update |
UpdateFolder 操作 |
| 検索フォルダーを削除する |
SearchFolder.Delete |
DeleteFolder 操作 |
検索フォルダーを操作するために把握しておくべき主要な概念
検索フォルダーを操作する前に、検索フィルターのしくみについて理解しておきます。 検索フォルダーは、検索フィルターに基づいて条件を表現します。 検索フォルダー用の検索フィルターは、検索操作用の検索フィルターと同じように構成します。
EWS マネージ API を使用して検索フォルダーを作成する
基本的には、EWS マネージ API を使用して検索フォルダーを作成する方法は、通常のフォルダーを作成する方法と同じです。 ただし、Folder クラスを使用するのではなく、SearchFolder クラスを使用し、SearchParameters プロパティを設定して検索条件を構成します。
次の例では、ユーザーのマネージャー sadie@contoso.comによって送信された受信トレイとそのサブフォルダー内のすべてのメッセージを検索する検索フォルダーが作成されます。 このフォルダーは、ユーザーのメールボックス内に [検索フォルダー] フォルダーの子として作成されます。
注:
ユーザーのメールボックス内の任意のフォルダーの子として検索フォルダーを作成できます。 ただし、新しく作成したフォルダーを Outlook の [検索フォルダー] の下に表示する場合は、[検索フォルダー] の既知のフォルダーの下に作成します。そのためには WellKnownFolderName 列挙体の SearchFolders 値を使用します。
この例では、ExchangeService オブジェクトは Credentials プロパティと Url プロパティの有効な値で初期化されているものとします。
using Microsoft.Exchange.WebServices.Data;
static void CreateSearchFolder(ExchangeService service)
{
// Create the folder.
SearchFolder searchFolder = new SearchFolder(service);
searchFolder.DisplayName = "From Manager";
// Create a search filter to express the criteria
// for the folder.
EmailAddress manager = new EmailAddress("sadie@contoso.com");
SearchFilter.IsEqualTo fromManagerFilter =
new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, manager);
// Set the search filter.
searchFolder.SearchParameters.SearchFilter = fromManagerFilter;
// Set the folder to search.
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
// Set the search traversal. Deep will search all subfolders.
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
// Call Save to make the EWS call to create the folder.
searchFolder.Save(WellKnownFolderName.SearchFolders);
}
EWS を使用して検索フォルダーを作成する
EWS を使用する場合、CreateFolder 操作 に SearchFolder 要素を設定して、検索フォルダーを作成します。 次の要求例では、ユーザーのマネージャー sadie@contoso.comによって送信された受信トレイとそのサブフォルダー内のすべてのメッセージを検索する検索フォルダーが作成されます。 このフォルダーは、ユーザーのメールボックス内の [検索フォルダー] フォルダーに作成されます。
注:
ユーザーのメールボックス内の任意のフォルダーの子として検索フォルダーを作成できます。 ただし、新しく作成したフォルダーを Outlook の [検索フォルダー] の下に表示する場合には、[検索フォルダー] の既知のフォルダーの下に作成します。そのためには DistinguishedFolderId 要素の Id 属性に searchfolders 値を使用します。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="searchfolders" />
</m:ParentFolderId>
<m:Folders>
<t:SearchFolder>
<t:DisplayName>From Manager</t:DisplayName>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="sadie@contoso.com" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
サーバーは、CreateFolderResponse メッセージで応答します。このメッセージには、成功したことを示す、NoError の ResponseCode 値が含まれています。
EWS マネージ API を使用して検索フォルダーを取得する
ExchangeService.FindFolders EWS マネージ API メソッドを使用して、検索フォルダーを検索します。 ただし、結果に検索フォルダーだけを含めることはできません。結果を処理するときにこの点を覚えておくことができます。 SearchFolder.Bind メソッドを使用して、検索フォルダーを取得します。
次の例では、[検索フォルダー] フォルダーの最初の 10 フォルダーを検索します。 それぞれが検索フォルダーかどうかを判別し、検索フォルダーであれば取得して、検索対象のフォルダー数を表示します。
using Microsoft.Exchange.WebServices.Data;
static void GetSearchFolders(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You can't request only search folders in
// a FindFolders request, so other search folders might also be present.
if (folder is SearchFolder)
{
Console.WriteLine("{0} is a search folder.", folder.DisplayName);
// In order to access the SearchParameters property,
// you have to bind to the folder. SearchParameters are not
// returned in FindFolders results.
SearchFolder searchFolder = SearchFolder.Bind(service, folder.Id);
Console.WriteLine("Number of folders searched: {0}.",
searchFolder.SearchParameters.RootFolderIds.Count);
}
else
{
Console.WriteLine("{0} is NOT a search folder.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
EWS を使用して検索フォルダーを取得する
EWS を使用する場合、FindFolder 操作を使用して検索フォルダーを検索し、GetFolder 操作で検索フォルダーを取得します。 検索フォルダーの正常な GetFolder 応答には、SearchFolder 要素が含まれます。 次の要求例は、[検索フォルダー] フォルダーの最初の 10 フォルダーを検索します。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:FindFolder Traversal="Shallow">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:DisplayName" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="searchfolders" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
サーバーは、1 つの検索フォルダーを示す次の応答を返します。
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="712" MinorBuildNumber="22" Version="V2_3"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="3" TotalItemsInView="3" IncludesLastItemInRange="true">
<t:Folders>
<t:SearchFolder>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:DisplayName>From Manager</t:DisplayName>
</t:SearchFolder>
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</m:FindFolderResponse>
</s:Body>
</s:Envelope>
次の要求例では、検索フォルダーを取得する GetFolder 操作要求の先ほどの応答に含まれている FolderId 要素の値を使用します。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:GetFolder>
<m:FolderShape>
<t:BaseShape>AllProperties</t:BaseShape>
</m:FolderShape>
<m:FolderIds>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
サーバーは、以下の応答を、検索フォルダーのファースト クラスのプロパティすべてと一緒に返します。
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="712" MinorBuildNumber="22" Version="V2_3"
xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<m:GetFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:SearchFolder>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:ParentFolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>From Manager</t:DisplayName>
<t:TotalCount>8</t:TotalCount>
<t:ChildFolderCount>0</t:ChildFolderCount>
<t:EffectiveRights>
<t:CreateAssociated>true</t:CreateAssociated>
<t:CreateContents>true</t:CreateContents>
<t:CreateHierarchy>true</t:CreateHierarchy>
<t:Delete>true</t:Delete>
<t:Modify>true</t:Modify>
<t:Read>true</t:Read>
<t:ViewPrivateItems>true</t:ViewPrivateItems>
</t:EffectiveRights>
<t:UnreadCount>0</t:UnreadCount>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="/o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=8d84a3f4cbb34d48838a3aecf99795c0-Sadie" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:FolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
EWS マネージ API を使用して検索フォルダーを更新する
Folder.Update EWS マネージ API メソッドを SearchFolder オブジェクトに対して使用し、検索フォルダーを更新します。 次の例は、「From Manager」という表示名の検索フォルダーの検索条件を更新します。
using Microsoft.Exchange.WebServices.Data;
static void UpdateSearchFolder(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You cannot request only search folders in
// a FindFolders request, so other search folders might also be present.
if (folder is SearchFolder && folder.DisplayName.Equals("From Manager"))
{
Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
SearchFolder searchFolder = folder as SearchFolder;
EmailAddress newManager = new EmailAddress("hope@contoso.com");
SearchFilter.IsEqualTo newManagerFilter =
new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, newManager);
searchFolder.SearchParameters.SearchFilter = newManagerFilter;
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
searchFolder.Update();
Console.WriteLine("\"{0}\" folder updated.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
EWS を使用して検索フォルダーを更新する
EWS を使用する場合、UpdateFolder 操作に SearchFolder 要素を設定して、検索フォルダーを更新します。 次の要求例は、「From Manager」という検索フォルダーの検索条件を更新します。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:UpdateFolder>
<m:FolderChanges>
<t:FolderChange>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:SearchParameters" />
<t:SearchFolder>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="hope@contoso.com" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
サーバーは、UpdateFolderResponse メッセージで応答します。このメッセージには、成功したことを示す、NoError の ResponseCode 値が含まれています。
EWS マネージ API を使用して検索フォルダーを削除する
Folder.Delete EWS マネージ API メソッドを SearchFolder オブジェクトに対して使用し、検索フォルダーを削除します。 次の例は、「From Manager」という表示名の検索フォルダーを削除します。 削除されたフォルダーは、[削除済みアイテム] フォルダーに移動します。
using Microsoft.Exchange.WebServices.Data;
static void DeleteSearchFolder(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You cannot request only search folders in
// a FindFolders request, so other folders might also be present.
if (folder is SearchFolder && folder.DisplayName.Equals("From Manager"))
{
Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
folder.Delete(DeleteMode.MoveToDeletedItems);
Console.WriteLine("\"{0}\" folder deleted.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
EWS を使用して検索フォルダーを削除する
EWS を使用する場合、DeleteFolder 操作を使用して、検索フォルダーを削除します。 次の例は、検索フォルダーを削除し、[削除済みアイテム] フォルダーに移動します。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:DeleteFolder DeleteType="MoveToDeletedItems">
<m:FolderIds>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
</m:FolderIds>
</m:DeleteFolder>
</soap:Body>
</soap:Envelope>
サーバーは、DeleteFolderResponse メッセージで応答します。このメッセージには、成功したことを示す、NoError の ResponseCode 値が含まれています。
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示