Effectuer des recherches groupées à l’aide d’EWS dans Exchange
Découvrez comment effectuer des recherches groupées dans votre API managée EWS ou votre application EWS qui cible Exchange.
Les recherches groupées sont utiles, car elles vous permettent de contrôler l’organisation des résultats de la recherche. Les résultats de recherche organisés peuvent faciliter le traitement des résultats par votre application ou leur affichage à un utilisateur final de manière gérable.
Le regroupement fonctionne en plaçant tous les éléments dans le jeu de résultats qui ont la même valeur d’un champ spécifique dans un groupe. Par exemple, vous pouvez regrouper vos résultats par l’expéditeur, et tous les éléments de la même personne se trouvent dans un groupe distinct, et les éléments de chaque groupe sont triés en fonction de l’ordre que vous spécifiez dans l’affichage. Les groupes eux-mêmes sont triés par une valeur d’agrégation basée sur un champ que vous choisissez.
Tableau 1. Méthodes d’API managée EWS et opérations EWS pour organiser les résultats de la recherche
| Si vous voulez... | Dans l’API gérée EWS, utilisez… | Dans EWS, utilisez… |
|---|---|---|
| Organiser les éléments ayant la même valeur dans une propriété spécifique dans vos résultats en groupes |
Grouping.GroupOn |
Élément FieldURI en tant qu’enfant de l’élément GroupBy |
| Trier les éléments de chaque groupe en fonction de la valeur d’une propriété spécifique |
ItemView.OrderBy |
Élément SortOrder |
| Trier les groupes |
Grouping.AggregateOn Grouping.AggregateType Grouping.SortDirection |
Élément FieldURI en tant qu’enfant de l’élément AggregateOn Attribut d’agrégation sur l’élément AggregateOn Attribut Order sur l’élément GroupBy |
Pas à pas.
Regrouper les résultats par une propriété spécifique
La première étape de l’utilisation du regroupement consiste à sélectionner une propriété, ou un attribut sur les éléments dans la banque Exchange, à regrouper par. L’API managée EWS les expose en tant que propriétés de classe sur les classes correspondantes, tandis qu’EWS les expose en tant qu’éléments XML. Vous pouvez choisir n’importe quelle propriété, y compris les propriétés personnalisées ou étendues, mais il est utile de comprendre comment les éléments sont regroupés en fonction de la valeur de la propriété que vous choisissez.
Tous les éléments qui ont la même valeur dans la propriété que vous choisissez de regrouper seront regroupés. Cela peut sembler évident, mais c’est un détail important. Considérez ce qui se passe si vous regroupez par une propriété date/heure, telle que Item.DateTimeReceived dans l’API managée EWS, ou l’élément DateTimeReceived dans EWS. L’objectif peut être d’organiser les résultats en groupes, chaque groupe contenant des éléments du même jour. Toutefois, le regroupement examine la valeur entière, qui inclut l’heure.
Le résultat final est que les éléments seront regroupés de sorte que les éléments reçus en même temps, jusqu’au deuxième, se trouvent dans leur propre groupe. Les résultats seront probablement triés en un grand nombre de groupes avec un petit nombre d’éléments dans chaque groupe.
Pour obtenir un jeu de résultats avec un plus petit nombre de groupes et un plus grand nombre d’éléments dans chaque groupe, choisissez une propriété susceptible d’avoir un plus petit nombre de valeurs, comme EmailMessage.From ou Item.Categories dans l’API managée EWS, ou De ou Catégories dans EWS. La figure suivante montre la liste des e-mails qui s’affichent dans une boîte de réception.
Figure 1. Messages dans une boîte de réception
Si vous regroupez les éléments de la figure 1 par la propriété EmailMessage.From , le résultat est deux groupes: un pour les messages envoyés par Hope Gross et un pour les messages envoyés par Sadie Daniels.
Figure 2. Messages séparés en groupes en fonction de la propriété From
Trier les éléments dans des groupes
Vous pouvez contrôler la façon dont les éléments sont triés dans chaque groupe à l’aide de la propriété ItemView.OrderBy dans l’API managée EWS ou de l’élément SortOrder dans EWS. Le même classement s’applique à chaque groupe. Par exemple, si vous triez les éléments de la figure 1 par la propriété Item.DateTimeReceived , dans l’ordre décroissant, l’élément le plus récemment reçu de Hope Gross sera le premier dans le groupe Hope Gross, et l’élément le plus récemment reçu de Sadie Daniels sera le premier dans le groupe Sadie Daniels. De façon pratique, les groupes de la figure 2 sont déjà triés de cette façon.
Trier les groupes
Maintenant que vous avez vos groupes réglés, la dernière étape consiste à trier les groupes eux-mêmes. Étant donné que les groupes eux-mêmes n’ont pas de valeurs spécifiques, le processus de regroupement doit attribuer une valeur de tri à chaque groupe. Cette opération s’effectue par agrégation des valeurs d’une propriété spécifique au sein de chaque groupe, spécifiée par la propriété Grouping.AggregateOn dans l’API managée EWS, ou par l’élément FieldURI en tant qu’enfant de l’élément AggregateOn dans EWS. La propriété Grouping.AggregateType dans l’API managée EWS (ou l’attribut Aggregate sur l’élément AggregateOn dans EWS) spécifie la valeur des éléments au sein de chaque groupe qui est affectée à la valeur de tri du groupe, soit la plus grande valeur, soit la plus petite. Enfin, l’ordre de tri (décroissant ou croissant) est spécifié par la propriété Grouping.SortDirection dans l’API managée EWS, ou par l’attribut Order sur l’élément GroupBy dans EWS.
Par exemple, si les groupes de la figure 2 sont triés en agrégeant sur la propriété Item.DateTimeReceived , en utilisant la valeur la plus petite et en triant dans l’ordre décroissant, les éléments sont retournés dans l’ordre indiqué dans la figure 3.
Figure 3. Résultats de recherche groupés avec les groupes triés par la propriété DateTimeReceived
Les sections suivantes vous montrent comment vous pouvez extraire le regroupement et le tri dans le code.
Exemple : Effectuer une recherche groupée à l’aide de l’API managée EWS
Les méthodes d’API managée EWS suivantes peuvent utiliser le regroupement :
L’exemple suivant utilise la méthode ExchangeService.FindItems ; Toutefois, les mêmes règles et concepts s’appliquent à la méthode Folder.FindItems . Dans cet exemple, une méthode appelée GroupItemsByFrom est définie. Il prend un objet ExchangeService et un objet WellKnownFolderName comme paramètres. Il demande les 50 premiers éléments du dossier, regroupés par la propriété EmailMessage.From , triés par la propriété Item.DateTimeReceived dans l’ordre décroissant. Les groupes eux-mêmes sont triés par la plus petite valeur de propriété Item.DateTimeReceived sur leurs éléments, dans l’ordre décroissant.
Cet exemple suppose que l’objet ExchangeService a été initialisé avec des valeurs valides dans les propriétés Identifiants et Url.
static void GroupItemsByFrom(ExchangeService service, WellKnownFolderName folder)
{
// Limit the result set to 50 items.
ItemView view = new ItemView(50);
view.PropertySet = new PropertySet(ItemSchema.Subject,
ItemSchema.DateTimeReceived,
EmailMessageSchema.From,
ItemSchema.Categories);
// Item searches do not support Deep traversal.
view.Traversal = ItemTraversal.Shallow;
// Specify the sorting done within the groups.
view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);
// Configure grouping.
Grouping groupByFrom = new Grouping();
groupByFrom.GroupOn = EmailMessageSchema.From;
groupByFrom.AggregateOn = ItemSchema.DateTimeReceived;
groupByFrom.AggregateType = AggregateType.Minimum;
groupByFrom.SortDirection = SortDirection.Descending;
try
{
GroupedFindItemsResults<Item> results = service.FindItems(folder,
view, groupByFrom);
foreach (ItemGroup<Item> group in results.ItemGroups)
{
Console.WriteLine("Group: {0}", group.GroupIndex);
foreach (Item item in group.Items)
{
if (item is EmailMessage)
{
EmailMessage message = item as EmailMessage;
Console.WriteLine("From: {0}", message.From);
Console.WriteLine("Subject: {0}", message.Subject);
Console.WriteLine("Id: {0}\n", message.Id.ToString());
}
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
Exemple : effectuer une recherche groupée à l’aide d’EWS
L’exemple de requête suivant montre une demande d’opération FindItem pour les 50 premiers éléments du dossier, regroupés par l’élément From , triés par l’élément DateTimeReceived dans l’ordre décroissant. Les groupes eux-mêmes sont triés par la plus petite valeur d’élément DateTimeReceived sur leurs éléments, dans l’ordre décroissant.
<?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" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</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="item:DateTimeReceived" />
<t:FieldURI FieldURI="message:From" />
<t:FieldURI FieldURI="item:Categories" />
</t:AdditionalProperties>
</m:ItemShape>
<m:IndexedPageItemView MaxEntriesReturned="50" Offset="0" BasePoint="Beginning" />
<m:GroupBy Order="Descending">
<t:FieldURI FieldURI="message:From" />
<t:AggregateOn Aggregate="Minimum">
<t:FieldURI FieldURI="item:DateTimeReceived" />
</t:AggregateOn>
</m:GroupBy>
<m:SortOrder>
<t:FieldOrder Order="Descending">
<t:FieldURI FieldURI="item:DateTimeReceived" />
</t:FieldOrder>
</m:SortOrder>
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</m:ParentFolderIds>
</m:FindItem>
</soap:Body>
</soap:Envelope>
Le serveur retourne la réponse suivante.
<?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="712" MinorBuildNumber="22" Version="V2_3"
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:FindItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindItemResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="10" TotalItemsInView="8" IncludesLastItemInRange="true">
<t:Groups>
<t:GroupedItems>
<t:GroupIndex>0</t:GroupIndex>
<t:Items>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>Planning resources</t:Subject>
<t:DateTimeReceived>2013-12-10T17:41:05Z</t:DateTimeReceived>
<t:From>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=8D84A3F4CBB34D48838A3AECF99795C0-SADIE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>Timeline</t:Subject>
<t:DateTimeReceived>2013-12-10T17:40:37Z</t:DateTimeReceived>
<t:Categories>
<t:String>Project</t:String>
</t:Categories>
<t:From>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=8D84A3F4CBB34D48838A3AECF99795C0-SADIE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>For your perusal</t:Subject>
<t:DateTimeReceived>2013-11-20T21:51:16Z</t:DateTimeReceived>
<t:From>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=8D84A3F4CBB34D48838A3AECF99795C0-SADIE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>meeting notes</t:Subject>
<t:DateTimeReceived>2013-11-20T21:18:51Z</t:DateTimeReceived>
<t:Categories>
<t:String>Blue category</t:String>
</t:Categories>
<t:From>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=8D84A3F4CBB34D48838A3AECF99795C0-SADIE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>Meeting notes</t:Subject>
<t:DateTimeReceived>2013-11-20T21:18:51Z</t:DateTimeReceived>
<t:From>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=8D84A3F4CBB34D48838A3AECF99795C0-SADIE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
</t:Items>
</t:GroupedItems>
<t:GroupedItems>
<t:GroupIndex>1</t:GroupIndex>
<t:Items>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>Query</t:Subject>
<t:DateTimeReceived>2013-12-10T17:43:15Z</t:DateTimeReceived>
<t:From>
<t:Mailbox>
<t:Name>Hope Gross</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=9B55E4100C064D9D8C5F72FF36802ED3-HOPE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>Update</t:Subject>
<t:DateTimeReceived>2013-12-10T17:42:33Z</t:DateTimeReceived>
<t:Categories>
<t:String>Project</t:String>
<t:String>Blue category</t:String>
</t:Categories>
<t:From>
<t:Mailbox>
<t:Name>Hope Gross</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=9B55E4100C064D9D8C5F72FF36802ED3-HOPE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
<t:Message>
<t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
<t:Subject>This cat is hilarious!</t:Subject>
<t:DateTimeReceived>2013-10-15T20:22:12Z</t:DateTimeReceived>
<t:From>
<t:Mailbox>
<t:Name>Hope Gross</t:Name>
<t:EmailAddress>/O=FIRST ORGANIZATION/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=9B55E4100C064D9D8C5F72FF36802ED3-HOPE</t:EmailAddress>
<t:RoutingType>EX</t:RoutingType>
</t:Mailbox>
</t:From>
</t:Message>
</t:Items>
</t:GroupedItems>
</t:Groups>
</m:RootFolder>
</m:FindItemResponseMessage>
</m:ResponseMessages>
</m:FindItemResponse>
</s:Body>
</s:Envelope>
Différences entre les versions
Les versions d’Exchange commençant par la version principale 15 et se terminant par la build 15.0.775.38 retournent des éléments Group (de type GroupedItemsType) à la place des éléments GroupedItems dans la réponse SOAP. Si vous utilisez l’API managée EWS, la collection GroupedFindItemsResults.ItemGroups contient 0 objets. Si vous utilisez EWS, les éléments Group doivent être gérés en tant qu’éléments GroupedItems .
Les versions d’Exchange à compter de la version principale 15 retournent des éléments Group ou GroupedItems supplémentaires avec l’attribut xsi:nil défini sur true dans la réponse SOAP. Si vous utilisez l’API managée EWS, ces éléments supplémentaires entraînent la levée d’une exception ServiceXmlDeserializationException . Si vous utilisez EWS, ces éléments supplémentaires doivent être ignorés.
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