Выполнение поиска AQS с помощью EWS в Exchange

Статья
03/29/2023

Узнайте, как выполнять поиск с помощью строк запроса и AQS в управляемом API EWS или приложении EWS.

Строки запросов предоставляют альтернативу фильтрам поиска для выражения условий поиска. Самое большое преимущество использования строк запроса заключается в том, что для поиска не требуется указывать одно свойство. Можно просто указать значение, и поиск будет применяться ко всем часто используемым полям элементов. Вы также можете уточнить поиск с помощью расширенного синтаксиса запросов (AQS) вместо простого значения. Однако строки запросов имеют следующие ограничения, о которых следует знать, прежде чем добавлять их на панель элементов:

Ограниченная возможность поиска определенных свойств. При поиске с простым значением в строке запроса поиск выполняется для всех индексированных свойств. Вы можете уточнить поиск по определенным свойствам, но доступные для использования свойства в строке AQS ограничены. Если свойство, которое требуется выполнить поиск, не является одним из свойств, доступных для AQS, рассмотрите возможность использования фильтра поиска.
Поиск в пользовательских свойствах не выполняется. Поиск по строке запроса выполняется по индексу, и пользовательские свойства не включаются в этот индекс. Если вам нужно выполнить поиск по пользовательским свойствам, используйте фильтр поиска.
Ограниченный элемент управления для строкового поиска. Поиск по строкам запроса всегда игнорирует регистр и всегда выполняет поиск подстроки. Если вы хотите выполнять поиск с учетом регистра, префикса или точного соответствия, используйте фильтр поиска.
Недоступно для папок или папок поиска. Операции EWS для поиска папок не поддерживают использование строки запроса. Кроме того, папки поиска не поддерживают строки запросов. В обоих случаях единственным вариантом является фильтр поиска.

Создание строки запроса

Строки запросов в управляемом API EWS и EWS интерпретируются как подмножество синтаксиса AQS. Строки AQS состоят из значений или пар "ключевое слово-значение", разделенных двоеточием (:).

keyword:value

Если значение указано без ключевого слова, выполняется поиск по всем индексированных свойствам. Если ключевое слово связано со значением, ключевое слово указывает свойство для поиска соответствующего значения.

Таблица 1. Поддерживаемые ключевые слова AQS

Ключевое слово	Тип значения	Пример
subject	String	subject:project
body	Строка	body:sales figures
attachment	Строка	attachment:report
на	Строка	to:"Сэди Дэниелс"
from	Строка	from:hope
копия;	Строка	cc:"Ронни Стургис"
СК.	Строка	bcc:mack
participants	Строка	участники:сэди
category	String	category:project
importance	String	importance:high
kind	Тип элемента	kind:meetings
sent	Дата	отправлено:12/10/2013
received	Дата	получено:вчера
hasattachment	Boolean	Имеет вложение:true
isflagged	Boolean	isflagged:true
isread	Boolean	isread:false
size	Числовой	размер:>5000

Давайте посмотрим, как работают различные типы значений.

Использование типа строкового значения

Типы строковых значений по умолчанию выполняются как поиск по префиксной подстроке, в которых регистр не учитывается. Это означает, что поиск subject:project будет соответствовать любому из следующих субъектов:

Заметки о собрании проекта
У вас есть планы проекта?
Прогнозы продаж за декабрь

Вы можете изменить поиск, чтобы требовать целое слово, а не соответствующие префиксы, заключив строку в кавычки. При поиске subject:"project" значение "декабрьских прогнозов продаж" из списка совпадений будет удалено. Обратите внимание, что значение по-прежнему не учитывает регистр.

Если в строке запроса используется несколько слов, для сопоставления требуется, чтобы оба слова отображались в полях поиска. Например, поиск по плану subject:project будет соответствовать любому из следующих субъектов:

План проекта
У вас есть планы проекта?
Пожалуйста, отправьте мне план для нашего проекта
Вехи планирования проекта

Если заключить несколько слов в кавычки, они обрабатываются как одна фраза. Поиск по теме:"план проекта" будет соответствовать только теме "План проекта" из предыдущего списка.

Использование типа значения типа элемента

Вы можете использовать следующие значения типа элемента с ключевым словом kind , чтобы ограничить результаты поиска только определенным типом элемента, например электронной почтой или приглашением на собрание:

contacts
docs
email
faxes
im (соответствует мгновенным сообщениям)
journals
собрания (соответствует встречам и приглашениям на собрания)
notes
posts
rssfeeds
tasks
voicemail

Использование типа значения даты

Типы значений даты можно искать различными способами. Самый простой — поиск определенной даты. Поиск с использованием received:11/12/2013 вернет все элементы, полученные 11 декабря 2013 года. Однако вы также можете быть менее конкретными. Поиск с параметром received:12/11 вернет все элементы, полученные 11 декабря текущего года.

Другой вариант — использовать названия месяцев. Вы можете выполнить поиск по параметру received:11 декабря 2013 г. или 11 декабря, чтобы получить те же результаты, что и получено:12/11 соответственно. Вы также можете выполнить поиск по параметру received:Декабрь, чтобы получить все элементы, полученные в декабре текущего года.

Также можно использовать названия дней недели. Поиск с параметром received:Tuesday вернет все элементы, полученные во вторник текущей недели.

Типы значений даты также поддерживают набор ключевых слов для поиска относительно текущего времени. Поддерживаются следующие ключевые слова:

today
tomorrow
yesterday
this week
На прошлой неделе
в следующем месяце
за прошлый месяц
ближайший год

Типы значений даты также можно сравнивать с реляционными операторами, такими как больше или меньше, или указывать как диапазон с оператором диапазона ... Например, received:>30/11/2013, sent:>=yesterday и received:12/1/2013..today являются допустимыми строками запроса.

Использование логического типа значения

Логические типы значений могут быть "true" или "false". Значения не чувствительны к регистру, поэтому isread:false даст те же результаты, что и isread:FALSE.

Использование типа числового значения

Числовые типы значений можно искать как точные совпадения, но их также можно искать с помощью реляционных операторов, таких как больше или меньше. Например, size:10000 вернет только элементы размером ровно 10 000 байт, но размер:>=10000 вернет элементы, размер которых превышает 10 000 байт или равен 10 000 байт. Диапазон также можно указать с помощью оператора диапазона ( ..). Например, size:7000..8000 вернет элементы размером от 7000 до 8000.

Использование логических операторов

Строки запроса поддерживают следующие логические операторы.

Табл. 2. Поддерживаемые логические операторы

Описание	Примеры
И	проект AND от:"Сэди Дэниелс" subject:(project AND plan)
ИЛИ	subject:meeting OR from:"Hope Gross" from:("Сэди Дэниелс" ИЛИ "Надежда Гросс")
NOT	НЕ от:"Ронни Стургис" получено:NOT сегодня

Обратите внимание, что эти операторы можно использовать для объединения нескольких критериев или для объединения нескольких значений в одной паре ключевое слово/значение. Однако при соединении нескольких значений в одной паре "ключевое слово-значение" следует использовать круглые скобки для заключения нескольких значений. Чтобы понять причину, рассмотрите возможность поиска с: "Сэди Дэниелс" или "Надежда Гросс". Этот поиск фактически интерпретируется как следующие критерии:

Элемент из Сэди Дэниелс, OR
Элемент содержит фразу "Надежда Гросс" в любом из его индексированных свойств.

В отличие от: ("Сэди Дэниелс" ИЛИ "Надежда Гросс") интерпретируется как:

Элемент из Сэди Дэниелс, OR
Элемент от Хоуп Гросс

Оператор по умолчанию, если указано несколько условий, но логический оператор не включен, — AND. Например, имеет значение attachment:true subject:project эквивалентно has:attachment:true и subject:project.

Пример. Поиск элементов с помощью строки запроса и управляемого API EWS

В этом примере определен метод SearchWithQueryString . Он принимает объект ExchangeService , объект WellKnownFolderName и строковый объект, представляющий строку запроса в качестве параметров. В этом примере предполагается, что для объекта ExchangeService выполнена инициализация с допустимыми значениями в свойствах Credentials и 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);
    }
}

Этот метод можно использовать для поиска всех элементов с фразой "план проекта" в теме, как показано в этом примере.

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

Пример. Поиск элементов с помощью строки запроса и EWS

В этом примере запрос SOAP FindItem находит все элементы в папке "Входящие" с фразой "план проекта" в теме.

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

В следующем примере показан ответ сервера с результатами поиска.

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

Share via