Durchführen gruppierter Suchen mithilfe von EWS in Exchange
Erfahren Sie, wie Sie gruppierte Suchvorgänge in Ihrer verwalteten EWS-API oder EWS-Anwendung ausführen, die auf Exchange ausgerichtet ist.
Gruppierte Suchvorgänge sind nützlich, da sie Ihnen die Kontrolle darüber geben, wie Suchergebnisse organisiert werden. Organisierte Suchergebnisse können es Ihrer Anwendung erleichtern, Ergebnisse zu verarbeiten oder einem Endbenutzer auf verwaltbare Weise anzuzeigen.
Die Gruppierung funktioniert, indem alle Elemente innerhalb des Resultsets, die denselben Wert eines bestimmten Felds aufweisen, in eine Gruppe aufgenommen werden. Beispielsweise können Sie Ihre Ergebnisse nach dem Absender gruppieren, und alle Elemente derselben Person befinden sich in einer separaten Gruppe, und die Elemente in jeder Gruppe werden entsprechend der Reihenfolge sortiert, die Sie in der Ansicht angeben. Die Gruppen selbst werden anhand eines Aggregatwerts sortiert, der auf einem von Ihnen ausgewählten Feld basiert.
Tabelle 1. Verwaltete EWS-API-Methoden und EWS-Vorgänge zum Organisieren von Suchergebnissen
| Aktion | Verwalten Sie in der verwalteten EWS-API... | Verwalten Sie in EWS... |
|---|---|---|
| Organisieren von Elementen mit dem gleichen Wert in einer bestimmten Eigenschaft in Ihren Ergebnissen in Gruppen |
Grouping.GroupOn |
FieldURI-Element als untergeordnetes Element des GroupBy-Elements |
| Sortieren von Elementen innerhalb jeder Gruppe nach dem Wert in einer bestimmten Eigenschaft |
ItemView.OrderBy |
SortOrder-Element |
| Sortieren der Gruppen |
Grouping.AggregateOn Grouping.AggregateType Grouping.SortDirection |
FieldURI-Element als untergeordnetes Element des AggregateOn-Elements Aggregate-Attribut für das AggregateOn-Element Order-Attribut für das GroupBy-Element |
Gehen wir schritt für Schritt vor.
Gruppieren von Ergebnissen nach einer bestimmten Eigenschaft
Der erste Schritt bei der Verwendung der Gruppierung besteht darin, eine Eigenschaft oder ein Attribut für die Elemente im Exchange-Speicher auszuwählen, nach denen gruppiert werden soll. Die verwaltete EWS-API macht diese als Klasseneigenschaften für die entsprechenden Klassen verfügbar, während EWS sie als XML-Elemente verfügbar macht. Sie können eine beliebige Eigenschaft auswählen, einschließlich benutzerdefinierter oder erweiterter Eigenschaften, aber es ist hilfreich zu verstehen, wie Elemente basierend auf dem Wert der ausgewählten Eigenschaft gruppiert werden.
Alle Elemente, die denselben Wert in der Eigenschaft aufweisen, nach der Sie gruppieren möchten, werden gruppiert. Dies mag offensichtlich erscheinen, aber es ist ein wichtiges Detail. Überlegen Sie, was geschieht, wenn Sie nach einer Datums-/Uhrzeiteigenschaft gruppieren, z . B. Item.DateTimeReceived in der verwalteten EWS-API oder das DateTimeReceived-Element in EWS. Die Absicht könnte sein, die Ergebnisse in Gruppen zu organisieren, wobei jede Gruppe Elemente vom selben Tag enthält. Bei der Gruppierung wird jedoch der gesamte Wert betrachtet, der die Zeit einschließt.
Das Endergebnis ist, dass die Elemente so gruppiert werden, dass sich die gleichzeitig empfangenen Elemente bis zur Sekunde in ihren eigenen Gruppen befinden. Die Ergebnisse werden höchstwahrscheinlich in eine große Anzahl von Gruppen mit einer kleinen Anzahl von Elementen in jeder Gruppe sortiert.
Um ein Resultset mit einer kleineren Anzahl von Gruppen und einer größeren Anzahl von Elementen in jeder Gruppe zu erhalten, wählen Sie eine Eigenschaft aus, die wahrscheinlich eine kleinere Anzahl von Werten aufweist, z. B. EmailMessage.From oder Item.Categories in der verwalteten EWS-API oder From oder Categories in EWS. Die folgende Abbildung zeigt eine Liste der E-Mails, die in einem Posteingang angezeigt werden.
Abbildung 1: Nachrichten in einem Posteingang
Wenn Sie die Elemente in Abbildung 1 nach der Eigenschaft EmailMessage.From gruppiert haben, ergeben sich zwei Gruppen: eine für Nachrichten, die von Hope Gross gesendet werden, und eine für nachrichten, die von Sadie Daniels gesendet werden.
Abbildung 2: Nachrichten, die basierend auf der From-Eigenschaft in Gruppen unterteilt sind
Sortieren der Elemente innerhalb von Gruppen
Sie können steuern, wie Elemente innerhalb jeder Gruppe sortiert werden, indem Sie die ItemView.OrderBy-Eigenschaft in der verwalteten EWS-API oder das SortOrder-Element in EWS verwenden. Die gleiche Reihenfolge gilt für jede Gruppe. Wenn Sie beispielsweise die Elemente aus Abbildung 1 nach der Item.DateTimeReceived-Eigenschaft in absteigender Reihenfolge sortieren, wird das Element, das zuletzt von Hope Gross empfangen wurde, zuerst in der Gruppe Hope Gross angezeigt, und das Element, das zuletzt von Sadie Daniels empfangen wurde, befindet sich an erster Stelle in der Sadie Daniels-Gruppe. Praktischerweise sind die Gruppen in Abbildung 2 bereits auf diese Weise sortiert.
Sortieren der Gruppen
Nachdem Sie Ihre Gruppen nun festgelegt haben, ist der letzte Schritt das Sortieren der Gruppen selbst. Da die Gruppen selbst keine bestimmten Werte haben, muss der Gruppierungsprozess jeder Gruppe einen Sortierwert zuweisen. Dies erfolgt durch aggregation der Werte einer bestimmten Eigenschaft innerhalb jeder Gruppe, die durch die Grouping.AggregateOn-Eigenschaft in der verwalteten EWS-API oder das FieldURI-Element als untergeordnetes Element des AggregateOn-Elements in EWS angegeben wird. Die Grouping.AggregateType-Eigenschaft in der verwalteten EWS-API (oder das Aggregate-Attribut für das AggregateOn-Element in EWS) gibt an, welcher Wert aus den Elementen in jeder Gruppe dem Sortierwert für die Gruppe zugewiesen wird – entweder dem größten wert oder dem kleinsten Wert. Schließlich wird die Sortierreihenfolge (absteigend oder aufsteigend) durch die Grouping.SortDirection-Eigenschaft in der verwalteten EWS-API oder das Order-Attribut für das GroupBy-Element in EWS angegeben.
Wenn die Gruppen aus Abbildung 2 beispielsweise durch Aggregieren nach der Item.DateTimeReceived-Eigenschaft sortiert werden, wobei der kleinste Wert verwendet und in absteigender Reihenfolge sortiert wird, werden die Elemente in der in Abbildung 3 gezeigten Reihenfolge zurückgegeben.
Abbildung 3: Gruppierte Suchergebnisse mit den Gruppen, die nach der DateTimeReceived-Eigenschaft sortiert sind
In den nächsten Abschnitten wird gezeigt, wie Sie gruppieren und sortieren im Code zusammenziehen können.
Beispiel: Ausführen einer gruppierten Suche mithilfe der verwalteten EWS-API
Die folgenden EWS Managed API-Methoden können gruppieren:
Im folgenden Beispiel wird die ExchangeService.FindItems-Methode verwendet. Die gleichen Regeln und Konzepte gelten jedoch für die Folder.FindItems-Methode . In diesem Beispiel wird eine Methode namens GroupItemsByFrom definiert. Als Parameter werden ein ExchangeService-Objekt und ein WellKnownFolderName-Objekt verwendet. Sie fordert die ersten 50 Elemente im Ordner an, gruppiert nach der EmailMessage.From-Eigenschaft , sortiert nach der Item.DateTimeReceived-Eigenschaft in absteigender Reihenfolge. Die Gruppen selbst werden nach dem kleinsten Item.DateTimeReceived-Eigenschaftswert für ihre Elemente in absteigender Reihenfolge sortiert.
In diesem Beispiel wird davon ausgegangen, dass das ExchangeService-Objekt mit gültigen Werten in den Credentials- und Url-Eigenschaften initialisiert wurde.
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);
}
}
Beispiel: Ausführen einer gruppierten Suche mithilfe von EWS
Das folgende Anforderungsbeispiel zeigt eine FindItem-Vorgangsanforderung für die ersten 50 Elemente im Ordner, gruppiert nach dem From-Element , sortiert nach dem DateTimeReceived-Element in absteigender Reihenfolge. Die Gruppen selbst werden nach dem kleinsten DateTimeReceived-Elementwert für ihre Elemente in absteigender Reihenfolge sortiert.
<?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" />
<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>
Der Server gibt die folgende Antwort zurück.
<?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="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://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>
Versionsunterschiede
Versionen von Exchange, die mit Hauptversion 15 beginnen und mit Build 15.0.775.38 enden, geben Group-Elemente (vom Typ GroupedItemsType) anstelle von GroupedItems-Elementen in der SOAP-Antwort zurück. Wenn Sie die verwaltete EWS-API verwenden, führt dies dazu, dass die GroupedFindItemsResults.ItemGroups-Auflistung 0 Objekte enthält. Wenn Sie EWS verwenden, sollten Group-Elemente als GroupedItems-Elemente behandelt werden.
Versionen von Exchange ab Hauptversion 15 geben zusätzliche Group- oder GroupedItems-Elemente zurück, deren xsi:nil-Attribut in der SOAP-Antwort auf true festgelegt ist. Wenn Sie die verwaltete EWS-API verwenden, führen diese zusätzlichen Elemente dazu, dass eine ServiceXmlDeserializationException ausgelöst wird. Wenn Sie EWS verwenden, sollten diese zusätzlichen Elemente ignoriert werden.