Realizar una búsqueda de AQS mediante EWS en Exchange

Artículo
03/29/2023

Obtenga información sobre cómo buscar con cadenas de consulta y AQS en la API administrada de EWS o la aplicación EWS.

Las cadenas de consulta proporcionan una alternativa a los filtros de búsqueda para expresar criterios de búsqueda. La mayor ventaja de usar cadenas de consulta es que no es necesario especificar una sola propiedad para buscar. Solo puede proporcionar un valor y la búsqueda se aplicará a todos los campos usados habitualmente en los elementos. También puede refinar la búsqueda mediante la sintaxis de consulta avanzada (AQS) en lugar de un valor simple. Sin embargo, las cadenas de consulta tienen las siguientes limitaciones que debe tener en cuenta antes de agregarlas al cuadro de herramientas:

Capacidad limitada para buscar propiedades específicas. Al buscar con un valor simple en una cadena de consulta, la búsqueda se realiza en todas las propiedades indizadas. Puede refinar la búsqueda a propiedades específicas, pero las propiedades disponibles para su uso en una cadena de AQS son limitadas. Si la propiedad que desea buscar no es una de las propiedades que están disponibles para AQS, considere la posibilidad de usar un filtro de búsqueda.
No se buscan propiedades personalizadas. Las búsquedas de cadenas de consulta se realizan en un índice y las propiedades personalizadas no se incluyen en ese índice. Si necesita buscar propiedades personalizadas, use un filtro de búsqueda en su lugar.
Control limitado para las búsquedas de cadenas. Las búsquedas de cadenas de consulta siempre omiten mayúsculas y minúsculas y siempre son búsquedas de subcadenas. Si desea realizar búsquedas con distinción entre mayúsculas y minúsculas, prefijo o coincidencia exacta, use un filtro de búsqueda.
No está disponible para carpetas o carpetas de búsqueda. Las operaciones de EWS para buscar carpetas no admiten el uso de una cadena de consulta. Además, las carpetas de búsqueda no admiten cadenas de consulta. En ambos casos, un filtro de búsqueda es la única opción.

Creación de una cadena de consulta

Las cadenas de consulta de la API administrada de EWS y EWS se interpretan como un subconjunto de la sintaxis de AQS. Las cadenas de AQS se componen de valores o pares de palabras clave/valor, separados por dos puntos (:).

keyword:value

Cuando se especifica un valor sin una palabra clave, se busca el valor en todas las propiedades indizadas. Si una palabra clave está emparejada con un valor, la palabra clave especifica una propiedad para buscar el valor correspondiente.

Tabla 1. Palabras clave de AQS admitidas

Palabra clave	Tipo de valor	Ejemplo
subject	Cadena	subject:project
body	Cadena	body:sales figures
datos adjuntos	Cadena	attachment:report
a	Cadena	to:"Sadie Daniels"
from	Cadena	from:hope
cc	Cadena	cc:"Ronnie Sturgis"
cco	Cadena	bcc:mack
participants	Cadena	participants:sadie
categoría	Cadena	category:project
importance	String	importance:alta
kind	Tipo de elemento	kind:meetings
sent	Fecha	enviado:12/10/2013
received	Fecha	received:yesterday
hasattachment	Boolean	Tiene attachment:true
isflagged	Boolean	isflagged:true
isread	Boolean	isread:false
size	Número	size:>5000

Echemos un vistazo a cómo funcionan los distintos tipos de valor.

Uso de un tipo de valor de cadena

Los tipos de valor de cadena se buscan de forma predeterminada como búsquedas de subcadenas de prefijo que no distinguen mayúsculas de minúsculas. Esto significa que la búsqueda de subject:project coincidiría con cualquiera de los temas siguientes:

Notas de la reunión del proyecto
¿Tiene los planes del proyecto?
Proyecciones de ventas de diciembre

Puede cambiar la búsqueda para que requiera toda la palabra en lugar de coincidir con prefijos; para ello, incluya la cadena entre comillas. La búsqueda de subject:"project" eliminaría el valor "Proyecciones de ventas de diciembre" de la lista de coincidencias. Tenga en cuenta que el valor todavía no distingue mayúsculas de minúsculas.

Si usa varias palabras en una cadena de consulta, una coincidencia requiere que ambas palabras aparezcan en los campos buscados. Por ejemplo, la búsqueda de un plan subject:project coincidiría con cualquiera de los siguientes temas:

Plan de proyecto
¿Tiene los planes del proyecto?
Por favor, envíeme el plan para nuestro proyecto.
Planeamiento de hitos del proyecto

Si incluye varias palabras entre comillas, se tratan como una sola frase. La búsqueda de subject:"project plan" solo coincidiría con el asunto "Plan de proyecto" de la lista anterior.

Uso de un tipo de valor de tipo de elemento

Puede usar los siguientes valores de tipo de elemento con la palabra clave kind para limitar los resultados de la búsqueda a solo un tipo específico de elemento, como correo electrónico o convocatorias de reunión:

contacts
documentos
correo electrónico
faxes
im (corresponde a mensajes instantáneos)
diarios
reuniones (corresponde a citas y convocatorias de reunión)
notas
entradas
fuentes rss
tareas
correo de voz

Uso de un tipo de valor de fecha

Puede buscar tipos de valor de fecha de varias maneras diferentes. Lo más sencillo es buscar una fecha específica. La búsqueda con recibido:12/11/2013 devolverá todos los elementos recibidos el 11 de diciembre de 2013. Sin embargo, también puede ser menos específico. La búsqueda con recibido:12/11 devolverá todos los elementos recibidos el 11 de diciembre del año en curso.

Otra opción es usar los nombres de mes. Puede buscar con recibido:11 de diciembre de 2013 o 11 de diciembre para obtener los mismos resultados que recibidos:12/11/2013 y recibidos:12/11, respectivamente. También puede buscar con received:December para obtener todos los elementos recibidos en el mes de diciembre, en el año actual.

El uso de los nombres de los días de la semana también es una opción. La búsqueda con recibido:Martes devolverá todos los elementos recibidos el martes de la semana actual.

Los tipos de valor de fecha también admiten un conjunto de palabras clave para las búsquedas relativas a la hora actual. Se admiten las siguientes palabras clave:

hoy
tomorrow
yesterday
this week
La semana pasada
próximo mes
mes pasado
próximo año

Los tipos de valor de fecha también se pueden comparar con operadores relacionales como mayor o menor que, o se especifican como un intervalo con el operador de intervalo ... Por ejemplo, received:>11/30/2013, sent:>=yesterday y received:12/1/2013..today son todas cadenas de consulta válidas.

Uso de un tipo de valor booleano

Los tipos de valor booleano pueden ser "true" o "false". Los valores no distinguen mayúsculas de minúsculas, por lo que isread:false generará los mismos resultados que isread:FALSE.

Uso de un tipo de valor de número

Los tipos de valor numérico se pueden buscar como coincidencias exactas, pero también se pueden buscar mediante operadores relacionales como mayor o menor que. Por ejemplo, size:10000 devolverá solo los elementos que tengan un tamaño de exactamente 10000 bytes, pero size:>=10000 devolverá elementos que tengan un tamaño mayor o igual que 10000 bytes. También puede especificar un intervalo mediante el operador range ( ..). Por ejemplo, size:7000..8000 devolverá elementos que tengan un tamaño entre 7000 y 8000.

Uso de operadores lógicos

Las cadenas de consulta admiten los siguientes operadores lógicos.

Tabla 2. Operadores lógicos admitidos

Operador	Ejemplos
Y	proyecto Y de:"Sadie Daniels" subject:(project AND plan)
O	subject:meeting OR from:"Hope Gross" from:("Sadie Daniels" O "Hope Gross")
NOT	NO de:"Ronnie Sturgis" received:NOT today

Tenga en cuenta que puede usar estos operadores para combinar varios criterios o combinar varios valores dentro de un único par de palabras clave-valor. Sin embargo, al combinar varios valores en un único par de palabras clave/valor, debe usar paréntesis para incluir los valores múltiples. Para entender por qué, considere la posibilidad de buscar desde:"Sadie Daniels" o "Hope Gross". En realidad, esta búsqueda se interpreta como los siguientes criterios:

El elemento es de Sadie Daniels, OR
El elemento tiene la frase "Hope Gross" en cualquiera de sus propiedades indizadas.

Por el contrario, de:("Sadie Daniels" O "Hope Gross") se interpreta como:

El elemento es de Sadie Daniels, OR
El elemento es de Hope Gross

El operador predeterminado cuando se especifican varios criterios, pero no se incluye ningún operador lógico es AND. Por ejemplo, tiene attachment:true subject:project es equivalente a has:attachment:true AND subject:project.

Ejemplo: Búsqueda de elementos mediante una cadena de consulta y la API administrada de EWS

En este ejemplo, se define un método denominado SearchWithQueryString . Toma un objeto ExchangeService , un objeto WellKnownFolderName y un objeto de cadena que representa la cadena de consulta como parámetros. En este ejemplo se asume que el objeto ExchangeService se ha inicializado con valores válidos en las propiedades Credentials y Url.

using Microsoft.Exchange.WebServices.Data;
static void SearchWithQueryString(ExchangeService service, WellKnownFolderName folder, string queryString)
{
    // Limit the result set to 10 items.
    ItemView view = new ItemView(10);
    view.PropertySet = new PropertySet(ItemSchema.Subject,
                                       ItemSchema.DateTimeReceived,
                                       ItemSchema.Size,
                                       ItemSchema.Importance,
                                       EmailMessageSchema.IsRead);
    // Item searches do not support Deep traversal.
    view.Traversal = ItemTraversal.Shallow;
    // Sorting
    view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);
    try
    {
        // Execute the search based on the query string.
        // Example: "subject:project plan"
        FindItemsResults<Item> results = service.FindItems(folder, queryString, view);
        foreach (Item item in results.Items)
        {
            Console.WriteLine("Subject: {0}", item.Subject);
            Console.WriteLine("Received: {0}", item.DateTimeReceived.ToString());
            Console.WriteLine("Size: {0}", item.Size.ToString());
            Console.WriteLine("Importance: {0}", item.Importance.ToString());
            if (item is EmailMessage)
            {
                EmailMessage message = item as EmailMessage;
                Console.WriteLine("Read: {0}", message.IsRead.ToString());
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
    }
}

Puede usar este método para buscar todos los elementos con la frase "plan de proyecto" en el asunto, como se muestra en este ejemplo.

string queryString = "subject:\"project plan\"";
SearchWithQueryString(service, WellKnownFolderName.Inbox, queryString);

Ejemplo: Buscar elementos mediante una cadena de consulta y EWS

En este ejemplo, una solicitud FindItem SOAP busca todos los elementos de la Bandeja de entrada con la frase "plan de proyecto" en el asunto.

<?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="Exchange2013" />
  </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="item:Size" />
          <t:FieldURI FieldURI="item:Importance" />
          <t:FieldURI FieldURI="message:IsRead" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:IndexedPageItemView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
      <m:SortOrder>
        <t:FieldOrder Order="Descending">
          <t:FieldURI FieldURI="item:DateTimeReceived" />
        </t:FieldOrder>
      </m:SortOrder>
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="inbox" />
      </m:ParentFolderIds>
      <m:QueryString>subject:"project plan"</m:QueryString>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

En el ejemplo siguiente se muestra la respuesta del servidor con los resultados de la búsqueda.

<?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="1" TotalItemsInView="1" IncludesLastItemInRange="true">
            <t:Items>
              <t:Message>
                <t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
                <t:Subject>project plan</t:Subject>
                <t:DateTimeReceived>2013-12-11T15:42:02Z</t:DateTimeReceived>
                <t:Size>7406</t:Size>
                <t:Importance>Normal</t:Importance>
                <t:IsRead>false</t:IsRead>
              </t:Message>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </m:FindItemResponse>
  </s:Body>
</s:Envelope>