Exchange で EWS を使用して予定表に代理人としてアクセスする

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

Exchange で EWS マネージ API または EWS を使用して予定表に代理人としてアクセスする方法について説明します。

EWS マネージ API または EWS を使用して、メールボックス所有者の予定表フォルダーへの代理人アクセス権をユーザーに付与できます。そうすることにより代理人は、アクセス許可に応じて、メールボックス所有者の代理としての会議出席依頼の作成、予定の作成、会議出席依頼への応答、メールボックス所有者の予定表フォルダーにある会議の取得、更新、および削除を行えます。

代理人として、独自の予定表フォルダーへのアクセスに使用するメールボックス所有者の予定表フォルダーにアクセスする場合と同じ方法と操作を使用します。主な違いは、予定表アイテムまたは予定表サブフォルダーを検索または作成するために明示的なアクセスを使用する必要があり、アイテム ID またはフォルダー ID を特定した後、暗黙的なアクセスを使用してアイテムを取得、更新、または削除できることです。

表 1. 代理人として予定表にアクセスするための EWS マネージ API メソッドと EWS 操作

目的	使用する EWS マネージ API メソッド…	使用する EWS 操作…
会議または予定を代理人として作成する	Appointment.Save: FolderId パラメーターがメールボックス所有者の予定表フォルダーへの明示的なアクセスを提供する	CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する
複数の会議または予定を代理人として作成する	ExchangeService.CreateItems: FolderId パラメーターがメールボックス所有者の予定表フォルダーに明示的なアクセスを提供する	CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する
予定または会議を代理人として検索または検出する	ExchangeService.FindItems: FolderId パラメーターがメールボックス所有者の予定表フォルダーに明示的なアクセスを提供する	FindItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する
予定または会議を代理人として取得する	Appointment.Bind	GetItem
予定または会議を代理人として更新する	Appointment.Bind の後に Appointment.Update	GetItem の後に UpdateItem
予定または会議を代理人として削除する	Appointment.Bind の後に Appointment.Delete	GetItem の後に DeleteItem

注:

この記事のコード例では、 primary@contoso.com はメールボックスの所有者です。

事前に必要なタスク

ユーザーが代理人としてメールボックス所有者の予定表フォルダーにアクセスするためには、そのユーザーは、メールボックス所有者の予定表フォルダーに、アクセス許可を持つ代理人として追加されていなければなりません。

代理人は、メールボックス所有者の予定表を更新するには、自身のアカウントにアタッチされたメールボックスが必要です。

代理人が会議出席依頼と応答だけを処理すればよい場合は、予定表フォルダーに代理人を追加し、既定の MeetingRequestsDeliveryScope.DelegatesAndSendInformationToMe EWS マネージ API 列挙値または DeliverMeetingRequests EWS 要素値 DelegatesAndSendInformationToMe を使用して、出席依頼を代理人に送信し、情報メッセージをメールボックス所有者に送信します。こうすると、メールボックス所有者の受信トレイフォルダーへのアクセス権を代理人に付与する必要はありません。

EWS マネージ API を使用して会議または予定を代理人として作成する

EWS マネージ API を使用すると、代理ユーザーのサービスオブジェクトを使用して、メールボックス所有者の予定表アイテムを作成できます。この例は、Save メソッドを使用して会議を作成し、出席者に会議出席依頼を送信する方法を示しています。

この例では、service が代理人の有効な ExchangeService オブジェクトであり、メールボックス所有者の予定表フォルダーに対する適切なアクセス許可が代理人に付与されいることを前提にしています。

private static void DelegateAccessCreateMeeting(ExchangeService service)
{
    Appointment meeting = new Appointment(service);
    // Set the properties on the meeting object to create the meeting.
    meeting.Subject = "Team building exercise";
    meeting.Body = "Let's learn to really work as a team and then have lunch!";
    meeting.Start = DateTime.Now.AddDays(2);
    meeting.End = meeting.Start.AddHours(4);
    meeting.Location = "Conference Room 12";
    meeting.RequiredAttendees.Add("sadie@contoso.com");
    meeting.ReminderMinutesBeforeStart = 60;
    // Save the meeting to the Calendar folder for 
    // the mailbox owner and send the meeting request.
    // This method call results in a CreateItem call to EWS.
    meeting.Save(new FolderId(WellKnownFolderName.Calendar, 
        "primary@contoso.com"), 
        SendInvitationsMode.SendToAllAndSaveCopy);
    // Verify that the meeting was created.
    Item item = Item.Bind(service, meeting.Id, new PropertySet(ItemSchema.Subject));
    Console.WriteLine("\nMeeting created: " + item.Subject + "\n");
}

アイテムの保存時には、Save メソッド呼び出しでメールボックス所有者の予定表フォルダーを識別する必要があることにご注意ください。メールボックス所有者の予定表フォルダーを指定しない場合、会議出席依頼はメールボックス所有者の予定表フォルダーではなく、代理人の予定表フォルダーに保存されます。メールボックス所有者の予定表フォルダーは、2 つの方法で Save メソッド呼び出しに含めることができます。メールボックス所有者の WellKnownFolderName と SMTP アドレスを使用して、FolderId オブジェクトの新しいインスタンスをインスタンス化することをお勧めします。

meeting.Save(new FolderId(WellKnownFolderName.Calendar,
    "primary@contoso.com"), SendInvitationsMode.SendToAllAndSaveCopy);

ただし、最初に予定表フォルダーに Bind してから、Save メソッド呼び出しでフォルダーの ID を使用することもできます。ただし、これにより追加の EWS 呼び出しが作成されることにご注意ください。

    // Identify the mailbox owner's SMTP address
    // and bind to their Calendar folder.
    Mailbox primary = new Mailbox("primary@contoso.com"); 
    Folder primaryCalendar = Folder.Bind(service, 
        new FolderId(WellKnownFolderName.Calendar, primary)); 
…
    // Save the meeting to the Calendar folder for the mailbox owner and send the meeting request.
    meeting.Save(primaryCalendar.Id, 
        SendInvitationsMode.SendToAllAndSaveCopy);

EWS を使用して会議または予定を代理人として作成する

EWS を使用すると、代理ユーザーのサービスオブジェクトを使用して、メールボックス所有者の予定表アイテムを作成できます。この例は、CreateItem 操作を使用して会議を作成し、出席者に会議出席依頼を送信する方法を示しています。

これは、Save メソッドを使用して会議または予定を代理人として作成する場合に EWS マネージ API が送信する XML 要求でもあります。

簡潔にするために、次の例では SOAP ヘッダーが削除されています。

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
         xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
         xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
…
  <soap:Body>
    <m:CreateItem SendMeetingInvitations="SendToAllAndSaveCopy">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="calendar">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:SavedItemFolderId>
      <m:Items>
        <t:CalendarItem>
          <t:Subject>Team building exercise</t:Subject>
          <t:Body BodyType="HTML">Let's learn to really work as a 
              team and then have lunch!</t:Body>
          <t:ReminderMinutesBeforeStart>60</t:ReminderMinutesBeforeStart>
          <t:Start>2014-03-09T23:26:33.756-05:00</t:Start>
          <t:End>2014-03-10T03:26:33.756-05:00</t:End>
          <t:Location>Conference Room 12</t:Location>
          <t:RequiredAttendees>
            <t:Attendee>
              <t:Mailbox>
                <t:EmailAddress>sadie@contoso.com</t:EmailAddress>
              </t:Mailbox>
            </t:Attendee>
          </t:RequiredAttendees>
        </t:CalendarItem>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

サーバーは、会議が正常に作成されたことを示す NoError の ResponseCode 要素値を含む CreateItemResponse メッセージで CreateItem 要求に応答します。応答には、新しく作成された会議のアイテム ID も含まれます。

EWS マネージ API を使用して会議または予定を代理人として検索する

会議を検索するには、メールボックス所有者の予定表フォルダーを指定するために、FolderId パラメーターが含まれるいずれかの ExchangeService.FindItems メソッドを使用する必要があります。

static void DelegateAccessSearchWithFilter
    (ExchangeService service, SearchFilter filter)
{
    // Limit the result set to 10 items.
    ItemView view = new ItemView(10);
    view.PropertySet = new PropertySet(ItemSchema.Subject,
                                       ItemSchema.DateTimeReceived,
                                       EmailMessageSchema.IsRead);
    // Item searches do not support deep traversal.
    view.Traversal = ItemTraversal.Shallow;
    // Define the sort order.
    view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);
    try
    {
        // Call FindItems to find matching calendar items. 
        // The FindItems parameters must denote the mailbox owner,
        // mailbox, and Calendar folder.
        // This method call results in a FindItem call to EWS.
        FindItemsResults<Item> results = service.FindItems(
        new FolderId(WellKnownFolderName.Calendar, 
            "primary@contoso.com"), 
            filter, 
            view);
        foreach (Item item in results.Items)
        {
            Console.WriteLine("Subject: {0}", item.Subject);
            Console.WriteLine("Id: {0}", item.Id.ToString());
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while 
            enumerating results: {0}", ex.Message);
    }
}

FindItems 呼び出しが ID を含む応答を返すと、ID と暗黙的アクセスを使用して対象の会議を取得、更新、削除できます。その際、メールボックス所有者の SMTP アドレスを指定する必要はありません。

EWS を使用して会議または予定を代理人として検索する

EWS を使用すると、代理ユーザーのサービスオブジェクトを使用して、検索条件のセットに一致する予定および会議を検索できます。この例は、FindItem 操作を使用して、メールボックス所有者の予定表フォルダーの中で件名に "building" という単語が含まれる会議を検索する方法を示しています。

これは、FindItem メソッドを使用して会議または予定を代理人として検索する場合に EWS マネージ API が送信する XML 要求でもあります。

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://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="item:DateTimeReceived" />
          <t:FieldURI FieldURI="message:IsRead" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:IndexedPageItemView MaxEntriesReturned="10"
                             Offset="0"
                             BasePoint="Beginning" />
      <m:Restriction>
        <t:Contains ContainmentMode="Substring"
                    ContainmentComparison="IgnoreCase">
          <t:FieldURI FieldURI="item:Subject" />
          <t:Constant Value="building" />
        </t:Contains>
      </m:Restriction>
      <m:SortOrder>
        <t:FieldOrder Order="Descending">
          <t:FieldURI FieldURI="item:DateTimeReceived" />
        </t:FieldOrder>
      </m:SortOrder>
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="calendar">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:ParentFolderIds>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

サーバーは、検索が正常に完了したことを示す NoError の ResponseCode 要素値を含む FindItemResponse メッセージで FindItem 要求に応答します。応答には、検索条件を満たす予定または会議の CalendarItem が含まれています。この場合、1 つの会議のみが見つかります。

ItemId 要素の値は読みやすいよう短縮されています。

<?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="893"
                         MinorBuildNumber="10"
                         Version="V2_10"
                         xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="http://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>
    <m:FindItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
                        xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="1"
                        TotalItemsInView="1"
                        IncludesLastItemInRange="true">
            <t:Items>
              <t:CalendarItem>
                <t:ItemId Id="IJpUAAA="
                          ChangeKey="DwAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAAAIKhS" />
                <t:Subject>Team building exercise</t:Subject>
                <t:DateTimeReceived>2014-03-04T21:27:22Z</t:DateTimeReceived>
              </t:CalendarItem>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </m:FindItemResponse>
  </s:Body>
</s:Envelope>

条件と一致する会議の ItemId が分かったので、ItemId と暗黙的なアクセスを使用して、会議の取得、更新、削除を行えます。その際、メールボックス所有者の SMTP アドレスを指定する必要はありません。

EWS マネージ API を使用して予定表アイテムを代理人として取得、更新、または削除する

EWS マネージ API を使用して、代理人アクセスを使用しない場合と同じ方法で、会議または予定を取得、更新、または削除できます。唯一の違いは、サービスオブジェクトが代理ユーザーを対象にしている点です。 Bind メソッド呼び出しに含まれるアイテム ID は、メールボックス所有者の予定表フォルダー内のメールボックスストアにあるアイテムを一意に識別します。

表 2. 予定および会議を代理人として処理するための EWS マネージ API メソッド

タスク	EWS マネージ API メソッド	コード例
予定または会議を取得する	Bind	EWS マネージ API を使用してアイテムを取得する
予定または会議を更新する	Bind の後に Update	EWS マネージ API を使用して会議を更新する
予定または会議を削除する	Bind の後に Delete	EWS マネージ API を使用して会議を削除する

EWS を使用して予定表アイテムを代理人として取得、更新、または削除する

EWS を使用して、代理人アクセスを使用しない場合と同じ方法で、会議または予定を取得、更新、または削除できます。唯一の違いは、サービスオブジェクトが代理ユーザーを対象にしている点です。 GetItem メソッド呼び出しに含まれるアイテム ID は、メールボックス所有者の予定表フォルダー内のメールボックスストアにあるアイテムを一意に識別します。

表 3. 予定および会議を代理人として処理するための EWS 操作

タスク	EWS 操作	コード例
予定または会議を取得する	GetItem	EWS を使用してアイテムを取得する
予定または会議を更新する	GetItem の後に UpdateItem	EWS を使用して会議を更新する
予定または会議を削除する	GetItem の後に DeleteItem	EWS を使用して会議を削除する

次の方法で共有