Realizar búsquedas agrupadas mediante EWS en Exchange
Obtenga información sobre cómo realizar búsquedas agrupadas en la API administrada de EWS o en la aplicación EWS destinada a Exchange.
Las búsquedas agrupadas son útiles porque le proporcionan control sobre cómo se organizan los resultados de la búsqueda. Los resultados de búsqueda organizados pueden facilitar a la aplicación procesar los resultados o mostrarlos a un usuario final de una manera fácil de administrar.
La agrupación funciona colocando todos los elementos del conjunto de resultados que tienen el mismo valor de un campo específico en un grupo. Por ejemplo, puede agrupar los resultados por el remitente y todos los elementos de la misma persona estarán en un grupo independiente y los elementos de cada grupo se ordenarán según el orden especificado en la vista. Los propios grupos se ordenan por un valor agregado en función de un campo que elija.
Tabla 1. Métodos de API administrada de EWS y operaciones de EWS para organizar resultados de búsqueda
| Si quiere... | En la API administrada de EWS, use… | En EWS, use… |
|---|---|---|
| Organizar elementos con el mismo valor en una propiedad específica en los resultados en grupos |
Grouping.GroupOn |
Elemento FieldURI como elemento secundario del elemento GroupBy |
| Ordenar elementos dentro de cada grupo por el valor de una propiedad específica |
ItemView.OrderBy |
Elemento SortOrder |
| Ordenar los grupos |
Grouping.AggregateOn Grouping.AggregateType Grouping.SortDirection |
Elemento FieldURI como elemento secundario del elemento AggregateOn Atributo Aggregate en el elemento AggregateOn Atributo Order en el elemento GroupBy |
Vamos a ir paso a paso.
Agrupar resultados por una propiedad específica
El primer paso para usar la agrupación es seleccionar una propiedad o atributo en los elementos del almacén de Exchange por el que agrupar. La API administrada de EWS las expone como propiedades de clase en las clases correspondientes, mientras que EWS las expone como elementos XML. Puede elegir cualquier propiedad, incluidas las propiedades personalizadas o extendidas, pero resulta útil comprender cómo se agrupan los elementos en función del valor de la propiedad que elija.
Todos los elementos que tengan el mismo valor en la propiedad por la que elija agrupar se agruparán. Esto puede parecer obvio, pero es un detalle importante. Tenga en cuenta lo que sucede si agrupa por una propiedad de fecha y hora, como Item.DateTimeReceived en la API administrada de EWS o el elemento DateTimeReceived en EWS. La intención podría ser organizar los resultados en grupos, con cada grupo que contenga elementos del mismo día. Sin embargo, la agrupación examina todo el valor, que incluye el tiempo.
El resultado final es que los elementos se agruparán para que los elementos recibidos al mismo tiempo, hasta el segundo, estén en sus propios grupos. Lo más probable es que los resultados se ordene en un gran número de grupos con un pequeño número de elementos en cada grupo.
Para obtener un conjunto de resultados con un número menor de grupos y un mayor número de elementos en cada grupo, elija una propiedad que probablemente tenga un número menor de valores, como EmailMessage.From o Item.Categories en la API administrada de EWS, o Desde o Categorías en EWS. En la ilustración siguiente se muestra una lista de correos electrónicos que aparecen en una bandeja de entrada.
Figura 1. Mensajes en una bandeja de entrada
Si agrupa los elementos de la figura 1 por la propiedad EmailMessage.From , el resultado será dos grupos, uno para los mensajes enviados por Hope Gross y otro para los mensajes enviados por Sadie Daniels.
Figura 2. Mensajes separados en grupos basados en la propiedad From
Ordenar los elementos dentro de grupos
Puede controlar cómo se ordenan los elementos dentro de cada grupo mediante la propiedad ItemView.OrderBy de la API administrada de EWS o el elemento SortOrder de EWS. El mismo orden se aplica a cada grupo. Por ejemplo, si ordena los elementos de la figura 1 por la propiedad Item.DateTimeReceived , en orden descendente, el elemento recibido más recientemente de Hope Gross será el primero en el grupo Hope Gross y el elemento recibido más recientemente de Sadie Daniels será el primero en el grupo Sadie Daniels. Convenientemente, los grupos de la figura 2 ya están ordenados de esta manera.
Ordenar los grupos
Ahora que tiene sus grupos establecidos, el paso final es ordenar los grupos por sí mismos. Dado que los propios grupos no tienen valores específicos, el proceso de agrupación tiene que asignar un valor de ordenación a cada grupo. Esto se realiza mediante la agregación de los valores de una propiedad específica dentro de cada grupo, especificada por la propiedad Grouping.AggregateOn en la API administrada de EWS, o el elemento FieldURI como elemento secundario del elemento AggregateOn en EWS. La propiedad Grouping.AggregateType de la API administrada de EWS (o el atributo Aggregate en el elemento AggregateOn de EWS) especifica qué valor de los elementos de cada grupo se asigna al valor de ordenación del grupo, ya sea el valor más grande o el valor más pequeño. Por último, la propiedad Grouping.SortDirection de la API administrada de EWS especifica el criterio de ordenación (descendente o ascendente) o el atributo Order en el elemento GroupBy de EWS.
Por ejemplo, si los grupos de la figura 2 se ordenan agregando en la propiedad Item.DateTimeReceived , usando el valor más pequeño y ordenando en orden descendente, los elementos se devuelven en el orden en que se muestra la figura 3.
Figura 3. Resultados de búsqueda agrupados con los grupos ordenados por la propiedad DateTimeReceived
En las secciones siguientes se muestra cómo se puede extraer la agrupación y ordenación en el código.
Ejemplo: Realizar una búsqueda agrupada mediante la API administrada de EWS
Los siguientes métodos de API administrada de EWS pueden usar la agrupación:
En el ejemplo siguiente se usa el método ExchangeService.FindItems ; sin embargo, las mismas reglas y conceptos se aplican al método Folder.FindItems . En este ejemplo, se define un método denominado GroupItemsByFrom . Toma un objeto ExchangeService y un objeto WellKnownFolderName como parámetros. Solicita los primeros 50 elementos de la carpeta, agrupados por la propiedad EmailMessage.From , ordenados por la propiedad Item.DateTimeReceived en orden descendente. Los propios grupos se ordenan por el valor de propiedad Item.DateTimeReceived más pequeño en sus elementos, en orden descendente.
En este ejemplo se asume que el objeto ExchangeService se ha inicializado con valores válidos en las propiedades Credentials y 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);
}
}
Ejemplo: Realizar una búsqueda agrupada mediante EWS
En el ejemplo de solicitud siguiente se muestra una solicitud de operación FindItem para los primeros 50 elementos de la carpeta, agrupados por el elemento From , ordenados por el elemento DateTimeReceived en orden descendente. Los propios grupos se ordenan por el valor de elemento DateTimeReceived más pequeño en sus elementos, en orden descendente.
<?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>
El servidor devuelve la siguiente respuesta.
<?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>
Diferencias de versión
Las versiones de Exchange a partir de la versión principal 15 y terminando con la compilación 15.0.775.38 devuelven elementos Group (de tipo GroupedItemsType) en lugar de elementos GroupedItems en la respuesta SOAP. Si usa la API administrada de EWS, esto hará que la colección GroupedFindItemsResults.ItemGroups contenga 0 objetos. Si usa EWS, los elementos Group deben controlarse como elementos GroupedItems .
Las versiones de Exchange a partir de la versión principal 15 devuelven elementos Group o GroupedItems adicionales con el atributo xsi:nil establecido en true en la respuesta SOAP. Si usa la API administrada de EWS, estos elementos adicionales harán que se produzca una excepción ServiceXmlDeserializationException . Si usa EWS, se deben omitir estos elementos adicionales.
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de