Processar mensagens de email em lotes usando o EWS no Exchange
Saiba como criar, obter, atualizar e excluir lotes de mensagens de email em uma única chamada usando a API Gerenciada do EWS ou o EWS no Exchange.
Você pode usar a API Gerenciada do EWS ou o EWS para trabalhar com lotes de mensagens de email para reduzir o número de chamadas que um cliente faz a um servidor do Exchange. Quando você usa a API Gerenciada do EWS para criar, obter, atualizar, excluir e enviar mensagens em lotes, você usa métodos de objeto ExchangeService , enquanto quando você trabalha com mensagens de email simples, usa métodos de objeto EmailMessage . Se você estiver usando o EWS, usará as mesmas operações para trabalhar com mensagens de email individuais e em lotes.
Tabela 1. Métodos de API Gerenciada do EWS e operações EWS para trabalhar com lotes de mensagens de email
| Para... | Use este método de API Gerenciada do EWS | Usar essa operação EWS |
|---|---|---|
| Criar mensagens de email em lotes |
ExchangeService.CreateItems |
CreateItem |
| Obter mensagens de email em lotes |
ExchangeService.BindToItems |
GetItem |
| Atualizar mensagens de email em lotes |
ExchangeService.UpdateItems |
UpdateItem |
| Excluir mensagens de email em lotes |
ExchangeService.DeleteItems |
DeleteItem |
Neste artigo, você aprenderá a concluir tarefas básicas para lotes de mensagens de email usando a API Gerenciada do EWS ou o EWS.
Criar mensagens de email em lotes usando a API Gerenciada do EWS
Você pode criar mensagens em lotes usando o método CreateItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir. Este exemplo cria três objetos EmailMessage localmente, adiciona cada mensagem a uma coleção e chama o método CreateItems na coleção de mensagens.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.
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;
}
Observe que o exemplo salva apenas as mensagens na pasta Rascunhos; ele não envia as mensagens. Para saber mais sobre como enviar as mensagens, consulte Enviar mensagens de email em lotes usando a API Gerenciada do EWS.
Criar mensagens de email em lotes usando o EWS
Você pode criar mensagens de email em lotes usando a operação CreateItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para criar mensagens de email em lotes.
<?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>
O servidor responde à solicitação CreateItem com uma mensagem CreateItemResponse que inclui um valor ResponseCode de NoError para cada uma das novas mensagens, o que indica que cada email foi criado e salvo com êxito.
Observe que o exemplo salva apenas as mensagens na pasta Rascunhos; ele não envia as mensagens. Para saber mais sobre como enviar as mensagens, consulte Enviar mensagens de email em lotes usando o EWS.
Enviar mensagens de email em lotes usando a API Gerenciada do EWS
Você usa o mesmo código para enviar mensagens de email em lotes que usa para criar mensagens de email em lotes, exceto que alguns dos parâmetros do método CreateItems são alterados. Portanto, para enviar mensagens de email usando a API Gerenciada do EWS, use o código usado para criar mensagens de email em lotes e substitua a chamada para o método CreateItems pela chamada no exemplo a seguir. Neste exemplo, as mensagens são criadas na pasta Itens Enviados e a disposição da mensagem é alterada para MessageDisposition.SendAndSaveCopy, para que a mensagem seja enviada e não apenas salva localmente.
// 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);
Enviar mensagens de email em lotes usando o EWS
Você usa o mesmo código para enviar mensagens de email em lotes que usa para criar mensagens de email em lotes, exceto que alguns dos valores de atributo são alterados para a operação CreateItem . Portanto, para enviar mensagens de email usando o EWS, use o código usado para criar mensagens de email em lotes e altere o valor messageDisposition para "SendAndSaveCopy" e altere o DistinguishedFolderId para "sentitems", conforme mostrado no exemplo de código a seguir.
<m:CreateItem MessageDisposition="SendAndSaveCopy">
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="sentitems" />
</m:SavedItemFolderId>
O servidor responde à solicitação CreateItem com uma mensagem CreateItemResponse que inclui um valor ResponseCode de NoError para cada uma das novas mensagens, o que indica que cada email foi criado e enviado com êxito.
Obter mensagens de email em lotes usando a API Gerenciada do EWS
Você pode obter mensagens de email em lotes usando o método BindToItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.
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;
}
Obter mensagens de email em lotes usando o EWS
Você pode obter mensagens de email em lotes usando a operação GetItem EWS e o código no exemplo a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para obter mensagens de email em lotes.
Os atributos ItemId e ChangeKey foram reduzidos para legibilidade.
<?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>
O servidor responde à solicitação GetItem com uma mensagem GetItemResponse que inclui as propriedades de primeira classe para cada uma das mensagens solicitadas.
Atualizar mensagens de email em lotes usando a API Gerenciada do EWS
Você pode obter mensagens de email em lotes usando o método UpdateItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir.
Para obter uma lista de propriedades de mensagem de email graváveis, consulte Email propriedades e elementos no EWS no Exchange.
Para obter detalhes sobre como enviar uma mensagem de rascunho após a atualização, confira Enviando mensagens de email usando a API Gerenciada do EWS.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.
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;
}
Atualizar mensagens de email em lotes usando o EWS
Você pode atualizar mensagens de email em lotes usando a operação GetItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para atualizar mensagens de email em lotes.
Para obter uma lista de elementos de mensagem de email graváveis, consulte Email propriedades e elementos no EWS no Exchange.
Para obter detalhes sobre como enviar uma mensagem de rascunho depois de ser atualizada, consulte Enviar uma mensagem de email de rascunho usando o 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>
O servidor responde à solicitação UpdateItem com uma mensagem UpdateItemResponse que inclui um valor ResponseCode de NoError, que indica que cada uma das atualizações foi salva com êxito no servidor. Todos os conflitos são relatados no elemento ConflictResult .
Excluir mensagens de email em lotes usando a API Gerenciada do EWS
Você pode excluir mensagens em lotes usando o método DeleteItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir.
Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.
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");
}
}
Excluir mensagens de email em lotes usando o EWS
Você pode excluir mensagens de email em lotes usando a operação DeleteItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para excluir mensagens de email em lotes.
<?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>
O servidor responde à solicitação DeleteItem com uma mensagem DeleteItemResponse que inclui um valor ResponseCode de NoError para cada item que foi removido. Observe que a operação também retornará êxito se a ID do item não puder ser encontrada.
Verificando se um processo em lote foi concluído com êxito
Quando uma ou mais mensagens de email em uma solicitação em lote não podem ser processadas conforme solicitado, um erro é retornado para cada mensagem de email que falhou e o restante dos emails no lote são processados conforme o esperado. Falhas no processamento em lote podem ocorrer se o item foi excluído e, portanto, não puder ser enviado, recuperado ou atualizado ou se o item for movido para uma pasta diferente e, portanto, tiver uma nova ID do item e não puder ser modificado com a ID do item enviada. As informações nesta seção mostram como obter detalhes de erro sobre falhas no processamento em lote da mensagem de email.
Para verificar o sucesso de um processo em lote usando a API Gerenciada do EWS, verifique se a propriedade OverallResult do ServiceResponseCollection é igual a ServiceResult.Success. Em caso afirmativo, todos os emails foram processados com êxito. Se o OverallResult não for igual a ServiceResult.Success, um ou mais emails não foram processados com êxito. Cada um dos objetos retornados no ServiceResponseCollection contém as seguintes propriedades:
Essas propriedades contêm informações sobre por que as mensagens de email não puderam ser processadas conforme solicitado. Os exemplos neste artigo imprimem o Resultado, o ErrorCode e o ErrorMessage para cada mensagem com falha. Você pode usar esses resultados para investigar o problema.
Para eWS, para verificar o sucesso de um processo em lote, verifique o atributo ResponseClass para cada item que está sendo processado. A seguir está a estrutura básica do ResponseMessageType, o tipo base do qual todas as mensagens de resposta são derivadas.
<ResponseMessage ResponseClass="Success | Warning | Error">
<MessageText/>
<ResponseCode/>
<DescriptiveLinkKey/>
<MessageXml/>
</ResponseMessage>
O atributo ResponseClass será definido como Êxito se o email foi processado com êxito ou Erro se o email não tiver sido processado com êxito. Para mensagens de email, você não encontrará um Aviso durante o processamento em lote. Se o ResponseClass for Success, o elemento ResponseCode a seguir também será sempre definido como NoError. Se a ResponseClass for Error, você precisará verificar os valores dos elementos MessageText, ResponseCode e MessageXml para determinar o que causou o problema. O DescriptiveLinkKey está atualmente não utilizado.
Confira também
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários