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

Обработка сообщений электронной почты пакетами с помощью EWS в Exchange

  • Статья

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

Управляемый API EWS или EWS можно использовать для работы с пакетами сообщений электронной почты, чтобы уменьшить количество вызовов, которые клиент выполняет на сервер Exchange Server. При использовании управляемого API EWS для создания, получения, обновления, удаления и отправки сообщений в пакетах используются методы объектов ExchangeService , тогда как при работе с отдельными сообщениями электронной почты используются методы объектов EmailMessage . Если вы используете EWS, вы используете одни и те же операции для работы как с отдельными, так и с пакетами сообщений электронной почты.

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

Задача Используйте этот метод управляемого API EWS Используйте эту операцию EWS
Создание сообщений электронной почты в пакетах
 ExchangeService.CreateItems
CreateItem
Получение сообщений электронной почты в пакетах
 ExchangeService.BindToItems
GetItem
Обновление сообщений электронной почты в пакетах
 ExchangeService.UpdateItems
UpdateItem
Удаление сообщений электронной почты пакетами
 ExchangeService.DeleteItems
DeleteItem

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

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

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

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

public static Collection<ItemId> CreateDraftEmailInBatch(ExchangeService service)
{
    // These are unsaved local instances of an EmailMessage object.
    // Despite the required parameter of an ExchangeService object (service), no call
    // to an Exchange server is made when the objects are instantiated.
    // A call to the Exchange server is made when the service.CreateItems() method is called.
    EmailMessage message1 = new EmailMessage(service);
    EmailMessage message2 = new EmailMessage(service);
    EmailMessage message3 = new EmailMessage(service);
    // Set the properties on the first message.
    message1.Subject = "Project priorities";
    message1.Body = "(1) Buy pizza, (2) Eat pizza";
    message1.ToRecipients.Add("sadie@contoso.com");
    // Set the properties on the second message.
    message2.Subject = "Company Soccer Team";
    message2.Body = "Are you interested in joining?";
    message2.ToRecipients.Add("magdalena@contoso.com");
    // Set the properties on the third message.
    message3.Subject = "Code Blast";
    message3.Body = "Are you interested in getting together to finish the methods for the ContosoLive project?";
    message3.ToRecipients.Add("mack@contoso.com");
    // Add the EmailMessage objects to a collection.
    Collection<EmailMessage> messageItems = new Collection<EmailMessage>() { message1, message2, message3 };
    // Create the batch of email messages on the server.
    // This method call results in an CreateItem call to EWS.
    ServiceResponseCollection<ServiceResponse> response = service.CreateItems(messageItems, WellKnownFolderName.Drafts, MessageDisposition.SaveOnly, null);
    // Instantiate a collection of item IDs to populate from the values that are returned by the Exchange server.
    Collection<ItemId> itemIds = new Collection<ItemId>();
    // Collect the item IDs from the created email messages.
    foreach (EmailMessage message in messageItems)
    {
        try
        {
            itemIds.Add(message.Id);
            Console.WriteLine("Email message '{0}' created successfully.", message.Subject);
        }
        catch (Exception ex)
        {
            // Print out the exception and the last eight characters of the item ID.
            Console.WriteLine("Exception while creating message {0}: {1}", message.Id.ToString().Substring(144), ex.Message);
        }
    }
    // Check for success of the CreateItems method call.
    if (response.OverallResult == ServiceResult.Success)
    {
            Console.WriteLine("All locally created messages were successfully saved to the Drafts folder.");
            Console.WriteLine("\r\n");
    }

    // If the method did not return success, print the result message for each email.
    else
    {
        int counter = 1;
        foreach (ServiceResponse resp in response)
        {
            // Print out the result and the last eight characters of the item ID.
            Console.WriteLine("Result (message {0}), id {1}: {2}", counter, itemIds[counter - 1].ToString().Substring(144), resp.Result);
            Console.WriteLine("Error Code: {0}", resp.ErrorCode);
            Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
            Console.WriteLine("\r\n");
            counter++;
        }
    }
    return itemIds;
}

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

Создание сообщений электронной почты в пакетах с помощью EWS

Сообщения электронной почты можно создавать пакетами с помощью операции CreateItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для создания сообщений электронной почты пакетами.

<?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:CreateItem MessageDisposition="SaveOnly">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="drafts" />
      </m:SavedItemFolderId>
      <m:Items>
        <t:Message>
          <t:Subject>Project priorities</t:Subject>
          <t:Body BodyType="HTML">(1) Buy pizza, (2) Eat pizza</t:Body>
          <t:ToRecipients>
            <t:Mailbox>
              <t:EmailAddress>sadie@contoso.com</t:EmailAddress>
            </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
        <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>magdalena@contoso.com</t:EmailAddress>
            </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
        <t:Message>
          <t:Subject>Code Blast</t:Subject>
          <t:Body BodyType="HTML">Are you interested in getting together to finish the methods for the ContosoLive project?</t:Body>
          <t:ToRecipients>
            <t:Mailbox>
              <t:EmailAddress>mack@contoso.com</t:EmailAddress>
            </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

Сервер отвечает на запрос CreateItem сообщением CreateItemResponse , которое содержит значение ResponseCodeNoError для каждого нового сообщения, указывающее, что каждое сообщение электронной почты было успешно создано и сохранено.

Обратите внимание, что в примере сообщения сохраняются только в папке Черновики. он не отправляет сообщения. Дополнительные сведения об отправке сообщений см. в статье Отправка сообщений электронной почты пакетами с помощью EWS.

Отправка сообщений электронной почты пакетами с помощью управляемого API EWS

Вы используете тот же код для отправки сообщений электронной почты пакетами, которые используются для создания сообщений электронной почты в пакетах, за исключением того, что некоторые параметры метода CreateItems изменяются. Таким образом, чтобы отправить сообщения электронной почты с помощью управляемого API EWS, используйте код, используемый для создания сообщений электронной почты в пакетах, и замените вызов метода CreateItems вызовом в следующем примере. В этом примере сообщения создаются в папке Отправленные, а ликвидация сообщений изменяется на MessageDisposition.SendAndSaveCopy, чтобы сообщение отправлялось, а не только сохранялось локально.

// Create and send the batch of email messages on the server.
// This method call results in an CreateItem call to EWS.
ServiceResponseCollection<ServiceResponse> response = service.CreateItems(messageItems, WellKnownFolderName.SentItems, MessageDisposition.SendAndSaveCopy, null);

Отправка сообщений электронной почты пакетами с помощью EWS

Вы используете тот же код для отправки сообщений электронной почты пакетами, которые используются для создания сообщений электронной почты в пакетах, за исключением того, что некоторые значения атрибутов изменяются для операции CreateItem . Таким образом, чтобы отправлять сообщения электронной почты с помощью EWS, используйте код, используемый для создания сообщений электронной почты в пакетах, и измените значение MessageDisposition на SendAndSaveCopy, а Для параметра DistinguishedFolderId — sentitems, как показано в следующем примере кода.

<m:CreateItem MessageDisposition="SendAndSaveCopy">
  <m:SavedItemFolderId>
    <t:DistinguishedFolderId Id="sentitems" />
  </m:SavedItemFolderId>

Сервер отвечает на запрос CreateItem сообщением CreateItemResponse , которое содержит значение ResponseCodeNoError для каждого нового сообщения, указывающее, что каждое сообщение электронной почты было создано и отправлено успешно.

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

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

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

public static Collection<EmailMessage> BatchGetEmailItems(ExchangeService service, Collection<ItemId> itemIds)
{
    // Create a property set that limits the properties returned by the Bind method to only those that are required.
    PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, EmailMessageSchema.Subject, EmailMessageSchema.ToRecipients);
    // Get the items from the server.
    // This method call results in a GetItem call to EWS.
    ServiceResponseCollection<GetItemResponse> response = service.BindToItems(itemIds, propSet);

    // Instantiate a collection of EmailMessage objects to populate from the values that are returned by the Exchange server.
    Collection<EmailMessage> messageItems = new Collection<EmailMessage>();
    foreach (GetItemResponse getItemResponse in response)
    {
        try
        {
            Item item = getItemResponse.Item;
            EmailMessage message = (EmailMessage)item;
            messageItems.Add(message);
            // Print out confirmation and the last eight characters of the item ID.
            Console.WriteLine("Found item {0}.", message.Id.ToString().Substring(144));
        }
        catch (Exception ex)
        {
           Console.WriteLine("Exception while getting a message: {0}", ex.Message);
        }
    }
    // Check for success of the BindToItems method call.
    if (response.OverallResult == ServiceResult.Success)
    {
        Console.WriteLine("All email messages retrieved successfully.");
        Console.WriteLine("\r\n");
    }
        return messageItems;
}

Получение сообщений электронной почты в пакетах с помощью EWS

Сообщения электронной почты можно получать пакетами с помощью операции GetItem EWS и кода, приведенного в следующем примере. Это также XML-запрос, который управляемый API EWS отправляет при использовании управляемого API EWS для получения сообщений электронной почты пакетными пакетами.

Атрибуты ItemId и ChangeKey сокращены для удобства чтения.

<?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:GetItem>
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
          <t:FieldURI FieldURI="message:ToRecipients" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:ItemIds>
        <t:ItemId Id="m4NxAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKB0" />
        <t:ItemId Id="m4NyAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKB1" />
        <t:ItemId Id="m4NzAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKB2" />
      </m:ItemIds>
    </m:GetItem>
  </soap:Body>
</soap:Envelope>

Сервер отвечает на запрос GetItemсообщением GetItemResponse , которое содержит свойства первого класса для каждого запрошенного сообщения.

Обновление сообщений электронной почты в пакетах с помощью управляемого API EWS

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

Список записываемых свойств сообщений электронной почты см. в разделе Email свойств и элементов в EWS в Exchange.

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

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

public static Collection<EmailMessage> BatchUpdateEmailItems(ExchangeService service, Collection<EmailMessage> messageItems)
{
    // Update the subject of each message locally.
    foreach (EmailMessage message in messageItems)
    {
        // Update the Subject of the email.
        message.Subject = "Updated subject at " + DateTime.Now;
        // Print out confirmation with the last eight characters of the item ID and the email subject.
        Console.WriteLine("Updated local email message {0} with the subject '{1}'.", message.Id.ToString().Substring(144), message.Subject);
    }
    // Send the item updates to the server.
    // This method call results in an UpdateItem call to EWS.
    ServiceResponseCollection<UpdateItemResponse> response = service.UpdateItems(messageItems, WellKnownFolderName.Drafts, ConflictResolutionMode.AutoResolve, MessageDisposition.SaveOnly, null);
    // Check for success of the UpdateItems method call.
    if (response.OverallResult == ServiceResult.Success)
    {
        Console.WriteLine("All email messages updated successfully.\r\n");
    }
    // If the method did not return success, print the result message for each email.
    else
    {
        Console.WriteLine("All emails were not successfully saved on the server.\r\n");
        int counter = 1;
        foreach (ServiceResponse resp in response)
        {
            Console.WriteLine("Result for (message {0}): {1}", counter, resp.Result);
            Console.WriteLine("Error Code: {0}", resp.ErrorCode);
            Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
            counter++;
        }
    }
    return messageItems;
}

Обновление сообщений электронной почты в пакетах с помощью EWS

Сообщения электронной почты можно обновлять пакетами с помощью операции GetItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для обновления сообщений электронной почты пакетами.

Список записываемых элементов сообщений электронной почты см. в разделе Email свойств и элементов в EWS в Exchange.

Дополнительные сведения об отправке черновика сообщения после обновления см. в разделе Отправка черновика сообщения электронной почты с помощью EWS.

<?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:UpdateItem MessageDisposition="SaveOnly"
                  ConflictResolution="AutoResolve">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="drafts" />
      </m:SavedItemFolderId>
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="m4OVAAA="
                    ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKCy" />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Subject" />
              <t:Message>
                <t:Subject>Updated subject at 1/17/2014 2:58:09 PM</t:Subject>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
        <t:ItemChange>
          <t:ItemId Id="m4OWAAA="
                    ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKCz" />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Subject" />
              <t:Message>
                <t:Subject>Updated subject at 1/17/2014 2:58:09 PM</t:Subject>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
        <t:ItemChange>
          <t:ItemId Id="m4OXAAA="
                    ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKC0" />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Subject" />
              <t:Message>
                <t:Subject>Updated subject at 1/17/2014 2:58:09 PM</t:Subject>
              </t:Message>
            </t:SetItemField>
          </t:Updates>
        </t:ItemChange>
      </m:ItemChanges>
    </m:UpdateItem>
  </soap:Body>
</soap:Envelope>

Сервер отвечает на запрос UpdateItemсообщением UpdateItemResponse , которое содержит значение ResponseCodeNoError, указывающее, что каждое из обновлений успешно сохранено на сервере. Все конфликты отображаются в элементе ConflictResult .

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

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

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

public static void BatchDeleteEmailItems(ExchangeService service, Collection<ItemId> itemIds)
{
    // Delete the batch of email message objects.
    // This method call results in an DeleteItem call to EWS.
    ServiceResponseCollection<ServiceResponse> response = service.DeleteItems(itemIds, DeleteMode.SoftDelete, null, AffectedTaskOccurrence.AllOccurrences);

    // Check for success of the DeleteItems method call.
    // DeleteItems returns success even if it does not find all the item IDs.
    if (response.OverallResult == ServiceResult.Success)
    {
        Console.WriteLine("Email messages deleted successfully.\r\n");
    }
    // If the method did not return success, print a message.
    else
    {
        Console.WriteLine("Not all email messages deleted successfully.\r\n");
    }
}

Удаление сообщений электронной почты пакетами с помощью EWS

Вы можете удалять сообщения электронной почты пакетами с помощью операции DeleteItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для удаления сообщений электронной почты пакетами.

<?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:DeleteItem DeleteType="SoftDelete"
                  AffectedTaskOccurrences="AllOccurrences">
      <m:ItemIds>
        <t:ItemId Id="m4OkAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKDE" />
        <t:ItemId Id="m4OlAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKDF" />
        <t:ItemId Id="m4OmAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF/yKDG" />
      </m:ItemIds>
    </m:DeleteItem>
  </soap:Body>
</soap:Envelope>

Сервер отвечает на запрос DeleteItem сообщением DeleteItemResponse , которое содержит значение ResponseCodeNoError для каждого удаленного элемента. Обратите внимание, что операция также возвращает успешное выполнение, если не удалось найти идентификатор элемента.

Проверка успешного выполнения пакетного процесса

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

Чтобы проверить успешность пакетного процесса с помощью управляемого API EWS, можно проверить, что свойство OverallResultобъекта ServiceResponseCollection равно ServiceResult.Success. Если это так, все сообщения электронной почты были успешно обработаны. Если значение OverallResult не равно ServiceResult.Success, одно или несколько сообщений электронной почты не были обработаны успешно. Каждый из объектов, возвращаемых в ServiceResponseCollection , содержит следующие свойства:

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

Для EWS, чтобы проверить успешность пакетного процесса, проверьте атрибут ResponseClass для каждого обрабатываемого элемента. Ниже приведена базовая структура ResponseMessageType, базового типа, от которого извлекаются все ответные сообщения.

<ResponseMessage ResponseClass="Success | Warning | Error">
            <MessageText/>
            <ResponseCode/>
            <DescriptiveLinkKey/>
            <MessageXml/>
</ResponseMessage>

Атрибут ResponseClass имеет значение Успешно , если сообщение было обработано успешно, или Error , если сообщение электронной почты не было обработано успешно. Для сообщений электронной почты предупреждение не будет отображаться во время пакетной обработки. Если параметр ResponseClass имеет значение Success, то следующий элемент ResponseCode также всегда имеет значение NoError. Если класс ResponseClass имеет значение Error, необходимо проверить значения элементов MessageText, ResponseCode и MessageXml , чтобы определить причину проблемы. DescriptiveLinkKey в настоящее время не используется.

См. также