Traiter des contacts par lots à l’aide d’EWS dans Exchange
Découvrez comment créer, obtenir, mettre à jour et supprimer des lots de contacts dans 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 contacts 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 et supprimer des contacts par lots, vous utilisez des méthodes d’objet ExchangeService , tandis que lorsque vous travaillez avec des contacts uniques, vous utilisez des méthodes d’objet Contact . Si vous utilisez EWS, vous utilisez les mêmes opérations pour travailler avec un seul contact et des lots de contacts.
Tableau 1. Méthodes d’API managée EWS et opérations EWS pour l’utilisation de lots de contacts
| Afin de... | Utiliser cette méthode d’API managée EWS | Utiliser cette opération EWS |
|---|---|---|
| Créer des contacts par lots |
ExchangeService.CreateItems |
CreateItem |
| Obtenir des contacts par lots |
ExchangeService.BindToItems ou ExchangeService.LoadPropertiesForItems |
GetItem |
| Mettre à jour les contacts par lots |
ExchangeService.UpdateItems |
UpdateItem |
| Supprimer des contacts par lots |
ExchangeService.DeleteItems |
DeleteItem |
Dans cet article, vous allez apprendre à effectuer des tâches de base pour des lots de contacts à l’aide de l’API managée EWS ou EWS.
Créer des contacts par lots à l’aide de l’API managée EWS
Vous pouvez créer des contacts 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 Contact localement, ajoute chaque contact à une collection, puis appelle la méthode CreateItems sur la collection de contacts.
public static Collection<ItemId> CreateContactsInBatch(ExchangeService service)
{
// These are unsaved local instances of a Contact 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.
Contact contact1 = new Contact(service);
Contact contact2 = new Contact(service);
Contact contact3 = new Contact(service);
// Set the properties on the first contact.
contact1.DisplayName = "Sadie Daniels";
contact1.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("sadie@contoso.com");
// Set the properties on the second contact.
contact2.DisplayName = "Alfred Welker";
contact2.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("alfred@contoso.com");
// Set the properties on the third contact.
contact3.DisplayName = "Hope Gross";
contact3.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("hope@contoso.com");
// Add the Contact objects to a collection.
Collection<Contact> contactItems = new Collection<Contact>() { contact1, contact2, contact3 };
// Create the batch of contacts on the server.
// This method call results in an CreateItem call to EWS.
ServiceResponseCollection<ServiceResponse> response = service.CreateItems(contactItems, WellKnownFolderName.Contacts, null, 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 contacts.
foreach (Contact contact in contactItems)
{
try
{
itemIds.Add(contact.Id);
Console.WriteLine("Contact '{0}' created successfully.", contact.DisplayName);
}
catch (Exception ex)
{
// Print out the exception and the last eight characters of the item ID.
Console.WriteLine("Exception while creating contact {0}: {1}", contact.Id.ToString().Substring(144), ex.Message);
}
}
// Determine whether the CreateItems method call completed successfully.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All locally created contacts were successfully created in the Contacts folder.");
Console.WriteLine("\r\n");
}
// If the method did not return success, print the result message for each contact.
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 (contact {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;
}
Créer des contacts par lots à l’aide d’EWS
Vous pouvez créer des contacts 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 contacts par lots.
<?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>
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="contacts" />
</m:SavedItemFolderId>
<m:Items>
<t:Contact>
<t:DisplayName>Sadie Daniels</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">sadie@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
<t:Contact>
<t:DisplayName>Alfred Welker</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">alfred@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
<t:Contact>
<t:DisplayName>Hope Gross</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">hope@contoso.com</t:Entry>
</t:EmailAddresses>
</t:Contact>
</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 contacts, ce qui indique que chaque contact a été créé et enregistré avec succès.
Obtenir des contacts par lots à l’aide de l’API managée EWS
Vous pouvez obtenir des contacts 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<Contact> BatchGetContactItems(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, ContactSchema.DisplayName);
// 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 Contact objects to populate from the values that are returned by the Exchange server.
Collection<Contact> contactItems = new Collection<Contact>();
foreach (GetItemResponse getItemResponse in response)
{
try
{
Item item = getItemResponse.Item;
Contact contact = (Contact)item;
contactItems.Add(contact);
// Print out confirmation and the last eight characters of the item ID.
Console.WriteLine("Found item {0}.", contact.Id.ToString().Substring(144));
}
catch (Exception ex)
{
Console.WriteLine("Exception while getting a contact: {0}", ex.Message);
}
}
// Check for success of the BindToItems method call.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All contacts retrieved successfully.");
Console.WriteLine("\r\n");
}
return contactItems;
}
Obtenir des contacts par lots à l’aide d’EWS
Vous pouvez obtenir des contacts 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 contacts par lots. L’attribut ItemId a été raccourci pour plus de lisibilité.
<?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:GetItem>
<m:ItemShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="contacts:DisplayName" />
</t:AdditionalProperties>
</m:ItemShape>
<m:ItemIds>
<t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
<t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
<t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
</m:ItemIds>
</m:GetItem>
</soap:Body>
</soap:Envelope>
Le serveur répond à la requête GetItem avec un message GetItemResponse qui inclut l’ID et le nom complet de chacun des contacts demandés.
Mettre à jour les contacts par lots à l’aide de l’API managée EWS
Vous pouvez mettre à jour les contacts par lots à l’aide de la méthode UpdateItems de l’API managée EWS, comme illustré dans l’exemple suivant. L’exemple précédent crée le contact, mais ne spécifie pas pour qui il travaille. Vous pouvez utiliser le code de cet exemple pour mettre à jour tous vos contacts à la fois afin d’inclure leur nom d’entreprise.
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<Contact> BatchUpdateContactItems(ExchangeService service, Collection<Contact> contactItems)
{
// Update the company name of each contact locally.
foreach (Contact contact in contactItems)
{
// Update the company name of the contact.
contact.CompanyName = "Contoso";
// Print out confirmation with the last eight characters of the item ID and the contact company name.
Console.WriteLine("Updated local contact {0} with the company name '{1}'.", contact.Id.ToString().Substring(144), contact.CompanyName);
}
// Send the item updates to the server.
// This method call results in an UpdateItem call to EWS.
ServiceResponseCollection<UpdateItemResponse> response = service.UpdateItems(contactItems, WellKnownFolderName.Contacts, ConflictResolutionMode.AutoResolve, null, null);
// Verify the success of the UpdateItems method call.
if (response.OverallResult == ServiceResult.Success)
{
Console.WriteLine("All contacts updated successfully.\r\n");
}
// If the method did not return success, print the result message for each contact.
else
{
Console.WriteLine("All contacts were not successfully saved on the server.\r\n");
int counter = 1;
foreach (ServiceResponse resp in response)
{
Console.WriteLine("Result for (contact {0}): {1}", counter, resp.Result);
Console.WriteLine("Error Code: {0}", resp.ErrorCode);
Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
counter++;
}
}
return contactItems;
}
Mettre à jour les contacts par lots à l’aide d’EWS
Vous pouvez mettre à jour des contacts 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 contacts par lots. L’attribut ItemId a été raccourci pour plus de lisibilité.
<?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:UpdateItem ConflictResolution="AutoResolve">
<m:SavedItemFolderId>
<t:DistinguishedFolderId Id="contacts" />
</m:SavedItemFolderId>
<m:ItemChanges>
<t:ItemChange>
<t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
<t:ItemChange>
<t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</t:SetItemField>
</t:Updates>
</t:ItemChange>
<t:ItemChange>
<t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
<t:Updates>
<t:SetItemField>
<t:FieldURI FieldURI="contacts:CompanyName" />
<t:Contact>
<t:CompanyName>Contoso</t:CompanyName>
</t:Contact>
</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 contacts par lots à l’aide de l’API managée EWS
Vous pouvez supprimer des contacts par lots à l’aide de la méthode d’API managée EWS DeleteItems , 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 BatchDeleteContactItems(ExchangeService service, Collection<ItemId> itemIds)
{
// Delete the batch of contact 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("Contacts deleted successfully.\r\n");
}
// If the method did not return success, print a message.
else
{
Console.WriteLine("Not all contacts deleted successfully.\r\n");
}
}
Supprimer des contacts par lots à l’aide d’EWS
Vous pouvez supprimer des contacts 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 contacts par lots. L’attribut ItemId a été raccourci pour plus de lisibilité.
<?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:DeleteItem DeleteType="SoftDelete" AffectedTaskOccurrences="AllOccurrences">
<m:ItemIds>
<t:ItemId Id="ceJwYAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yY" />
<t:ItemId Id="ceJwZAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yZ" />
<t:ItemId Id="ceJwaAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51ya" />
</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 contacts d’une demande par lot ne peuvent pas être traités comme demandé, une erreur est retournée pour chaque contact ayant échoué, et les autres contacts 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 récupéré, ni 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 dans le traitement par lots des contacts.
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 contacts ont été traités avec succès. Si OverallResult n’est pas égal à ServiceResult.Success, un ou plusieurs contacts 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 contacts n’ont pas pu être traités comme demandé. Les exemples de cet article affichent les valeurs Result, ErrorCode et ErrorMessage pour chaque contact ayant échoué. 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 le contact a été traité avec succès, ou Erreur si le contact n’a pas été traité correctement. Pour les contacts, 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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour