Auflösen von mehrdeutigen Namen mithilfe der EWS Exchange 2013
Erfahren Sie, wie Sie die verwaltete EWS-API oder EWS verwenden, um mehrdeutige Namen aufzulösen, indem Sie mögliche Übereinstimmungen aus Active Directory Domain Services (AD DS) oder einem Kontaktordner im Postfach Ihres Benutzers abrufen.
Ein Benutzer in Ihrer Organisation erhält eine handgeschriebene Liste mit Namen und Adressen für Mitarbeiter, die an einer Schulung teilgenommen haben. Sie möchten eine E-Mail mit einigen zusätzlichen Informationen an Personen in der Liste senden, aber sie können nicht die E-Mail-Adresse aller Benutzer lesen. Wenn Sie dieses Problem für Ihre Benutzer in Ihrer Anwendung lösen möchten, kann EWS helfen. Sie können die ExchangeService.ResolveName EWS Managed API-Methode oder den EWS-Vorgang ResolveNames verwenden, um eine Liste möglicher Übereinstimmungen für eine Textauswahl zurückzugeben, z. B. teil eines Nachnamens. Die zurückgegebenen Elemente können öffentliche Benutzerpostfächer, Verteilergruppen und Kontakte sein.
Beachten Sie, dass Exchange E-Mail-Adressen mit Routingtypen mit Präfix wie smtp oder sip in einem mehrwertigen Array speichert. Die ResolveName-Methode und der ResolveNames-Vorgang führen eine partielle Übereinstimmung mit jedem Wert dieses Arrays durch, wenn Sie den Routingtyp am Anfang des nicht aufgelösten Namens hinzufügen, z. B. "sip:User1". Wenn Sie keinen Routingtyp angeben, wird für die Methode oder den Vorgang standardmäßig smtp verwendet, mit einer primären SMTP-Adresseigenschaft abgeglichen, und das mehrwertige Array wird nicht durchsucht. Wenn Sie z. B. nach User1 suchen und das sip-Präfix nicht einschließen, erhalten Sie als Ergebnis kein sip:User1@Contoso.com , selbst wenn es sich um ein gültiges Postfach handelt.
Sie können nur einen mehrdeutigen Namen in einer einzelnen Anforderung angeben. Wenn Sie eine Liste mit mehrdeutigen Namen auflösen müssen, müssen Sie die Liste durchlaufen und die Methode oder den Vorgang für jeden Eintrag aufrufen. Kandidaten aus dem Ordner "Kontakte" eines Benutzers verfügen über einen Element-ID-Wert ungleich NULL, der dann in einem Contact.Bind-Methodenaufruf oder einer GetItem-Vorgangsanforderung verwendet werden kann, um zusätzliche Informationen abzurufen. Wenn es sich bei dem Kandidaten um eine Verteilergruppe handelt, können Sie die EwS Managed API-Methode ExpandGroup(ItemId) oder den EWS-Vorgang ExpandDL verwenden, um die Liste der Mitglieder abzurufen. Wenn der Parameter returnContactDetails oder das EWS-Attribut ReturnFullContactData auf true festgelegt ist, enthalten Active Directory-Einträge, die über eine ResolveName-Methode oder einen ResolveNames-Vorgang zurückgegeben werden, zusätzliche Eigenschaften, die den Kontakt beschreiben. Der ReturnContactDetails-Parameter oder das ReturnFullContactData-Attribut wirkt sich nicht auf die Daten aus, die für Kontakte und Kontaktgruppen zurückgegeben werden.
Auflösen von mehrdeutigen Namen mithilfe der verwalteten EWS-API
Sie können die ResolveName-Methode verwenden, um Kandidaten zu finden, die dem mehrdeutigen Namen entsprechen, den Sie übergeben. Sie können Überladungen der ResolveName-Methode verwenden, um auf fünf verschiedene Arten nach Kandidaten zu suchen.
Tabelle 1. Überladene ResolveName-Methoden
| Methode | Funktionsweise |
|---|---|
| ResolveName(String) | Sucht Kontakte im Ordner Kontakte des Benutzers und in der globalen Adressliste (GAL) – in dieser Reihenfolge. Die Zeichenfolgenvariable ist der mehrdeutige Name, den Sie auflösen möchten. |
| ResolveName(String, ResolveNameSearchLocation, Boolean) | Sucht Kontakte im Standardordner Kontakte und/oder in der globalen Adressliste (GAL). Der Zeichenfolgenwert ist der mehrdeutige Name, der Suchspeicherort gibt den Ordner Kontakte und/oder die GAL an, und der boolesche Wert gibt an, ob die vollständigen Kontaktinformationen zurückgegeben werden sollen. |
| ResolveName(String, ResolveNameSearchLocation, Boolean, PropertySet) | Sucht Kontakte im Standardordner Kontakte und/oder globale Adressliste (GAL). Mit dieser Methode können Sie die zurückgegebenen Eigenschaften festlegen. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean) | Sucht Kontakte in angegebenen Kontaktordnern und/oder der globalen Adressliste (GAL). Sie können diese Methode verwenden, um eine Sammlung von Ordnern für die Suche zu übergeben. Dadurch können Sie in anderen Kontaktordnern als dem Standardordner Kontakte suchen. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean, PropertySet) | Sucht Kontakte in der globalen Adressliste (GAL) und/oder in bestimmten Kontaktordnern. Mit dieser Methode können Sie die zurückgegebenen Eigenschaften festlegen. |
Beginnen wir mit einem einfachen Beispiel. Das folgende Beispiel zeigt, wie die Textzeichenfolge "dan" aufgelöst und der Name und die E-Mail-Adresse jedes gefundenen Kandidaten ausgegeben werden. In diesem Beispiel wird davon ausgegangen, dass service ein gültiges ExchangeService-Objekt ist und der Benutzer bei einem Exchange-Server authentifiziert wurde.
// 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);
}
Die Antwort gibt maximal 100 Kandidaten zurück, obwohl es möglicherweise mehr als 100 potenzielle Kandidaten gibt. Um festzustellen, ob nur die ersten 100 Kandidaten einer größeren Anzahl von Kandidaten zurückgegeben wurden, überprüfen Sie den Wert von IncludesAllResolutions im NameResolutionCollection-Objekt . Wenn der Wert true ist, gibt es keine weiteren möglichen Kandidaten. Wenn der Wert false ist, hat die Methode nur die ersten 100 einer größeren Anzahl potenzieller Kandidaten zurückgegeben.
Wenn Sie in einer großen Organisation arbeiten, gibt ein Name wie "dan" wahrscheinlich die maximale Anzahl von 100 Kandidaten zurück. Um die Anzahl der zurückgegebenen Kandidaten zu reduzieren, begrenzen Sie den Suchort. Im nächsten Beispiel wird die ResolveNameSearchLocation-Enumeration verwendet, um anzugeben, wo gesucht werden soll, um den mehrdeutigen Namen aufzulösen.
// 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);
}
Wenn Sie Ihre Kontakte in einem anderen Ordner als dem bekannten Kontakteordner speichern, verwenden Sie eine der überladenen Methoden, um anzugeben, wo nach Kandidaten gesucht werden soll. Im folgenden Beispiel wird eine Ordnerliste für die ResolveName-Methode basierend auf der Ordner-ID erstellt. Die FolderId wurde aus Gründen der Lesbarkeit gekürzt.
// 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);
}
Wenn Sie Filter anwenden und keine Kandidaten zurückgegeben werden, enthält die NameResolutionCollection null Einträge. Sie können dies überprüfen, indem Sie sich die Count-Eigenschaft der Sammlung ansehen.
Auflösen von mehrdeutigen Namen mithilfe von EWS
Sie können den EWS-Vorgang ResolveNames verwenden, um mögliche Kandidaten für einen mehrdeutigen Namen zu identifizieren. Das UnresolvedEntry-Element enthält den mehrdeutigen Namen, den Sie auflösen möchten. Das folgende Beispiel zeigt, wie der Name Sadie aufgelöst wird. Dies ist auch die XML-Anforderung, die die verwaltete EWS-API verwendet, wenn Sie die ResolveName-Methode verwenden, mit der Ausnahme, dass sie einen anderen Namen für gültige Ausgabebeispiele verwendet.
<?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>
Die Antwort gibt maximal 100 Kandidaten zurück, obwohl es mehr als 100 potenzielle Kandidaten gibt. Überprüfen Sie den Wert des IncludesLastItemInRange-Attributs des ResolutionSet-Elements , um zu ermitteln, ob nur die ersten 100 Kandidaten einer größeren Anzahl von Kandidaten zurückgegeben wurden. Wenn der Wert true ist, gibt es keine weiteren möglichen Kandidaten. Wenn der Wert false ist, hat der Vorgang nur die ersten 100 einer größeren Anzahl potenzieller Kandidaten zurückgegeben.
Das folgende Beispiel zeigt die XML-Antwort, wenn ein Kandidat gefunden wird. Beachten Sie, dass resolutionSet bis zu 100 Kandidaten enthalten kann, die jeweils durch das Resolution-Element und seine untergeordneten Elemente dargestellt werden.
<?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>
Sie werden nicht immer Kandidaten für Ihren mehrdeutigen Namen finden. Das folgende Beispiel zeigt die XML-Antwort als Fehler, wenn keine Kandidaten gefunden werden.
<?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>