Выполнение группового поиска с помощью EWS в ExchangePerform grouped searches by using EWS in Exchange

Узнайте, как выполнять группировку поисков в управляемом API EWS или приложении EWS, предназначенном для Exchange.Find out how to perform grouped searches in your EWS Managed API or EWS application that targets Exchange.

Сгруппированные поиски удобны в том, что они дают вам возможность контролировать организацию результатов поиска.Grouped searches are useful in that they gives you control over how search results are organized. Упорядоченные результаты поиска могут облегчить приложению обработку результатов или отобразить их конечному пользователю в управляемом виде.Organized search results can make it easier for your application to process results or display them to an end user in a manageable way.

Группирование заключается в размещении всех элементов в наборе результатов с одинаковым значением определенного поля в группе.Grouping works by putting all items within the result set that have the same value of a specific field into a group. Например, вы можете группировать результаты по отправителю, и все элементы из одного лица будут находиться в отдельной группе, а элементы в каждой группе будут отсортированы в соответствии с порядком, указанным в представлении.For example, you can group your results by the sender, and all items from the same person will be in a separate group, and the items within each group will be sorted according to the order you specify on the view. Сами группы сортируются по статистическому значению, основанному на выбранном поле.The groups themselves are sorted by an aggregate value based on a field you choose.

Таблица 1. Методы управляемого API EWS и операции EWS для организации результатов поискаTable 1. EWS Managed API methods and EWS operations for organizing search results

ЗадачаIf you want to… В управляемом API EWS используйте...In the EWS Managed API, use… В EWS используйте...In EWS, use…
Упорядочение элементов с одинаковым значением в определенном свойстве в результатах по группамOrganize items with the same value in a specific property in your results into groups
Группирование. GroupOnGrouping.GroupOn
Элемент фиелдури в качестве дочернего элемента для элемента GroupByFieldURI element as a child of the GroupBy element
Сортировка элементов в каждой группе по значению в определенном свойствеSort items within each group by the value in a specific property
Итемвиев. OrderByItemView.OrderBy
Элемент SortOrderSortOrder element
Сортировка группSort the groups
GROUPING. АггрегатеонGrouping.AggregateOn

GROUPING. АггрегатетипеGrouping.AggregateType

GROUPING. SortDirectionGrouping.SortDirection
Элемент фиелдури в качестве дочернего элемента для элемента аггрегатеонFieldURI element as a child of the AggregateOn element

Статистический атрибут для элемента аггрегатеонAggregate attribute on the AggregateOn element

Атрибут Order для элемента GroupByOrder attribute on the GroupBy element

Давайте попробуем пошаговое выполнение.Let's take it step by step.

Группировка результатов по определенному свойствуGroup results by a specific property

Первый шаг по использованию группирования — выбор свойства или атрибута элементов в хранилище Exchange для группировки по.The first step to using grouping is to select a property, or attribute on the items in the Exchange store, to group by. Управляемый API EWS предоставляет эти свойства классам в соответствующих классах, а EWS представляет их в виде элементов XML.The EWS Managed API exposes these as class properties on the corresponding classes, while EWS exposes them as XML elements. Вы можете выбрать любое свойство, включая настраиваемые или расширенные свойства, но при этом полезно знать, как группируются элементы в зависимости от значения свойства, которое вы выбрали.You can choose any property, including custom or extended properties, but it is helpful to understand how items are grouped based on the value of the property you choose.

Все элементы, имеющие одинаковое значение в свойстве, выбранном для группировки, будут сгруппированы вместе.All items that have the same value in the property you choose to group by will be grouped together. Это может показаться очевидным, но это очень важная информация.This might seem obvious, but it is an important detail. Обратите внимание на то, что происходит при группировке по свойству даты и времени, например Item. DateTimeReceived в УПРАВЛЯЕМОМ API EWS или элемент DateTimeReceived в EWS.Consider what happens if you group by a date/time property, such as Item.DateTimeReceived in the EWS Managed API, or the DateTimeReceived element in EWS. Цель может быть упорядочена по группам, при этом каждая группа содержит элементы из одного дня.The intent might be to organize the results into groups, with each group containing items from the same day. Тем не менее, группирование просматривает все значение, которое включает время.However, grouping looks at the entire value, which includes the time.

Конечный результат заключается в том, что элементы будут сгруппированы, так что одновременно получаемые элементы перемещаются в свои группы.The end result is that the items will be grouped so that items received at the same time, down to the second, are in their own groups. Скорее всего, результаты будут отсортированы в большом количестве групп с небольшим количеством элементов в каждой группе.The results will most likely be sorted into a large number of groups with a small number of items in each group.

Чтобы получить набор результатов с небольшим количеством групп и большим количеством элементов в каждой группе, выберите свойство, которое может иметь меньшее количество значений, например EmailMessage. from или Item. Categories в управляемом API EWS или из категорий в EWS.To get a results set with a smaller number of groups and a larger number of items in each group, choose a property that is likely to have a smaller number of values, such as EmailMessage.From or Item.Categories in the EWS Managed API, or From or Categories in EWS. На следующем рисунке показан список сообщений электронной почты, которые отображаются в папке "Входящие".The following figure shows a list of emails that appear in an Inbox.

Рис. 1. Сообщения в папке "Входящие"Figure 1. Messages in an Inbox

Пример списка сообщений в папке "Входящие".

Если сгруппировать элементы на рис. 1 по свойству EmailMessage. from , то результатом будет две группы, одна для сообщений, отправленных с "счастливых брутто", а другой для сообщений, отправляемых Ольга Даниелс.If you group the items in Figure 1 by the EmailMessage.From property, the result will be two groups, one for messages sent by Hope Gross, and one for messages sent by Sadie Daniels.

Рис. 2. Сообщения, разделенные на группы на основе свойства FromFigure 2. Messages separated into groups based on the From property

Изображение, на котором показаны сообщения, рассортированные по двум спискам согласно свойству "От".

Сортировка элементов в группахSort the items within groups

Вы можете управлять сортировкой элементов в каждой группе с помощью свойства итемвиев. OrderBy в УПРАВЛЯЕМОМ API EWS или элемента SortOrder в EWS.You can control how items are sorted within each group by using the ItemView.OrderBy property in the EWS Managed API, or the SortOrder element in EWS. Один и тот же порядок применяется к каждой группе.The same ordering applies to each group. Например, если Вы отсортируете элементы на рис. 1 по свойству Item. DateTimeReceived , в убывающем порядке, самый последний полученный из них элемент будет первым в группе вероятнее всего, а последний, полученный из Ольга Даниелс, будет первым в группе Ольга Даниелс.For example, if you sort the items from Figure 1 by the Item.DateTimeReceived property, in descending order, the item most recently received from Hope Gross will be first in the Hope Gross group, and the item most recently received from Sadie Daniels will be first in the Sadie Daniels group. С легкостью, группы на рисунке 2 уже отсортированы таким образом.Conveniently, the groups in Figure 2 are already sorted this way.

Сортировка группSort the groups

Теперь, когда ваши группы сопоставлены, последним шагом будет сортировка самих групп.Now that you have your groups settled, the final step is sorting the groups themselves. Так как сами группы не имеют определенных значений, процесс группирования должен назначить значение сортировки каждой группе.Because the groups themselves have no specific values, the grouping process has to assign a sort value to each group. Это выполняется путем объединения значений определенного свойства в каждой группе, заданного свойством Group. аггрегатеон в УПРАВЛЯЕМОМ API EWS, или элементом фиелдури в качестве дочернего элемента для элемента аггрегатеон в EWS.This is done by aggregation of the values of a specific property within each group, specified by the Grouping.AggregateOn property in the EWS Managed API, or the FieldURI element as a child of the AggregateOn element in EWS. Свойство Group. аггрегатетипе в УПРАВЛЯЕМОМ API EWS (или атрибут Aggregate для элемента аггрегатеон в EWS) указывает, какое значение из элементов в каждой группе назначается значению сортировки для группы — либо наибольшее значение, либо наименьшее значение.The Grouping.AggregateType property in the EWS Managed API (or the Aggregate attribute on the AggregateOn element in EWS) specifies which value from the items within each group is assigned to the sort value for the group — either the largest value or the smallest value. Наконец, порядок сортировки (по убыванию или по возрастанию) задается свойством Group. SortDirection в УПРАВЛЯЕМОМ API EWS или атрибутом Order для элемента GroupBy в веб-службах EWS.Finally, the sort order (descending or ascending) is specified by the Grouping.SortDirection property in the EWS Managed API, or the Order attribute on the GroupBy element in EWS.

Например, если группы, показанные на рисунке 2, отсортированы по статистической обработке свойства Item. DateTimeReceived с наименьшим значением и сортировка по убыванию, элементы возвращаются в порядке, приведенном на рисунке 3.For example, if the groups from Figure 2 are sorted by aggregating on the Item.DateTimeReceived property, using the smallest value, and sorting in descending order, the items are returned in the order in shown Figure 3.

Рис. 3. Сгруппированные результаты поиска с группами, отсортированными по свойству DateTimeReceivedFigure 3. Grouped search results with the groups sorted by the DateTimeReceived property

Изображение, на котором показан отсортированный список сообщений, сгруппированный по свойству "От", где группы отсортированы по наименьшим времени и дате получения.

В следующих разделах показано, как можно забирать группирование и сортировку в коде.The next sections show you how you might pull grouping and sorting together in code.

Пример: выполнение группового поиска с помощью управляемого API EWSExample: Perform a grouped search by using the EWS Managed API

Следующие методы управляемого API EWS могут использовать группировку:The following EWS Managed API methods can use grouping:

В следующем примере используется метод ExchangeService. FindItems ; Тем не менее те же правила и концепции применяются к методу Folder. FindItems .The following example uses the ExchangeService.FindItems method; however, the same rules and concepts apply to the Folder.FindItems method. В этом примере определен метод под названием граупитемсбифром .In this example, a method called GroupItemsByFrom is defined. В качестве параметров в качестве параметров используется объект ExchangeService и объект веллкновнфолдернаме .It takes an ExchangeService object and a WellKnownFolderName object as parameters. Он запрашивает первые 50 элементов в папке, сгруппированные по свойству EmailMessage. from , отсортированному по свойству Item. DateTimeReceived в убывающем порядке.It requests the first 50 items in the folder, grouped by the EmailMessage.From property, sorted by the Item.DateTimeReceived property in descending order. Сами группы сортируются по наименьшему значению свойства Item. DateTimeReceived в их элементах в порядке убывания.The groups themselves are sorted by the smallest Item.DateTimeReceived property value on their items, in descending order.

В этом примере предполагается, что для объекта ExchangeService выполнена инициализация с допустимыми значениями в свойствах Credentials и Url.This example assumes that the ExchangeService object has been initialized with valid values in the Credentials and Url properties.

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

Пример: выполнение группового поиска с помощью EWSExample: Perform a grouped search by using EWS

В следующем примере запроса показан запрос операции FindItem для первых 50 элементов в папке, сгруппированных по элементу from и отсортированный по элементу DateTimeReceived в убывающем порядке.The following request example shows a FindItem operation request for the first 50 items in the folder, grouped by the From element, sorted by the DateTimeReceived element in descending order. Сами группы сортируются по наименьшему значению элемента DateTimeReceived в их элементах в убывающем порядке.The groups themselves are sorted by the smallest DateTimeReceived element value on their items, in descending order.

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

Сервер возвращает следующий ответ.The server returns the following response.

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

Различия версийVersion differences

Версии Exchange, начиная с основной версии 15 и заканчивая сборкой 15.0.775.38, возвращают элементы группы (типа граупедитемстипе) вместо элементов граупедитемс в ответе SOAP.Versions of Exchange starting with major version 15 and ending with build 15.0.775.38 return Group elements (of type GroupedItemsType) in place of GroupedItems elements in the SOAP response. Если вы используете управляемый API EWS, это приведет к тому, что коллекция граупедфиндитемсресултс. итемграупс будет содержать 0 объектов.If you are using the EWS Managed API, this will cause the GroupedFindItemsResults.ItemGroups collection to contain 0 objects. Если вы используете EWS, элементы Group должны обрабатываться как элементы граупедитемс .If you are using EWS, Group elements should be handled as GroupedItems elements.

Версии Exchange, начиная с основной версии 15, возвращают дополнительные элементы Group или граупедитемс с атрибутом xsi: nil со значением true в ответе SOAP.Versions of Exchange starting with major version 15 return extra Group or GroupedItems elements with the xsi:nil attribute set to true in the SOAP response. Если вы используете управляемый API EWS, эти дополнительные элементы приведут к созданию сервицексмлдесериализатионексцептион .If you are using the EWS Managed API, these extra elements will cause a ServiceXmlDeserializationException to be thrown. Если вы используете EWS, эти дополнительные элементы следует игнорировать.If you are using EWS, these extra elements should be ignored.

См. такжеSee also