Работа с элементами почтовых ящиков Exchange с помощью веб-служб Exchange

Статья
06/01/2021

Узнайте, как создавать, получать, редактировать и удалять элементы с помощью управляемого API EWS или служб EWS в Exchange.

Вы можете работать с элементами в почтовом ящике с помощью управляемого API EWS или веб-служб Exchange. Вы можете использовать универсальные элементы — объекты или типы элементов EWS для выполнения некоторых операций (получения или удаления элемента по его идентификатору). Однако для получения и обновления элементов чаще всего приходится использовать строго типизированные элементы, так как вам потребуется доступ к свойствам, относящимся к строго типизированному элементу.

Например, с помощью универсального элемента невозможно получить элемент, содержащий даты начала и окончания — для этого потребуется объект управляемого API EWS Appointment или тип CalendarItem. А если вы используете управляемый API EWS, то создавать строго типизированные элементы необходимо в любом случае, так как у класса универсального **элемента ** нет конструктора. Для работы с элементом, не являющимся строго типизированным, всегда можно использовать класс базового элемента.

Таблица 1. Методы управляемого API EWS и операции EWS для работы с элементами

Задача	Метод управляемого API EWS	Операция служб EWS
Создание универсального элемента	Нет. С помощью управляемого API EWS можно создавать только элементы определенных типов. Создавать универсальные элементы невозможно.	CreateItem
Получение элемента	Item.Bind	GetItem
Обновление элемента	Item.Update	UpdateItem
Удаление элемента	Item.Delete	DeleteItem

Из этой статьи вы узнаете, когда для выполнения задачи можно использовать универсальный базовый класс, а в каких случаях необходимо применять строго типизированный элемент. В примерах кода показано, как использовать базовый класс и что делать, если использовать базовый класс невозможно или он не соответствует вашим потребностям.

Создание элемента с помощью управляемого API EWS

В управляемом API EWS нет общедоступного конструктора для класса элемента, поэтому потребуется использовать конструктор конкретного типа, который необходим для создания элемента. Например, с помощью конструктора класса EmailMessage можно создать новое сообщение электронной почты и с помощью конструктора класса контактов Contact можно создавать новые контакты. Аналогичным образом, сервер никогда не возвращает в ответах объекты универсального элемента. Все универсальные элементы возвращаются в виде объектов EmailMessage.

Если вы знаете тип создаваемого элемента, выполнить задачу можно всего за несколько этапов. Действия одинаковы для всех типов элементов:

Инициализируйте новый экземпляр одного из классов элемента с объектом ExchangeService в качестве параметра.
Задайте свойства элемента. Для всех типов элементов используются разные схемы, поэтому для разных элементов доступны разные свойства.
Сохраните элемент или сохраните и отправьте его.

Например, вы можете создать объект 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();

Сведения о том, как создать элемент собрания или встречи с помощью управляемого API EWS, см. в статье Create appointments and meetings by using EWS in Exchange 2013.

Создание элемента с помощью веб-служб Exchange

С помощью EWS можно создать универсальный или строго типизированный элемент. Действия одинаковы для всех типов элементов.

Создайте элемент в хранилище Exchange с помощью операции CreateItem.
Используйте элемент Items в качестве контейнера для одного или нескольких создаваемых элементов.
Задайте свойства элемента.

Например, вы можете создать электронное сообщение и отправить его с помощью кода из представленного ниже примера. Управляемое API EWS также отправляет запрос XML при вызове метода SendAndSaveCopy.

<?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>

В ответ на запрос CreateItem сервер отправляет сообщение CreateItemResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что сообщение было успешно создано, и свойство ItemId созданного сообщения.

Сведения о том, как создать собрание или встречу с помощью EWS, см. в статьеCreate appointments and meetings by using EWS in Exchange 2013.

Получение элемента с помощью управляемого API EWS

Чтобы использовать управляемое API EWS для получения элемента, если вы знаете свойство Item.Id получаемого элемента, необходимо просто вызвать один из методов Bind в элементе, после чего элемент будет получен. Рекомендуем возвращать только обязательные свойства. В этом примере возвращаются свойства Id элемента и Subject.

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server. Локальная переменная itemId является идентификатором обновляемого элемента.

// 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 результаты можно сократить до одного элемента. Этот конкретный код работает только в объектах EmailMessage объекты, поскольку значение EmailMessageSchema.IsRead является частью SearchFilter.

// 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 дней. Конечно, этот код работает только с элементами календаря.

// 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.

Сведения о том, как получить элемент собрания или встречи с помощью управляемого API EWS, см. в статье Get appointments and meetings by using EWS in Exchange.

Получение элемента с помощью EWS

Если вам известно значение свойства ItemId получаемого элемента, то вы можете получить его с помощью операции GetItem.

В приведенном ниже примере показан XML-запрос на получение свойства Subject элемента с определенным значением свойства ItemId. Управляемое API EWS также отправляет запрос XML при вызове метода Bind на ItemId. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?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>

В приведенном ниже примере показан XML-ответ, возвращаемый сервером после обработки операции GetItem. Ответ указывает, что элемент был успешно получен. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?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 найдите в папке результаты, соответствующие фильтру поиска. В отличие от управляемого API EWS, в веб-службах Exchange нет отдельной операции поиска для встреч. Операция FindItem получает элементы всех типов.

В приведенном ниже примере показан XML-запрос с операцией FindItem, отправляемый на сервер для поиска в папке Calendar встреч, назначенных на следующие 30 дней. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?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>

В ответ на запрос FindItem сервер возвращает сообщение FindItemResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что операция успешно выполнена. Если какие-либо элементы календаря отвечают условиям фильтра, они включаются в ответ.

Обратите внимание, что данные, возвращаемые сервером в ответ на вызов операции GetItem, отличаются от аналогичных данных для операций FindItem или FindAppointment. Операция GetItem может возвращать все схематизированные свойства, в то время как операции FindItem и FindAppointment возвращают не все из этих свойств. Следовательно, если вам нужен полный доступ к элементу, то необходимо использовать операцию GetItem. Если вам неизвестно значение свойства ItemId получаемого элемента, используйте операции FindItem или FindAppointment, чтобы получить свойство ItemId, а затем получите необходимые элементы с помощью операции GetItem.

Сведения о том, как получить элемент собрания или встречи с помощью EWS, см. в статье Get appointments and meetings by using EWS in Exchange.

Изменение элемента с помощью управляемого API EWS

Действия для изменения элемента с помощью управляемого API EWS одинаковы для всех типов элементов. Однако элементы разных типов содержат разные свойства, а для метода Update доступно множество перегруженных методов. Чтобы обновить элемент, сделайте следующее:

Получите последнюю версию элемента (если ее у вас еще нет) с помощью метода Bind. Чтобы редактировать свойства, относящиеся к строго типизированному элементу, необходимо выполнить привязку к типу этого элемента. Чтобы изменить свойства, доступные для типа универсальный элемента, вы можете выполнить привязку к объекту элемента.
Обновите свойства элемента.
Вызовите метод 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);

Сведения о том, как обновить элемент собрания или встречи с помощью управляемого API EWS, см. в статье Update appointments and meetings by using EWS in Exchange.

Обновление элемента с помощью EWS

Чтобы обновить элемент с помощью EWS, сделайте следующее:

Получите последнюю версию элемента (если ее у вас еще нет) с помощью операции GetItem.
Укажите редактируемые поля и присвойте им новые значения с помощью операции UpdateItem.

В приведенном ниже примере показан XML-запрос с операцией UpdateItem, который отправляется на сервер для изменения свойства Subject электронного сообщения. Для удобства значения некоторых атрибутов и элементов были сокращены.

<?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>

В ответ на запрос UpdateItem сервер отправляет сообщение UpdateItemResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что элемент успешно обновлен.

Сведения о том, как изменить элемент собрания или встречи с помощью веб-служб Exchange, см. в статье Update appointments and meetings by using EWS in Exchange.

Удаление элемента с помощью управляемого API EWS

Вы можете удалять элементы, перемещая их в папку "Удаленные" или в корзину. Если вы знаете 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);

Дополнительные сведения об удалении элементов см. в статье Deleting items by using EWS in Exchange. Сведения о том, как удалить элемент собрания или встречи с помощью управляемого API EWS, см. в статье Delete appointments and cancel meetings by using EWS in Exchange.

Удаление элемента с помощью 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>

В ответ на запрос DeleteItem сервер отправляет сообщение DeleteItemResponse, включающее параметр ResponseCode со значением NoError, которое указывает, что элемент успешно удален.

Дополнительные сведения об удалении элементов см. в статье Deleting items by using EWS in Exchange. Сведения о том, как удалить элемент собрания или встречи с помощью EWS, см. в статье Delete appointments and cancel meetings by using EWS in Exchange.

Перемещение или копирование элементов в другой почтовый ящик

Вы можете перемещать и копировать элементы между почтовыми ящиками с помощью операций ExportItems и UploadItems. Дополнительные сведения см. в статье Exporting and importing items by using EWS in Exchange.

Поделиться через