Resolución de nombres ambiguos mediante EWS en Exchange 2013
Obtenga información sobre cómo usar la API administrada de EWS o EWS para resolver nombres ambiguos mediante la obtención de posibles coincidencias de Servicios de dominio de Active Directory (AD DS) o una carpeta de contactos en el buzón del usuario.
A un usuario de su organización se le da una lista escrita a mano de nombres y direcciones para los empleados que asistieron a una sesión de entrenamiento. Quieren enviar un correo electrónico con información adicional a los usuarios de la lista, pero no pueden leer la dirección de correo electrónico de todos. Si quiere resolver este problema para los usuarios de la aplicación, EWS puede ayudarle. Puede usar el método de API administrada de EWS ExchangeService.ResolveName o la operación EWS ResolveNames para devolver una lista de posibles coincidencias para una selección de texto, como parte de un apellido. Los elementos devueltos pueden ser buzones de usuario públicos, grupos de distribución y contactos.
Tenga en cuenta que Exchange guarda direcciones de correo electrónico con tipos de enrutamiento con prefijo, como smtp o sip, en una matriz de varios valores. El método ResolveName y la operación ResolveNames realizan una coincidencia parcial con cada valor de esa matriz al agregar el tipo de enrutamiento al principio del nombre sin resolver, como "sip:User1". Si no especifica un tipo de enrutamiento, el método o la operación coincidirán de forma predeterminada con smtp, coincidirán con una propiedad de dirección smtp principal y no buscarán en la matriz multivalor. Por ejemplo, si busca User1 y no incluye el prefijo sip, no recibirá sip:User1@Contoso.com como resultado, incluso si es un buzón válido.
Solo puede especificar un nombre ambiguo en una sola solicitud. Si tiene una lista de nombres ambiguos que resolver, deberá recorrer en bucle la lista y llamar al método o la operación para cada entrada. Los candidatos de la carpeta Contactos de un usuario tendrán un valor de identificador de elemento no NULO, que se puede usar en una llamada al método Contact.Bind o en una solicitud de operación GetItem para recuperar información adicional. Si el candidato es un grupo de distribución, puede usar el método De API administrada de EWS ExpandGroup(ItemId) o la operación EWS ExpandDL para obtener la lista de miembros. Si el parámetro returnContactDetails o el atributo EWS ReturnFullContactData se establecen en true, las entradas de Active Directory devueltas a través de un método ResolveName o una operación ResolveNames incluirán propiedades adicionales que describen el contacto. El parámetro returnContactDetails o el atributo ReturnFullContactData no afectan a los datos que se devuelven para los contactos y grupos de contactos.
Resolución de nombres ambiguos mediante la API administrada de EWS
Puede usar el método ResolveName para buscar candidatos que coincidan con el nombre ambiguo que se pasa. Puede usar sobrecargas del método ResolveName para buscar candidatos de cinco maneras diferentes.
Tabla 1. Métodos ResolveName sobrecargados
| Método | Funcionamiento |
|---|---|
| ResolveName(String) | Busca contactos en la carpeta Contactos del usuario y en la Lista global de direcciones (GAL), en ese orden. La variable de cadena es el nombre ambiguo que intenta resolver. |
| ResolveName(String, ResolveNameSearchLocation, Boolean) | Busca contactos en la carpeta Contactos predeterminada o en la Lista global de direcciones (GAL). El valor de cadena es el nombre ambiguo, la ubicación de búsqueda especifica la carpeta Contactos o la GAL, y el valor booleano indica si se debe devolver la información de contacto completa. |
| ResolveName(String, ResolveNameSearchLocation, Boolean, PropertySet) | Busca contactos en la carpeta Contactos predeterminada o en la Lista global de direcciones (GAL). Este método permite establecer las propiedades que se devuelven. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean) | Busca contactos en carpetas de contactos especificadas o en la lista global de direcciones (GAL). Puede usar este método para pasar una colección de carpetas para buscar. Esto le permite buscar en carpetas de contactos distintas de la carpeta contactos predeterminada. |
| ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean, PropertySet) | Busca contactos en la lista global de direcciones (GAL) o en carpetas de contactos específicas. Este método permite establecer las propiedades que se devuelven. |
Comencemos con un ejemplo sencillo. En el ejemplo siguiente se muestra cómo resolver la cadena de texto "dan" y generar el nombre y la dirección de correo electrónico de cada candidato encontrado. En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange.
// 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);
}
La respuesta devuelve un máximo de 100 candidatos, aunque podría haber más de 100 candidatos potenciales. Para determinar si solo se devolvieron los primeros 100 candidatos de un mayor número de candidatos, compruebe el valor de IncludesAllResolutions en el objeto NameResolutionCollection . Si el valor es true, no hay más candidatos posibles; Si el valor es false, el método solo devolvió los primeros 100 de un número mayor de candidatos potenciales.
Si trabaja en una organización grande, es probable que un nombre como "dan" devuelva el número máximo de 100 candidatos. Para reducir el número de candidatos devueltos, limite la búsqueda. En el ejemplo siguiente se usa la enumeración ResolveNameSearchLocation para especificar dónde buscar para resolver el nombre ambiguo.
// 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);
}
Si almacena los contactos en una carpeta distinta de la conocida carpeta Contactos, use uno de los métodos sobrecargados para especificar dónde buscar candidatos. En el ejemplo siguiente se crea una lista de carpetas para el método ResolveName en función del identificador de carpeta. FolderId se ha acortado para mejorar la legibilidad.
// 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);
}
Si aplica filtros y no se devuelve ningún candidato, NameResolutionCollection contendrá cero entradas. Para comprobarlo, examine la propiedad Count de la colección.
Resolución de nombres ambiguos mediante EWS
Puede usar la operación EWS ResolveNames para identificar posibles candidatos para un nombre ambiguo. El elemento UnresolvedEntry contiene el nombre ambiguo que desea resolver. En el ejemplo siguiente se muestra cómo resolver el nombre Sadie. Esta es también la solicitud XML que usa la API administrada de EWS cuando se usa el método ResolveName, salvo que usa un nombre diferente para los ejemplos de salida válidos.
<?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>
La respuesta devuelve un máximo de 100 candidatos, aunque podría haber más de 100 candidatos potenciales Para determinar si solo se devolvieron los primeros 100 candidatos de un número mayor de candidatos, compruebe el valor del atributo IncludesLastItemInRange del elemento ResolutionSet . Si el valor es true, no hay más candidatos posibles; Si el valor es false, la operación solo devolvió los primeros 100 de un número mayor de candidatos potenciales.
En el ejemplo siguiente se muestra la respuesta XML cuando se encuentra un candidato. Recuerde que ResolutionSet puede contener hasta 100 candidatos, cada uno representado por el elemento Resolution y sus elementos secundarios.
<?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>
No siempre vas a presentar candidatos para tu nombre ambiguo. En el ejemplo siguiente se muestra la respuesta XML, como un error, cuando no se encuentra ningún candidato.
<?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>