Exchange で EWS を使用してフォルダーを操作する
Exchange で EWS マネージ API または EWS を使用して、フォルダーを作成、取得、更新、削除する方法について説明します。
Exchange の EWS は、フォルダーを使用してメールボックスの構成と整理を行います。 EWS マネージ API または EWS を使用して、フォルダーを新規作成、取得、更新、削除できます。 次の表にまとめられている各メソッドまたは操作は、Folder オブジェクト、Folder タイプ、またはいずれかの派生 Folder クラスまたはタイプで実行されます。
表 1. フォルダーを作成、取得、更新、削除するためのメソッドと操作
| 目的 | EWS マネージ API メソッド | EWS 操作 |
|---|---|---|
| フォルダーの作成 | Folder.Save | CreateFolder |
| フォルダー階層の作成 | 利用不可 | CreateFolderPath |
| フォルダーの取得 | Folder.Bind | GetFolder |
| フォルダー階層の取得 | Folder.FindFolders | FindFolder |
| フォルダーの更新 | Folder.Update | UpdateFolder |
| フォルダーの削除 | Folder.Delete | DeleteFolder |
EWS マネージ API を使用してフォルダーを作成する
次のコード例は、Folder クラスを使用して、DisplayName が「Custom Folder」で FolderClass プロパティ値が IPF.Note の汎用フォルダーを新規作成する方法を示しています。 Folder.Save メソッドは、受信トレイ フォルダーの子フォルダーとして対象フォルダーを保存します。
これらの例では、service が有効な ExchangeService オブジェクトであり、ユーザーは Exchange サーバーに既に認証されていると想定しています。
// Create a custom folder.
Folder folder = new Folder(service);
folder.DisplayName = "Custom Folder";
folder.FolderClass = "IPF.Note";
// Save the folder as a child folder of the Inbox.
folder.Save(WellKnownFolderName.Inbox);
CalendarFolder、ContactsFolder、SearchFolder、TasksFolder など異なるタイプのフォルダーを作成するには、特定のクラスの新しいインスタンス (汎用の Folder クラスではなく) を作成し、FolderClass プロパティは設定しません。 たとえば、次のコード例は、新しい TasksFolder を作成する方法を示しています。
// Create a custom Tasks folder.
TasksFolder folder = new TasksFolder(service);
folder.DisplayName = "Custom Tasks";
// Save the folder as a child folder in the Inbox folder.
// This method call results in a CreateFolder call to EWS.
folder.Save(WellKnownFolderName.Inbox);
特定のクラスのインスタンスを作成し、同時に FolderClass プロパティも設定すると、ErrorNoFolderClassOverride エラーがスローされます。
EWS マネージ API を使用して、1 回のメソッド呼び出しで複数のフォルダーの作成をバッチ操作することはできません。
EWS を使用してフォルダーを作成する
EWS を使用すると、1 つまたは複数のフォルダーを作成できます。
1 つのフォルダーを作成するには、CreateFolder 操作要求メッセージを送信します。 この CreateFolder 操作要求は、親フォルダーが受信トレイで、DisplayName が「Custom Folder」であること、および FolderClass 要素の値が IPF.Note であることを示します。
これは、新しいフォルダーが作成されて Folder.Save メソッドが呼び出されると、EWS マネージ API が送信する XML 要求でもあります。
<?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" />
</soap:Header>
<soap:Body>
<m:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="inbox" />
</m:ParentFolderId>
<m:Folders>
<t:Folder>
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>Custom Folder</t:DisplayName>
</t:Folder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
サーバーは、CreateFolder 要求に CreateFolderResponse メッセージで応答します。このメッセージには、ResponseCode 値 NoError (フォルダーが正常に作成されたことを示します)、および新しく作成されたメッセージの FolderId が含まれます。
複数のフォルダーを作成するには、複数の Folder 要素を CreateFolder 操作要求メッセージに含めます。 すべての新しいフォルダーの親フォルダーは同じでなければなりません。
EWS を使用してフォルダー階層を作成する
EWS CreateFolderPath 操作を使用すると、1 回の呼び出しで 1 つのフォルダー階層を作成できます。 この機能は、EWS マネージ API では利用できません。 代わりに、EWS マネージ API を使用している場合には「EWS を使用してフォルダーを作成する」に記されているようにフォルダーを 1 つずつ作成できます。
注:
EWS マネージ API はこの機能を実装していません。
EWS マネージ API を使用してフォルダーを取得する
次のコード例は、Folder.Bind メソッドを使用して受信トレイ フォルダーを取得する方法を示しています。 ベスト プラクティスとして、アプリケーションで必要なものだけを返すようにプロパティを制限します。 この例の場合、返されるプロパティに含まれるのは、Id プロパティだけになるよう制限しています。そのために、PropertySet オブジェクトを作成し、IdOnly 値を BasePropertySet プロパティに適用しています。
この例では、service が有効な ExchangeService オブジェクトであり、ユーザーが Exchange サーバーに既に認証されていると想定しています。
// As a best practice, limit the properties returned to only those that are required.
// In this scenario, you only need the FolderId.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get only the properties specified in the PropertySet.
// This method call results in a GetFolder call to EWS.
Folder rootfolder = Folder.Bind(service, WellKnownFolderName.Inbox, propSet);
他のプロパティを返す必要がある場合、FolderSchema クラスのプロパティを PropertySet に追加するか、すべてのファースト クラス プロパティを返すオーバーロードされた Bind メソッドを使用します。
EWS マネージ API を使用して 1 度に複数のフォルダーは取得できないことに注意してください。 フォルダーごとに Bind メソッドを呼び出す必要があります。
EWS を使用してフォルダーを取得する
EWS を使用すると、1 つまたは複数のフォルダーを取得できます。
1 つのフォルダーを取得するには、GetFolder 操作要求メッセージをサーバーに送信します。 次の例では、BaseShape が IdOnly に設定されているため、指定したフォルダーの FolderId のみが返されます。 この FolderIds 要素は、取得するフォルダーが受信トレイ フォルダーであることを示します。
これは、Folder.Bind メソッドを使用して 1 つのフォルダーにバインドされるときに、EWS マネージ API が送信する XML 要求でもあります。
複数のフォルダーを取得するには、複数の FolderIds 要素を GetFolder 操作要求メッセージに含めます。
<?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" />
</soap:Header>
<soap:Body>
<m:GetFolder>
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
</m:FolderShape>
<m:FolderIds>
<t:DistinguishedFolderId Id="inbox" />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
次の XML の例は、GetFolder 操作要求に対する応答として、サーバーからクライアントに送信される GetFolderResponse メッセージを示しています。 受信トレイ フォルダーの FolderId 値のみが入っています。 読みやすくするため、一部の属性と要素の値が短縮されています。
<?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="800"
MinorBuildNumber="16"
Version="V2_6"
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:Folder>
<t:FolderId Id="AAAENAAA=" ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAEkbCr"/>
</t:Folder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
EWS マネージ API を使用してフォルダー階層を取得する
次のコード例は、指定したルート フォルダーのサブフォルダーを取得する方法を示します。 この例では、MsgFolderRoot (IPM サブツリーのルート) のサブフォルダーを取得します。IPM サブツリーにはメールボックス フォルダーとアイテムが格納されます。
この例では、FolderView クラス オブジェクトが作成されて、Folder.FindFolders メソッドの応答結果が制限されています。 このシナリオでは、Id、DisplayName、およびフォルダーが隠しフォルダーかどうかを示す拡張プロパティを返すよう、プロパティを制限しています。 FolderView.Traversal 値を Deep に設定してサーバーがサブフォルダーを取得できるように再帰的検索を実行しています。また、ルート フォルダーを MsgFolderRoot に設定し、サーバーがすべてのユーザー フォルダーを返しています (サーバーは非 IPM サブツリーのシステム フォルダーは返しません)。
この例では、service が有効な ExchangeService オブジェクトであり、ユーザーが Exchange サーバーに既に認証されていると想定しています。
// Create a new folder view, and pass in the maximum number of folders to return.
FolderView view = new FolderView(folderViewSize);
// Create an extended property definition for the PR_ATTR_HIDDEN property,
// so that your results will indicate whether the folder is a hidden folder.
ExtendedPropertyDefinition isHiddenProp = new ExtendedPropertyDefinition(0x10f4, MapiPropertyType.Boolean);
// As a best practice, limit the properties returned to only those required.
// In this case, return the folder ID, DisplayName, and the value of the isHiddenProp
// extended property.
view.PropertySet = new PropertySet(BasePropertySet.IdOnly, FolderSchema.DisplayName, isHiddenProp);
// Indicate a Traversal value of Deep, so that all subfolders are retrieved.
view.Traversal = FolderTraversal.Deep;
// Call FindFolders to retrieve the folder hierarchy, starting with the MsgFolderRoot folder.
// This method call results in a FindFolder call to EWS.
FindFoldersResults findFolderResults = service.FindFolders(WellKnownFolderName.MsgFolderRoot, view);
EWS を使用してフォルダー階層を取得する
次の XML の例は、FindFolder 操作を使用して EWS でフォルダー階層を取得する方法を示しています。 この例では、IPM サブツリーのルートである msgfolderroot フォルダーとそのサブフォルダーすべてが取得されます。 Traversal 属性が Deep に設定されているので、サーバーはフォルダー階層の再帰的検索を実行し、応答で指定のルート下にあるフォルダーとサブフォルダーのみを返します。 この例では、BaseShape 要素が IdOnly に設定されているため、サーバーは FolderId 要素のみを返します。 出力を分かりやすくするために、DisplayName 要素を要求の AdditionalProperties 要素に含めて結果にこの要素を含めています。同時に、PR_ATTR_HIDDEN プロパティの ExtendedFieldURI 値も含めて、フォルダーが隠しフォルダーかどうかがわかるようにしています。
これは、FindFolders メソッドが呼びされるときに EWS マネージ API が送信する XML 要求でもあります。
<?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" />
</soap:Header>
<soap:Body>
<m:FindFolder Traversal="Deep">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:ExtendedFieldURI PropertyTag="4340"
PropertyType="Boolean" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="100"
Offset="0"
BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="msgfolderroot" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
次の XML の例は、FindFolder 操作要求に対する応答として、サーバーからクライアントに送信される FindFolderResponse メッセージを示しています。 含まれているのは、msgrootfolder フォルダーのすべてのサブフォルダーに関する FolderId、DisplayName、および PR_ATTR_HIDDEN 拡張プロパティ値のみです。 Value 要素が true に設定されていると、フォルダーはクライアント ビューで非表示になっています。
これは、FindFolder メソッドを使用して複数のフォルダーが取得されるときに、EWS マネージ API が送信する XML 応答でもあります。 読みやすいように、いくつかの属性と要素の値に短縮されていて、簡略化するために含まれていないフォルダーもあります。
<?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="815"
MinorBuildNumber="6"
Version="V2_7"
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="16"
TotalItemsInView="16"
IncludesLastItemInRange="true">
<t:Folders>
<t:CalendarFolder>
<t:FolderId Id="AAAEOAAA="
ChangeKey="AgAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA3"/>
<t:DisplayName>Calendar</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:CalendarFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAEPAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAA4"/>
<t:DisplayName>Contacts</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>false</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:ContactsFolder>
<t:FolderId Id="AAAUKAAA="
ChangeKey="AwAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAAS5"/>
<t:DisplayName>Recipient Cache</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:ContactsFolder>
<t:Folder>
<t:FolderId Id="AAAUJAAA="
ChangeKey="AQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAAAASx"/>
<t:DisplayName>Conversation Action Settings</t:DisplayName>
<t:ExtendedProperty>
<t:ExtendedFieldURI PropertyTag="0x10f4"
PropertyType="Boolean"/>
<t:Value>true</t:Value>
</t:ExtendedProperty>
</t:Folder>
…
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</m:FindFolderResponse>
</s:Body>
</s:Envelope>
EWS マネージ API を使用してフォルダーを更新する
次のコード例は、EWS マネージ API を使用してフォルダーの表示名を更新する方法を示しています。
最初に、PropertySet プロパティを作成して、サーバーが Folder.Bind 応答で返すプロパティの数を限定します。 IdOnlyBasePropertySet を使用して Exchange データベースに対する呼び出しを減らすようお勧めします。 次に、Bind メソッドを使用してフォルダーを更新します。 その後、DisplayName プロパティを更新し、Folder.Update メソッドによって変更を保存します。
この例では、service が有効な ExchangeService オブジェクトで、ユーザーは Exchange サーバーに既に認証されていると想定しています。 ローカル変数 folderId は、更新するフォルダーの ID です 。
// As a best practice, only include the ID value in the PropertySet.
PropertySet propertySet = new PropertySet(BasePropertySet.IdOnly);
// Bind to an existing folder and get the FolderId.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId, propertySet);
// Update the display name of the folder.
folder.DisplayName = "Updated folder name";
// Save the updates.
// This method call results in an UpdateFolder call to EWS.
folder.Update();
EWS を使用してフォルダーを更新する
次のコード例は、EWS を使用してフォルダーの表示名を更新する方法を示しています。
最初に、「EWS を使用してフォルダー階層を取得する」に記されているように、更新対象フォルダーを取得するために GetFolder 操作要求メッセージを送信します。
次に、フォルダーを更新する UpdateFolder 操作要求メッセージをサーバーに送信します。 この UpdateFolder 操作要求は、DisplayName を「Updated Custom Folder」に更新します。
これは、Folder.Update メソッドを使用して 1 つのフォルダーが更新されるときに、EWS マネージ API が送信する XML 要求でもあります。 読みやすくするため、一部の属性と要素の値が短縮されています。
<?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" />
</soap:Header>
<soap:Body>
<m:UpdateFolder>
<m:FolderChanges>
<t:FolderChange>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWb" />
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:DisplayName" />
<t:Folder>
<t:DisplayName>Updated Custom Folder</t:DisplayName>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
サーバーは UpdateFolder 要求に UpdateFolderResponse メッセージで応答します。このメッセージには、ResponseCode 値として NoError、および ChangeKey 属性値で更新されたフォルダーの FolderId が含まれています。
EWS マネージ API を使用してフォルダーを削除する
この資料では、EWS マネージ API を使用してフォルダーを削除する基本的な方法の例を示します。 フォルダーの削除について詳しくは、「Exchange の EWS を使用するアイテムの削除」をご覧ください。
EWS マネージ API を使用してフォルダーを削除するには、最初に Folder.Bind メソッドを使用してサービス オブジェクトを、削除対象フォルダーにバインドします。 次に、Folder.Delete メソッドを使用してフォルダーを削除します。そのためには、HardDelete 削除モードを使用します。
この例では、service が有効な ExchangeService オブジェクトであり、ユーザーが Exchange サーバーに既に認証されていると想定しています。 ローカル変数 folderId は、削除するフォルダーの ID です 。
// Bind to an existing folder and get all its properties.
// This method call results in a GetFolder call to EWS.
Folder folder = Folder.Bind(service, folderId);
// HardDelete the folder.
// This method call results in a DeleteFolder call to EWS.
folder.Delete(DeleteMode.HardDelete);
EWS を使用してフォルダーを削除する
この資料では、EWS を使用してフォルダーを削除する基本的な方法の XML 例を示します。 フォルダーの削除について詳しくは、「Exchange の EWS を使用するアイテムの削除」をご覧ください。
EWS を使用してフィルダーを削除するには、最初に、「EWS を使用してフォルダーを取得する」に記されているように、更新対象フォルダーを取得するために GetFolder 操作要求メッセージを送信します。
次に、フォルダーを削除する DeleteFolder 操作要求メッセージをサーバーに送信します。 DeleteFolder 操作要求は DeleteType が HardDelete であることを示し、削除するフォルダーの FolderId が含まれています。
また、これは Folder.Delete メソッドを使用して 1 つのフォルダーが削除されるときに、EWS マネージ API が送信する XML 要求でもあります。 読みやすくするため、一部の属性と要素の値が短縮されています。
<?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" />
</soap:Header>
<soap:Body>
<m:DeleteFolder DeleteType="HardDelete">
<m:FolderIds>
<t:FolderId Id="OrV9ZAAA=" ChangeKey="AQAAABYAAABVzRdyy/cHS4XTC9itCRdUAAAOrXWf" />
</m:FolderIds>
</m:DeleteFolder>
</soap:Body>
</soap:Envelope>
サーバーは、DeleteFolder 要求に対して DeleteFolderResponse メッセージで応答します。このメッセージには、ResponseCode 値として、フォルダーが正常に削除されたことを示す NoError が含まれます。
次の手順
サーバー上のフォルダーを取得するか、フォルダーに変更を加えた後、フォルダー階層を同期するか、サーバーにおけるフォルダーの変更についての通知を購読することもできます。
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示