Устранение неоднозначности имен с помощью EWS в Exchange 2013
Узнайте, как использовать управляемый API EWS или EWS для разрешения неоднозначных имен, получая возможные совпадения из доменные службы Active Directory (AD DS) или папки контактов в почтовом ящике пользователя.
Пользователю в вашей организации предоставляется рукописный список имен и адресов для сотрудников, которые приняли участие в обучающей сессии. Они хотят отправить сообщение электронной почты с дополнительными сведениями людям из списка, но они не могут прочитать адрес электронной почты всех пользователей. Если вы хотите решить эту проблему для пользователей в приложении, EWS может помочь. Вы можете использовать метод Управляемого API ExchangeService.ResolveName EWS или операцию ResolveNames EWS, чтобы вернуть список потенциальных совпадений для выделения текста, например части фамилии. Возвращаемые элементы могут быть общедоступными почтовыми ящиками пользователей, группами рассылки и контактами.
Обратите внимание, что Exchange сохраняет адреса электронной почты с префиксами типов маршрутизации, таких как SMTP или SIP, в многозначном массиве. Метод ResolveName и операция ResolveNames выполняют частичное совпадение с каждым значением этого массива при добавлении типа маршрутизации в начало неразрешенного имени, например sip:User1. Если тип маршрутизации не указан, метод или операция по умолчанию будет использовать smtp, сопоставить его со свойством основного smtp-адреса, а не выполнять поиск в многозначном массиве. Например, если вы ищете user1 и не включаете префикс SIP, в результате вы не получите sip:User1@Contoso.com , даже если это допустимый почтовый ящик.
В одном запросе можно указать только одно неоднозначное имя. Если у вас есть список неоднозначных имен для разрешения, необходимо выполнить цикл по списку и вызвать метод или операцию для каждой записи. Кандидаты из папки Контактов пользователя будут иметь значение идентификатора элемента, отличное от NULL, которое затем можно использовать в вызове метода Contact.Bind или запросе операции GetItem для получения дополнительных сведений. Если кандидат является группой рассылки, для получения списка участников можно использовать метод Managed API EWS ExpandGroup(ItemId) или операцию ExpandDL EWS. Если для параметра returnContactDetails или атрибута EWS ReturnFullContactData задано значение true, записи Active Directory, возвращаемые с помощью метода ResolveName или операции ResolveNames , будут содержать дополнительные свойства, описывающие контакт. Параметр returnContactDetails или атрибут ReturnFullContactData не влияет на данные, возвращаемые для контактов и групп контактов.
Разрешение неоднозначных имен с помощью управляемого API EWS
Метод ResolveName можно использовать для поиска кандидатов, соответствующих неоднозначным именам, которые вы передаете. Перегрузки метода ResolveName можно использовать для поиска кандидатов пятью разными способами.
Таблица 1. Перегруженные методы ResolveName
| Метод | Принцип работы |
|---|---|
| ResolveName(String) | Находит контакты в папке "Контакты" пользователя и в глобальном списке адресов (GAL) — в этом порядке. Строковая переменная — это неоднозначное имя, который вы пытаетесь разрешить. |
| ResolveName(String, ResolveNameSearchLocation, Boolean) | Находит контакты в папке "Контакты" по умолчанию и (или) в глобальном списке адресов (GAL). Строковое значение — неоднозначное имя, расположение поиска — папку «Контакты» и (или) глобальный список адресов, а логическое значение — указывает, следует ли возвращать полные контактные данные. |
| ResolveName(String, ResolveNameSearchLocation, Boolean, PropertySet) | Находит контакты в папке "Контакты" по умолчанию и(или) в глобальном списке адресов (GAL). Этот метод позволяет задать возвращаемые свойства. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean) | Находит контакты в указанных папках контактов и (или) в глобальном списке адресов (GAL). Этот метод можно использовать для передачи коллекции папок для поиска. Это позволяет искать папки контактов, отличные от папки контактов по умолчанию. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean, PropertySet) | Находит контакты в глобальном списке адресов (GAL) и (или) в определенных папках контактов. Этот метод позволяет задать возвращаемые свойства. |
Начнем с простого примера. В следующем примере показано, как разрешить текстовую строку "dan" и вывести имя и адрес электронной почты каждого найденного кандидата. В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.
// Resolve the ambiguous name "dan".
NameResolutionCollection resolvedNames = service.ResolveName("dan");
// Output the list of candidates.
foreach (NameResolution nameRes in resolvedNames)
{
Console.WriteLine("Contact name: " + nameRes.Mailbox.Name);
Console.WriteLine("Contact e-mail address: " + nameRes.Mailbox.Address);
Console.WriteLine("Mailbox type: " + nameRes.Mailbox.MailboxType);
}
Ответ возвращает не более 100 кандидатов, хотя потенциальных кандидатов может быть более 100. Чтобы определить, были ли возвращены только первые 100 кандидатов из большего числа кандидатов, проверьте значение IncludesAllResolutions в объекте NameResolutionCollection . Если значение равно true, отсутствуют возможные кандидаты; Если значение равно false, метод возвращает только первые 100 из большего числа потенциальных кандидатов.
Если вы работаете в крупной организации, скорее всего, имя типа "dan" вернет максимальное число 100 кандидатов. Чтобы уменьшить количество возвращаемых кандидатов, ограничьте место поиска. В следующем примере перечисление ResolveNameSearchLocation используется для указания места поиска для разрешения неоднозначного имени.
// Resolve the ambiguous name "dan".
// Only use the Contacts folder.
NameResolutionCollection resolvedNames = service.ResolveName("dan", ResolveNameSearchLocation.ContactsOnly, false);
// Output the list of candidates.
foreach (NameResolution nameRes in resolvedNames)
{
Console.WriteLine("Contact name: " + nameRes.Mailbox.Name);
Console.WriteLine("Contact e-mail address: " + nameRes.Mailbox.Address);
Console.WriteLine("Mailbox type: " + nameRes.Mailbox.MailboxType);
}
Если контакты хранятся в папке, отличной от известной папки "Контакты", используйте один из перегруженных методов, чтобы указать, где искать кандидатов. В следующем примере создается список папок для метода ResolveName на основе идентификатора папки. Значение FolderId сокращено для удобства чтения.
// Create a list to store folders to search.
List<FolderId> folders = new List<FolderId>();
// Add a folder to the list based on the FolderId.
folders.Add(new FolderId("AABR8mboAAA="));
// Resolve the ambiguous name "dan".
// Only use the folders specified.
NameResolutionCollection resolvedNames = service.ResolveName("dan", folders, ResolveNameSearchLocation.ContactsOnly, false);
foreach (NameResolution nameRes in resolvedNames)
{
Console.WriteLine("Contact name: " + nameRes.Mailbox.Name);
Console.WriteLine("Contact e-mail address: " + nameRes.Mailbox.Address);
Console.WriteLine("Mailbox type: " + nameRes.Mailbox.MailboxType);
}
Если вы применяете фильтры и кандидаты не возвращаются, nameResolutionCollection будет содержать ноль записей. Это можно проверить, просмотрев свойство Count коллекции.
Разрешение неоднозначных имен с помощью EWS
Для определения возможных кандидатов для неоднозначного имени можно использовать операцию EWS ResolveNames . Элемент ResolveedEntry содержит неоднозначное имя, которое требуется разрешить. В следующем примере показано, как разрешить имя Сэди. Это также XML-запрос, который управляемый API EWS использует при использовании метода ResolveName, за исключением того, что он использует другое имя для допустимых примеров выходных данных.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<ResolveNames xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
ReturnFullContactData="true">
<UnresolvedEntry>Sadie</UnresolvedEntry>
</ResolveNames>
</soap:Body>
</soap:Envelope>
Ответ возвращает не более 100 кандидатов, хотя может быть более 100 потенциальных кандидатов. Чтобы определить, были ли возвращены только первые 100 кандидатов из большего числа кандидатов, проверьте значение атрибута IncludesLastItemInRange элемента ResolutionSet . Если значение равно true, отсутствуют возможные кандидаты; Если значение равно false, операция возвращает только первые 100 из большего числа потенциальных кандидатов.
В следующем примере показан XML-ответ при обнаружении одного кандидата. Помните, что ResolutionSet может содержать до 100 кандидатов, каждый из которых представлен элементом Resolution и его дочерними элементами.
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<ResolveNamesResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:ResolveNamesResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:ResolutionSet TotalItemsInView="1" IncludesLastItemInRange="true">
<t:Resolution>
<t:Mailbox>
<t:Name>Sadie Daniels</t:Name>
<t:EmailAddress>Sadie@Contoso.com</t:EmailAddress>
<t:RoutingType>SMTP</t:RoutingType>
<t:MailboxType>Mailbox</t:MailboxType>
</t:Mailbox>
<t:Contact>
<t:DisplayName>Sadie Daniels</t:DisplayName>
<t:EmailAddresses>
<t:Entry Key="EmailAddress1">SMTP:Sadie@Contoso.com</t:Entry>
</t:EmailAddresses>
<t:ContactSource>ActiveDirectory</t:ContactSource>
</t:Contact>
</t:Resolution>
</m:ResolutionSet>
</m:ResolveNamesResponseMessage>
</m:ResponseMessages>
</ResolveNamesResponse>
</soap:Body>
</soap:Envelope>
Вы не всегда будете придумывать кандидатов на ваше неоднозначное имя. В следующем примере xml-ответ показан как ошибка, если кандидаты не найдены.
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<ResolveNamesResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:ResolveNamesResponseMessage ResponseClass="Error">
<m:MessageText>No results were found.</m:MessageText>
<m:ResponseCode>ErrorNameResolutionNoResults</m:ResponseCode>
<m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
</m:ResolveNamesResponseMessage>
</m:ResponseMessages>
</ResolveNamesResponse>
</soap:Body>
</soap:Envelope>