Exchange で EWS を使用して、グループ化された検索を実行するPerform grouped searches by using EWS in Exchange

EWS マネージ API または Exchange を対象とする EWS アプリケーションで、グループ化された検索を実行する方法を説明します。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. 検索結果を整理するための EWS マネージ API のメソッドと EWS 操作Table 1. EWS Managed API methods and EWS operations for organizing search results

目的…If you want to… EWS マネージ API で使用するもの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
Grouping.GroupOnGrouping.GroupOn
GroupBy 要素の子としての FieldURI 要素FieldURI element as a child of the GroupBy element
特定のプロパティの値によって各グループ内でアイテムを並べ替えるSort items within each group by the value in a specific property
ItemView.OrderByItemView.OrderBy
SortOrder 要素SortOrder element
グループを並べ替えるSort the groups
Grouping.AggregateOnGrouping.AggregateOn

Grouping.AggregateTypeGrouping.AggregateType

Grouping.SortDirectionGrouping.SortDirection
AggregateOn 要素の子としての FieldURI 要素FieldURI element as a child of the AggregateOn element

AggregateOn 要素の Aggregate 属性Aggregate attribute on the AggregateOn element

GroupBy 要素の Order 属性Order 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. EWS マネージ API はこれらを対応するクラスのクラス プロパティとして公開するのに対し、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. EWS マネージ API の Item.DateTimeReceived、または EWS の DateTimeReceived 要素など、日付/時刻プロパティでグループ化するとどうなるかを考えてみましょう。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.

グループの数が少なくかつ各グループでアイテムの数が多い結果セットを取得するには、値の数が少ない可能性の高いプロパティ (EWS マネージ API の EmailMessage.From または Item.Categories、または EWS の From または Categories など) を選択します。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

ユーザーの [受信トレイ] のメッセージのサンプル リスト。

EmailMessage.From プロパティで図 1 のアイテムをグループ化すると、2 つのグループに分けられます。1 つは Hope Gross から送信されたメッセージで、もう 1 つは Sadie Daniels から送信されたメッセージです。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. From プロパティに基づいてグループ分けされたメッセージFigure 2. Messages separated into groups based on the From property

From プロパティで 2 つのリストに分類されたメッセージを表示したイメージ。

グループ内でアイテムを並べ替えるSort the items within groups

EWS マネージ API の ItemView.OrderBy プロパティ、または EWS の SortOrder 要素を使用して、各グループ内でアイテムを並べ替える方法を制御することができます。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. たとえば、Item.DateTimeReceived プロパティで図 1 のアイテムを降順に並べ替えると、Hope Gross から受信した最新のアイテムが Hope Gross グループの一番上になります。また、Sadie Daniels から受信した最新のアイテムは Sadie Daniels グループの一番上になります。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. これを行うには、EWS マネージ API の Grouping.AggregateOn プロパティ、または EWS の AggregateOn 要素の子としての FieldURI 要素で指定して、各グループ内で特定のプロパティの値を集約します。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. EWS マネージ API の Grouping.AggregateType プロパティ (または EWS の AggregateOn 要素の Aggregate 属性) は、グループの並べ替え対象の値 (最大値または最小値のいずれか) として割り当てる各グループ内のアイテムの値を指定します。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. 最後に、並べ替えの順序 (降順または昇順) を、EWS マネージ API の Grouping.SortDirection プロパティまたは EWS の GroupBy 要素の Order 属性で指定します。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. DateTimeReceived プロパティによって並べ替えられたグループでのグループ化された検索結果Figure 3. Grouped search results with the groups sorted by the DateTimeReceived property

From プロパティでグループ化された、並べ替えられたメッセージのリストを表示しているイメージ。グループは最小の受信日時で並び替えられています。

次のセクションでは、コードでグループ化と並べ替えをまとめてプルする方法を説明します。The next sections show you how you might pull grouping and sorting together in code.

例: EWS マネージ API を使用して、グループ化された検索を実行するExample: Perform a grouped search by using the EWS Managed API

次の EWS マネージ API メソッドではグループ化を使用できます。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. この例では、GroupItemsByFrom と呼ばれるメソッドが定義されます。In this example, a method called GroupItemsByFrom is defined. パラメーターとして、ExchangeService オブジェクトと WellKnownFolderName オブジェクトを使用します。It takes an ExchangeService object and a WellKnownFolderName object as parameters. EmailMessage.From プロパティでグループ化し Item.DateTimeReceived プロパティで降順に並べ替えた、フォルダー内の最初の 50 アイテムを要求します。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);
    }
}

例: EWS を使用して、グループ化された検索を実行するExample: Perform a grouped search by using EWS

次の要求例では、From 要素でグループ化し DateTimeReceived 要素で降順に並べ替えた、フォルダー内の最初の 50 アイテムに対する FindItem 操作要求を示します。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

メジャー バージョン 15 以降のビルド 15.0.775.38 以前のバージョンの Exchange では、SOAP 応答で GroupedItems 要素の代わりに Group 要素 (型 GroupedItemsType) が返されます。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. EWS マネージ API を使用している場合、これは GroupedFindItemsResults.ItemGroups コレクションに含まれるオブジェクトが 0 になる原因になります。If you are using the EWS Managed API, this will cause the GroupedFindItemsResults.ItemGroups collection to contain 0 objects. EWS を使用している場合は、Group 要素は GroupedItems 要素として処理される必要があります。If you are using EWS, Group elements should be handled as GroupedItems elements.

メジャー バージョン 15 以降のバージョンの Exchange では、SOAP 応答で true に設定された xsi:nil 属性を持つ追加の Group 要素または GroupedItems 要素が返されます。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. EWS マネージ API を使用している場合、これらの追加の要素は ServiceXmlDeserializationException がスローされる原因となります。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