Exchange で EWS を使用して Exchange メールボックスアイテムを操作する

[アーティクル]
03/29/2023

Exchange で EWS マネージ API または EWS を使用して、アイテムを作成、取得、更新、削除する方法について説明します。

EWS マネージ API または EWS を使用すると、メールボックスのアイテムを処理することができます。汎用アイテム (EWS マネージ API の Item オブジェクトや EWS の Item 型) を使用して、いくつかの操作 (アイテム識別子を使用したアイテムの取得や削除) を実行することができます。ただし、ほとんどの場合、取得操作または更新操作を実行するためには、厳密に型指定されたアイテムに固有のプロパティにアクセスする必要があるため、厳密に型指定されたアイテムを使用しなければなりません。

たとえば、汎用アイテムを使用して、開始日と終了日を含むアイテムを取得することはできません。これを行うには、EWS マネージ API の Appointment オブジェクトまたは EWS の CalendarItem 型が必要です。また、EWS マネージ API を使用している場合は、汎用 Item クラスにはコンストラクターがないため、厳密に型指定されたアイテムを常に作成する必要があります。厳密に型指定されていないアイテムを処理する場合は、いつでも、基本 Item クラスを使用してアイテムを処理することができます。

表 1. アイテムを処理するための EWS マネージ API メソッドと EWS 操作

目的	EWS マネージ API メソッド	EWS 操作
汎用アイテムを作成する	なし。 EWS マネージ API を使用してのみ、特定のアイテムの種類を作成できます。ジェネリック項目を作成することはできません。	CreateItem
アイテムを取得する	Item.Bind	GetItem
アイテムを更新する	Item.Update	UpdateItem
アイテムを削除する	Item.Delete	DeleteItem

この記事では、タスクを実行するために、汎用基本クラスを使用する場合と、厳密に型指定されたアイテムを使用する場合とについて説明します。コード例では、基本クラスを使用する方法と、基本クラスを使用できないとき、または基本クラスがニーズに合わないときの対処法を示しています。

EWS マネージ API を使用してアイテムを作成する

EWS マネージ API には Item クラスのパブリックに使用可能なコンストラクターがないため、アイテムを作成するには、作成する特定のアイテムの種類のコンストラクターを使用する必要があります。たとえば、 EmailMessage クラスコンストラクターを使用して新しい電子メールメッセージを作成し、 Contact クラスコンストラクターを使用して新しい連絡先を作成します。同様に、サーバーは応答で汎用 Item オブジェクトを返しません。すべての汎用項目は EmailMessage オブジェクトとして返されます。

作成するアイテムの種類が分かっている場合、わずかな手順だけでタスクを完了できます。この手順は、すべてのアイテムの種類について同様になります。

パラメータとして ExchangeService オプジェクトを持ついずれかの Item クラスの新しいインスタンスを初期化します。
アイテムのプロパティを設定します。スキーマはアイテムの種類ごとに異なるため、利用できるプロパティはアイテムに応じて異なってきます。
アイテムを保存するか、アイテムを保存して送信します。

たとえば、EmailMessage オブジェクトを作成して、 Subject、Body、および ToRecipients の各プロパティを設定し、 EmailMessage.SendAndSaveCopy メソッドを使用して送信できます。

// Create an email message and provide it with connection 
// configuration information by using an ExchangeService object named service.
EmailMessage message = new EmailMessage(service);
// Set properties on the email message.
message.Subject = "Company Soccer Team";
message.Body = "Are you interested in joining?";
message.ToRecipients.Add("sadie@contoso.com");
// Send the email message and save a copy.
// This method call results in a CreateItem call to EWS.
message.SendAndSaveCopy();

EWS マネージ API を使用して会議または予定アイテムを作成する方法については、「Exchange 2013 で EWS を使用して予定と会議を作成する」を参照してください。

EWS を使用してアイテムを作成する

EWS を使用して、汎用アイテムまたは厳密に型指定されたアイテムを作成できます。この手順は、すべてのアイテムの種類について同様になります。

CreateItem 操作を使用して、Exchange ストアのアイテムを作成します。
Items 要素を使用して、作成する 1 つ以上のアイテムを含めます。
アイテムのプロパティを設定します。

たとえば、次の例のコードを使用し、電子メールメッセージを作成して送信できます。これは、SendAndSaveCopy メソッドを呼び出す際に、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:CreateItem MessageDisposition="SendAndSaveCopy">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="sentitems" />
      </m:SavedItemFolderId>
      <m:Items>
        <t:Message>
          <t:Subject>Company Soccer Team</t:Subject>
          <t:Body BodyType="HTML">Are you interested in joining?</t:Body>
          <t:ToRecipients>
            <t:Mailbox>
              <t:EmailAddress>sadie@contoso.com </t:EmailAddress>
              </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

サーバーは、CreateItemResponse メッセージで CreateItem 要求に応答します。このメッセージには、電子メールが正常に作成されたことを示す NoError の ResponseCode 値、および新しく作成されたメッセージの ItemId が含まれます。

EWS を使用して会議または予定アイテムを作成する方法については、「Exchange 2013 で EWS を使用して予定および会議を作成する」を参照してください。

EWS マネージ API を使用してアイテムを取得する

取得するアイテムの Item.Id が分かっている場合に EWS マネージ API を使用してアイテムを取得するには、アイテムに対して Bind メソッドのいずれかを呼び出すだけでアイテムが取得されます。ベストプラクティスとして、必要なものだけを返すようにプロパティを制限することをお勧めします。次の例では、アイテムの Id プロパティと Subject プロパティを返します。

この例では、service が有効な ExchangeService オブジェクトであり、ユーザーが Exchange サーバーに既に認証されていると想定しています。ローカル変数 itemId は、更新する項目の ID です。

// As a best practice, limit the properties returned to only those that are required.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, ItemSchema.Subject);
// Bind to the existing item by using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId, propSet);

特定の条件を満たすアイテムを検索している場合は、次の操作を行います。

取得するアイテムを含むフォルダーにバインドします。
SearchFilter.SearchFilterCollection または PropertySet をインスタンス化して、返すアイテムをフィルターにかけます。
ItemView オブジェクトまたは CalendarView オブジェクトをインスタンス化して、返すアイテムの数を指定します。
ExchangeService.FindItems メソッドまたは ExchangeService.FindAppointments メソッドを呼び出します。

たとえば、受信トレイに未読の電子メールメッセージを取得する場合は、次の例のコードを使用します。この例では、 SearchFilterCollection を使用して FindItems メソッドの結果を未読のメッセージに制限し、 ItemView を制限して結果を 1 つのアイテムに制限します。 EmailMessageSchema.IsRead の値が SearchFilter.の一部であるため、この特定のコードは、 EmailMessage オブジェクトでのみ機能します。

// Bind the Inbox folder to the service object.
Folder inbox = Folder.Bind(service, WellKnownFolderName.Inbox);
// The search filter to get unread email.
SearchFilter sf = new SearchFilter.SearchFilterCollection(LogicalOperator.And, new SearchFilter.IsEqualTo(EmailMessageSchema.IsRead, false));
ItemView view = new ItemView(1);
// Fire the query for the unread items.
// This method call results in a FindItem call to EWS.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, sf, view);

また、次のコード例に示すように、PropertySet を使用して検索結果を制限することもできます。この例では、 FindAppointments メソッドを使用して、次の 30 日間で発生する最大 5 つの予定を取得します。このコードは、予定表アイテムでのみ機能します。

// Initialize values for the start and end times, and the number of appointments to retrieve.
DateTime startDate = DateTime.Now;
DateTime endDate = startDate.AddDays(30);
const int NUM_APPTS = 5;
// Bind the Calendar folder to the service object.
// This method call results in a GetFolder call to EWS.
CalendarFolder calendar = CalendarFolder.Bind(service, WellKnownFolderName.Calendar, new PropertySet());
// Set the start and end time and number of appointments to retrieve.
CalendarView cView = new CalendarView(startDate, endDate, NUM_APPTS);
// Limit the properties returned to the appointment's subject, start time, and end time.
cView.PropertySet = new PropertySet(AppointmentSchema.Subject, AppointmentSchema.Start, AppointmentSchema.End);
// Retrieve a collection of appointments by using the calendar view.
// This method call results in a FindAppointments call to EWS.
FindItemsResults<Appointment> appointments = calendar.FindAppointments(cView);

Bind メソッドの応答でサーバーが返す情報は、 FindItem メソッドまたは FindAppointment メソッドの応答でサーバーが返す情報とは異なります。 Bind メソッドは、すべてのスキーマ化されたプロパティを返すことができますが、 FindItem メソッドと FindAppointment メソッドは、スキーマ化されたすべてのプロパティを返しません。このため、アイテムに対するフルアクセスが必要な場合は、 Bind メソッドを使用する必要があります。取得するアイテムの Id アイテムがない場合は、 FindItem メソッドまたは FindAppointment メソッドを使用して ID を取得し、 Bind メソッドを使用して必要なプロパティを取得します。

EWS マネージ API を使用して会議または予定アイテムを取得する方法については、「Exchange で EWS を使用して予定および会議を取得する」を参照してください。

EWS を使用してアイテムを取得する

取得するアイテムの ItemId が分かっている場合は、GetItem 操作を使用してアイテムを取得できます。

次の例は、特定の ItemId を持つアイテムの件名を取得する XML の要求を示しています。これは、 ItemId で Bind メソッドを呼び出す際に 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="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:GetItem>
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:ItemIds>
        <t:ItemId Id="GJc/NAAA=" />
      </m:ItemIds>
    </m:GetItem>
  </soap:Body>
</soap:Envelope>

次の例は、 GetItem 操作の処理後にサーバーから返される 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:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                       xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:GetItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Items>
            <t:Message>
              <t:ItemId Id="GJc/NAAA=" ChangeKey="CQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAGJd9Z"/>
              <t:Subject>Company Soccer Team</t:Subject>
            </t:Message>
          </m:Items>
        </m:GetItemResponseMessage>
      </m:ResponseMessages>
    </m:GetItemResponse>
  </s:Body>
</s:Envelope>

取得したいアイテムの ItemId が分からない場合は、 FindItem 操作を使用してアイテムを見つけることができます。 FindItem 操作を使用するには、検索しているフォルダーをまず識別する必要があります。 DistinguinguishedFolderName または FolderId を使用して、フォルダーを識別できます。 FindFolder または SyncFolderHierarchy 操作のいずれかを使用して、必要な FolderId を取得することができます。 FindItem 操作を使用して、検索フィルターに一致する結果をそのフォルダーで検索します。 EWS マネージ APIとは異なり、EWS は、予定のための別の検索操作を提供しません。 FindItem 操作がすべての種類のアイテムを取得します。

次の例では、次の 30 日以内に発生する予定表フォルダー内で予定を検索するためにサーバーに送信される XMLの FindItem 操作要求を示しています。読みやすくするため、一部の属性と要素の値が短縮されています。

<?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:FindItem Traversal="Shallow">
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
          <t:FieldURI FieldURI="calendar:Start" />
          <t:FieldURI FieldURI="calendar:End" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:CalendarView MaxEntriesReturned="5" StartDate="2013-10-16T17:04:28.722Z" EndDate="2013-11-15T18:04:28.722Z" />
      <m:ParentFolderIds>
        <t:FolderId Id="AAAEOAAA=" ChangeKey="AgAAABYAAAAqRr3mNdNMSasqx/o9J13UAAAAAAA3" />
      </m:ParentFolderIds>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

サーバーは、操作が正常に完了したことを示す NoError の ResponseCode 値を含む FindItemResponse メッセージで FindItem 要求に応答します。いずれかの予定表アイテムがフィルター条件を満たしている場合は、応答に含まれます。

GetItem 操作の応答でサーバーが返す情報は、 FindItem 操作または FindAppointment 操作の応答でサーバーが返す情報とは異なります。 GetItem 操作は、すべてのスキーマ化されたプロパティを返すことができますが、 FindItem 操作と FindAppointment 操作は、スキーマ化されたすべてのプロパティを返しません。このため、アイテムに対するフルアクセスが必要な場合は、 GetItem 操作を使用する必要があります。取得するアイテムの ItemId がない場合は、 FindItem 操作または FindAppointment 操作を使用して ItemId を取得し、 GetItem 操作を使用して必要な要素を取得します。

EWS を使用して会議または予定アイテムを取得する方法については、「Exchange で EWS を使用して予定および会議を取得する」を参照してください。

EWS マネージ API を使用してアイテムを更新する

EWS マネージ API を使用してアイテムを更新する手順は、すべてのアイテムの種類に似ています。ただし、項目のプロパティはアイテムの種類ごとに異なり、 Update メソッドには多くのオーバーロードされたメソッドから選択できます。アイテムを更新するには:

最新バージョンのアイテムをまだ持っていない場合は、Bind メソッドを使用して取得します。厳密に型指定されたアイテム固有のプロパティを更新するには、その種類のアイテムにバインドする必要があります。汎用アイテムの種類で利用できるプロパティを更新するために、 Item オブジェクトにバインドできます。
アイテムのプロパティを更新します。
Update メソッドを呼び出します。

たとえば、次の例のコードに示すように、汎用アイテムの種類を使用して、電子メールの件名を更新できます。

// Bind to the existing item, using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId);
// Update the Subject of the email.
item.Subject = "New subject";
// Save the updated email.
// This method call results in an UpdateItem call to EWS.
item.Update(ConflictResolutionMode.AlwaysOverwrite);

EWS マネージ API を使用して会議または予定アイテムを更新する方法については、「Exchange で EWS を使用して予定および会議を更新する」を参照してください。

EWS を使用してアイテムを更新する

EWS を使用してアイテムを更新するには、次の操作を行います。

GetItem 操作を使用し、最新バージョンのアイテムをまだ持っていない場合は取得します。
UpdateItem 操作を使用して、更新するフィールドを指定し、それらのフィールドに新しい値を割り当てます。

次の例は、電子メールメッセージの Subject の値を更新するためにサーバーに送信される XML UpdateItem 操作要求を示しています。読みやすくするため、一部の属性と要素の値が短縮されています。

<?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="Exchange2010_SP1" />
  </soap:Header>
  <soap:Body>
    <m:UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite">
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="APdZjAAA=" ChangeKey="CQAAABYAAAAqRr3mNdNMSasqx/o9J13UAAAAPdgr" />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Subject" />
              <t:Message>
                <t:Subject>New subject</t:Subject>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </m:ItemChanges>
    </m:UpdateItem>
  </soap:Body>
</soap:Envelope>

サーバーは、UpdateItemResponse メッセージを含む UpdateItem 要求に応答します。このメッセージには、アイテムが正常に更新されたことを示す、 NoError の ResponseCode 値が含まれます。

EWS を使用して会議または予定アイテムを更新する方法については、「Exchange で EWS を使用して予定および会議を更新する」を参照してください。

EWS マネージ API を使用してアイテムを削除する

アイテムを、削除済みアイテムフォルダーまたはごみ箱に移動して、削除できます。削除するアイテムの ItemId が分かっている場合は、アイテムに対して Delete メソッドを呼び出します。

削除する前にアイテムを検索する必要がある場合は、次の操作を行います。

FindItems メソッドまたは FindAppointments メソッドを呼び出して、削除するアイテムを検索します。
PropertySet をインスタンス化して返すプロパティに制限するか、 SearchFilterCollection を使用して特定のアイテムを検索します。
ItemView または CalendarView をインスタンス化して、返すアイテムの数を指定します。
Delete メソッドを呼び出します。

たとえば次のコードは、電子メールメッセージを、削除済みアイテムフォルダーに移動する方法を示しています。

// Bind to the existing item, using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId);
// Delete the item by moving it to the Deleted Items folder.
// This method call results in a DeleteItem call to EWS.
item.Delete(DeleteMode.MoveToDeletedItems);

アイテムの削除の詳細については、「Exchange で EWS を使用してアイテムを削除する」を参照してください。 EWS マネージ API を使用して会議または予定アイテムを削除する方法については、「Exchange で EWS を使用して、予定を削除し、会議をキャンセルする」を参照してください。

EWS を使用してアイテムを削除する

DeleteItem 操作を使用して、アイテムを削除できます。

次の例は、電子メールメッセージを削除済みアイテムフォルダーに移動するためにサーバーに送信される 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="Exchange2010_SP1" />
  </soap:Header>
  <soap:Body>
    <m:DeleteItem DeleteType="MoveToDeletedItems">
      <m:ItemIds>
        <t:ItemId Id="APdZjAAA=" ChangeKey="CQAAABYAAAAqRr3mNdNMSasqx/o9J13UAAANIFzC" />
      </m:ItemIds>
    </m:DeleteItem>
  </soap:Body>
</soap:Envelope>

サーバーは、DeleteItemResponse メッセージを含む DeleteItem 要求に応答します。このメッセージには、アイテムが正常に更新されたことを示す、 NoError の ResponseCode 値が含まれます。

アイテムの削除の詳細については、「Exchange で EWS を使用してアイテムを削除する」を参照してください。 EWS を使用して会議または予定アイテムを削除する方法については、「Exchange で EWS を使用して、予定を削除し、会議をキャンセルする」を参照してください。

別のメールボックスにアイテムを移動またはコピーする

ExportItems 操作と UploadItems 操作を使用して、メールボックス間でアイテムを移動またはコピーできます。詳細については、「 Exchange で EWS を使用してアイテムをエクスポートおよびインポートする」を参照してください。

Exchange で EWS を使用して Exchange メールボックスアイテムを操作する

EWS マネージ API を使用してアイテムを作成する

EWS を使用してアイテムを作成する

EWS マネージ API を使用してアイテムを取得する

EWS を使用してアイテムを取得する

EWS マネージ API を使用してアイテムを更新する

EWS を使用してアイテムを更新する

EWS マネージ API を使用してアイテムを削除する

EWS を使用してアイテムを削除する

別のメールボックスにアイテムを移動またはコピーする

関連項目

フィードバック

フィードバック

その他のリソース

Exchange で EWS を使用して Exchange メールボックス アイテムを操作する

EWS マネージ API を使用してアイテムを作成する

EWS を使用してアイテムを作成する

EWS マネージ API を使用してアイテムを取得する

EWS を使用してアイテムを取得する

EWS マネージ API を使用してアイテムを更新する

EWS を使用してアイテムを更新する

EWS マネージ API を使用してアイテムを削除する

EWS を使用してアイテムを削除する

別のメールボックスにアイテムを移動またはコピーする

関連項目

フィードバック

フィードバック

その他のリソース

Exchange で EWS を使用して Exchange メールボックスアイテムを操作する