Partager via

Traiter les messages électroniques par lots à l’aide d’EWS dans Exchange

  • Article

Découvrez comment créer, obtenir, mettre à jour et supprimer des lots de messages électroniques en un seul appel à l’aide de l’API managée EWS ou EWS dans Exchange.

Vous pouvez utiliser l’API managée EWS ou EWS pour travailler avec des lots de messages électroniques afin de réduire le nombre d’appels qu’un client passe à un serveur Exchange. Lorsque vous utilisez l’API managée EWS pour créer, obtenir, mettre à jour, supprimer et envoyer des messages par lots, vous utilisez des méthodes d’objet ExchangeService , tandis que lorsque vous utilisez des messages électroniques uniques, vous utilisez des méthodes d’objet EmailMessage . Si vous utilisez EWS, vous utilisez les mêmes opérations pour travailler avec des lots de messages électroniques uniques et.

Tableau 1. Méthodes d’API managée EWS et opérations EWS pour l’utilisation de lots de messages électroniques

Afin de... Utiliser cette méthode d’API managée EWS Utiliser cette opération EWS
Créer des messages électroniques par lots
 ExchangeService.CreateItems
CreateItem
Obtenir des messages électroniques par lots
 ExchangeService.BindToItems
GetItem
Mettre à jour les messages électroniques par lots
 ExchangeService.UpdateItems
UpdateItem
Supprimer des messages électroniques par lots
 ExchangeService.DeleteItems
DeleteItem

Dans cet article, vous allez apprendre à effectuer des tâches de base pour des lots de messages électroniques à l’aide de l’API managée EWS ou EWS.

Créer des messages électroniques par lots à l’aide de l’API managée EWS

Vous pouvez créer des messages par lots à l’aide de la méthode CreateItems de l’API managée EWS, comme illustré dans l’exemple suivant. Cet exemple crée trois objets EmailMessage localement, ajoute chaque message à une collection, puis appelle la méthode CreateItems sur la collection de messages.

Cet exemple suppose que le service est un objetExchangeService valide et que l’utilisateur a bien été authentifié pour un serveur 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;
}

Notez que l’exemple enregistre uniquement les messages dans le dossier Brouillons ; il n’envoie pas les messages. Pour plus d’informations sur l’envoi des messages, consultez Envoyer des messages électroniques par lots à l’aide de l’API managée EWS.

Créer des messages électroniques par lots à l’aide d’EWS

Vous pouvez créer des messages électroniques par lots à l’aide de l’opération CreateItem EWS, comme indiqué dans l’exemple de code suivant. Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez l’API managée EWS pour créer des messages électroniques par lots.

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

Le serveur répond à la requête CreateItem avec un message CreateItemResponse qui inclut la valeur ResponseCodeNoError pour chacun des nouveaux messages, ce qui indique que chaque e-mail a été créé et enregistré avec succès.

Notez que l’exemple enregistre uniquement les messages dans le dossier Brouillons ; il n’envoie pas les messages. Pour plus d’informations sur l’envoi des messages, consultez Envoyer des messages électroniques par lots à l’aide d’EWS.

Envoyer des e-mails par lots à l’aide de l’API managée EWS

Vous utilisez le même code pour envoyer des messages électroniques par lots que pour créer des messages électroniques par lots, sauf que certains paramètres de la méthode CreateItems changent. Par conséquent, pour envoyer des messages électroniques à l’aide de l’API managée EWS, utilisez le code que vous utilisez pour créer des messages électroniques par lots et remplacez l’appel à la méthode CreateItems par l’appel dans l’exemple suivant. Dans cet exemple, les messages sont créés dans le dossier Éléments envoyés, et la disposition des messages est remplacée par MessageDisposition.SendAndSaveCopy, afin que le message soit envoyé et non seulement enregistré localement.

// 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);

Envoyer des messages électroniques par lots à l’aide d’EWS

Vous utilisez le même code pour envoyer des messages électroniques par lots que pour créer des messages électroniques par lots, à ceci près que quelques-unes des valeurs d’attribut changent pour l’opération CreateItem . Par conséquent, pour envoyer des messages électroniques à l’aide d’EWS, utilisez le code que vous utilisez pour créer des messages électroniques par lots, remplacez la valeur MessageDisposition par « SendAndSaveCopy », puis remplacez l’élément DistinguishedFolderId par « sentitems », comme illustré dans l’exemple de code suivant.

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

Le serveur répond à la requête CreateItem avec un message CreateItemResponse qui inclut la valeur ResponseCodeNoError pour chacun des nouveaux messages, ce qui indique que chaque e-mail a été créé et envoyé avec succès.

Obtenir des messages électroniques par lots à l’aide de l’API managée EWS

Vous pouvez obtenir des messages électroniques par lots à l’aide de la méthode BindToItems de l’API managée EWS, comme illustré dans l’exemple suivant.

Cet exemple suppose que le service est un objetExchangeService valide et que l’utilisateur a bien été authentifié pour un serveur 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;
}

Obtenir des messages électroniques par lots à l’aide d’EWS

Vous pouvez obtenir des messages électroniques par lots à l’aide de l’opération GetItem EWS et du code dans l’exemple suivant. Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez l’API managée EWS pour obtenir des messages électroniques par lots.

[!REMARQUE] Les attributs ItemId et ChangeKey ont été réduits pour une meilleure lisibilité.

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

Le serveur répond à la requête GetItem avec un message GetItemResponse qui inclut les propriétés de la première classe pour chacun des messages demandés.

Mettre à jour les messages électroniques par lots à l’aide de l’API managée EWS

Vous pouvez obtenir des messages électroniques par lots à l’aide de la méthode UpdateItems de l’API managée EWS, comme illustré dans l’exemple suivant.

Pour obtenir la liste des propriétés de message électronique accessibles en écriture, consultez Email propriétés et éléments dans EWS dans Exchange.

Pour plus d’informations sur l’envoi d’un brouillon de message après sa mise à jour, consultez Envoi de messages électroniques à l’aide de l’API managée EWS.

Cet exemple suppose que le service est un objetExchangeService valide et que l’utilisateur a bien été authentifié pour un serveur 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;
}

Mettre à jour les messages électroniques par lots à l’aide d’EWS

Vous pouvez mettre à jour les messages électroniques par lots à l’aide de l’opération GetItem EWS, comme indiqué dans l’exemple de code suivant. Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez l’API managée EWS pour mettre à jour les messages électroniques par lots.

Pour obtenir la liste des éléments de courrier électronique accessibles en écriture, consultez Email propriétés et éléments dans EWS dans Exchange.

Pour plus d’informations sur l’envoi d’un brouillon de message après sa mise à jour, consultez Envoyer un brouillon de message électronique à l’aide d’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>

Le serveur répond à la requête UpdateItem avec un message UpdateItemResponse qui inclut la valeur ResponseCodeNoError, ce qui indique que chacune des mises à jour a été enregistrée avec succès sur le serveur. Tous les conflits sont signalés dans l’élément ConflictResult .

Supprimer des messages électroniques par lots à l’aide de l’API managée EWS

Vous pouvez supprimer des messages par lots à l’aide de la méthode DeleteItems de l’API managée EWS, comme illustré dans l’exemple suivant.

Cet exemple suppose que le service est un objetExchangeService valide et que l’utilisateur a bien été authentifié pour un serveur 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");
    }
}

Supprimer des messages électroniques par lots à l’aide d’EWS

Vous pouvez supprimer des messages électroniques par lots à l’aide de l’opération EWS DeleteItem , comme indiqué dans l’exemple de code suivant. Il s’agit également de la requête XML que l’API managée EWS envoie lorsque vous utilisez l’API managée EWS pour supprimer des messages électroniques par lots.

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

Le serveur répond à la requête DeleteItem avec un message DeleteItemResponse qui inclut la valeur ResponseCodeNoError pour chaque élément supprimé. Notez que l’opération retourne également la réussite si l’ID d’élément est introuvable.

Vérification de la réussite d’un processus de traitement par lots

Lorsqu’un ou plusieurs messages électroniques d’une demande par lot ne peuvent pas être traités comme demandé, une erreur est retournée pour chaque e-mail ayant échoué, et le reste des e-mails du lot sont traités comme prévu. Des échecs dans le traitement par lots peuvent se produire si l’élément a été supprimé et ne peut donc pas être envoyé, récupéré ou mis à jour, ou si l’élément a été déplacé vers un autre dossier et a donc un nouvel ID d’élément et ne peut pas être modifié avec l’ID d’élément envoyé. Les informations de cette section montrent comment obtenir des détails d’erreur sur les échecs de traitement par lots des messages électroniques.

Pour vérifier la réussite d’un processus par lots à l’aide de l’API managée EWS, vous pouvez vérifier que la propriété OverallResult de ServiceResponseCollection est égale à ServiceResult.Success. Si c’est le cas, tous les e-mails ont été traités avec succès. Si OverallResult n’est pas égal à ServiceResult.Success, un ou plusieurs e-mails n’ont pas été traités correctement. Chacun des objets retournés dans ServiceResponseCollection contient les propriétés suivantes :

Ces propriétés contiennent des informations sur la raison pour laquelle les messages électroniques n’ont pas pu être traités comme demandé. Les exemples de cet article affichent les messages Result, ErrorCode et ErrorMessage pour chaque message d’échec. Vous pouvez utiliser ces résultats pour examiner le problème.

Pour EWS, pour vérifier la réussite d’un processus par lot, vérifiez l’attribut ResponseClass pour chaque élément en cours de traitement. Voici la structure de base du ResponseMessageType, le type de base duquel tous les messages de réponse sont dérivés.

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

L’attribut ResponseClass est défini sur Réussite si l’e-mail a été traité avec succès, ou Erreur si l’e-mail n’a pas été traité correctement. Pour les e-mails, vous ne rencontrerez pas d’avertissement pendant le traitement par lots. Si responseClass a la valeur Success, l’élément ResponseCode qui suit est également toujours défini sur NoError. Si responseClass a la valeur Error, vous devez vérifier les valeurs des éléments MessageText, ResponseCode et MessageXml pour déterminer la cause du problème. DescriptiveLinkKey n’est actuellement pas utilisé.

Voir aussi