Résoudre les noms ambigus à l’aide d’EWS dans Exchange 2013

Découvrez comment utiliser l’API managée EWS ou EWS pour résoudre les noms ambigus en obtenant des correspondances possibles à partir de services de domaine Active Directory (AD DS) ou d’un dossier contacts dans la boîte aux lettres de votre utilisateur.

Un utilisateur de votre organisation reçoit une liste manuscrite de noms et d’adresses pour les employés qui ont participé à une session de formation. Ils souhaitent envoyer un e-mail avec des informations supplémentaires aux personnes de la liste, mais ils ne peuvent pas lire l’adresse e-mail de tout le monde. Si vous souhaitez résoudre ce problème pour vos utilisateurs dans votre application, EWS peut vous aider. Vous pouvez utiliser la méthode d’API managée EWS ExchangeService.ResolveName ou l’opération EWS ResolveNames pour renvoyer une liste de correspondances potentielles pour une sélection de texte, comme une partie d’un nom de famille. Les éléments retournés peuvent être des boîtes aux lettres d’utilisateurs publics, des groupes de distribution et des contacts.

Notez qu’Exchange enregistre les adresses e-mail avec des types de routage préfixés, tels que smtp ou sip, dans un tableau à valeurs multiples. La méthode ResolveName et l’opération ResolveNames effectuent une correspondance partielle par rapport à chaque valeur de ce tableau lorsque vous ajoutez le type de routage au début du nom non résolu, tel que « sip:User1 ». Si vous ne spécifiez pas de type de routage, la méthode ou l’opération est par défaut smtp, la met en correspondance avec une propriété d’adresse smtp principale et ne recherche pas dans le tableau à valeurs multiples. Par exemple, si vous recherchez User1 et que vous n’incluez pas le préfixe sip, vous ne recevrez pas sip:User1@Contoso.com par conséquent, même s’il s’agit d’une boîte aux lettres valide.

Vous ne pouvez spécifier qu’un seul nom ambigu dans une seule requête. Si vous avez une liste de noms ambigus à résoudre, vous devez parcourir la liste en boucle et appeler la méthode ou l’opération pour chaque entrée. Les candidats du dossier Contacts d’un utilisateur ont une valeur d’ID d’élément non null, qui peut ensuite être utilisée dans un appel de méthode Contact.Bind ou une demande d’opération GetItem pour récupérer des informations supplémentaires. Si le candidat est un groupe de distribution, vous pouvez utiliser la méthode d’API managée EWS ExpandGroup(ItemId) ou l’opération ExpandDL EWS pour obtenir la liste des membres. Si le paramètre returnContactDetails ou l’attribut ReturnFullContactData EWS est défini sur true, les entrées Active Directory renvoyées via une méthode ResolveName ou une opération ResolveNames incluent des propriétés supplémentaires qui décrivent le contact. Le paramètre returnContactDetails ou l’attribut ReturnFullContactData n’affecte pas les données retournées pour les contacts et les groupes de contacts.

Résoudre les noms ambigus à l’aide de l’API managée EWS

Vous pouvez utiliser la méthode ResolveName pour rechercher des candidats qui correspondent au nom ambigu que vous transmettez. Vous pouvez utiliser des surcharges de la méthode ResolveName pour rechercher des candidats de cinq façons différentes.

Tableau 1. Méthodes ResolveName surchargées

Méthode Fonctionnement
ResolveName(String) Recherche les contacts dans le dossier Contacts de l’utilisateur et la liste d’adresses globale (GAL) dans cet ordre. La variable de chaîne est le nom ambigu que vous essayez de résoudre.
ResolveName(String, ResolveNameSearchLocation, Boolean) Recherche les contacts dans le dossier Contacts par défaut et/ou la liste d’adresses globale (GAL). La valeur de chaîne est le nom ambigu, l’emplacement de recherche spécifie le dossier Contacts et/ou la liste d’adresses générales, et la valeur booléenne indique s’il faut retourner les informations de contact complètes.
ResolveName(String, ResolveNameSearchLocation, Boolean, PropertySet) Recherche les contacts dans le dossier Contacts par défaut et/ou la liste d’adresses globale (GAL). Cette méthode vous permet de définir les propriétés retournées.
ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean) Recherche les contacts dans les dossiers de contacts spécifiés et/ou dans la liste d’adresses globale (GAL). Vous pouvez utiliser cette méthode pour passer une collection de dossiers à rechercher. Cela vous permet de rechercher dans des dossiers de contacts autres que le dossier Contacts par défaut.
ResolveName(String, IEnumerable<FolderId>, ResolveNameSearchLocation, Boolean, PropertySet) Recherche des contacts dans la liste d’adresses globale (GAL) et/ou dans des dossiers de contacts spécifiques. Cette méthode vous permet de définir les propriétés retournées.

Commençons par un exemple simple. L’exemple suivant montre comment résoudre la chaîne de texte « dan » et générer le nom et l’adresse e-mail de chaque candidat trouvé. Cet exemple suppose que le service est un objetExchangeService valide et que l’utilisateur a bien été authentifié pour un serveur 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 réponse renvoie un maximum de 100 candidats, bien qu’il puisse y avoir plus de 100 candidats potentiels. Pour déterminer si seuls les 100 premiers candidats d’un plus grand nombre de candidats ont été retournés, vérifiez la valeur includesAllResolutions dans l’objet NameResolutionCollection . Si la valeur est true, il n’y a plus de candidats possibles; si la valeur est false, la méthode n’a renvoyé que les 100 premiers candidats d’un plus grand nombre de candidats potentiels.

Si vous travaillez dans une grande organisation, il est probable qu’un nom comme « dan » renvoie le nombre maximal de 100 candidats. Pour réduire le nombre de candidats renvoyés, limitez l’emplacement de recherche. L’exemple suivant utilise l’énumération ResolveNameSearchLocation pour spécifier où effectuer une recherche afin de résoudre le nom ambigu.

// 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 vous stockez vos contacts dans un dossier autre que le dossier Contacts bien connu, utilisez l’une des méthodes surchargées pour spécifier où rechercher des candidats. L’exemple suivant crée une liste de dossiers pour la méthode ResolveName en fonction de l’ID de dossier. Le FolderId a été raccourci pour plus de lisibilité.

// 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 vous appliquez des filtres et qu’aucun candidat n’est retourné, nameResolutionCollection ne contient aucune entrée. Vous pouvez le vérifier en examinant la propriété Count de la collection.

Résoudre les noms ambigus à l’aide d’EWS

Vous pouvez utiliser l’opération EWS ResolveNames pour identifier les candidats possibles pour un nom ambigu. L’élément UnresolvedEntry contient le nom ambigu que vous souhaitez résoudre. L’exemple suivant montre comment résoudre le nom Sadie. Il s’agit également de la requête XML que l’API managée EWS utilise lorsque vous utilisez la méthode ResolveName, sauf qu’elle utilise un nom différent pour les exemples de sortie valides.

<?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="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <ResolveNames xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
                  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                  ReturnFullContactData="true">
      <UnresolvedEntry>Sadie</UnresolvedEntry>
    </ResolveNames>
  </soap:Body>
</soap:Envelope>

La réponse retourne un maximum de 100 candidats, bien qu’il puisse y avoir plus de 100 candidats potentiels. Pour déterminer si seuls les 100 premiers candidats d’un plus grand nombre de candidats ont été retournés, vérifiez la valeur de l’attribut IncludesLastItemInRange de l’élément ResolutionSet . Si la valeur est true, il n’y a plus de candidats possibles; si la valeur est false, l’opération n’a renvoyé que les 100 premiers candidats d’un plus grand nombre de candidats potentiels.

L’exemple suivant montre la réponse XML lorsqu’un candidat est trouvé. N’oubliez pas que le ResolutionSet peut contenir jusqu’à 100 candidats, chacun représenté par l’élément Resolution et ses éléments enfants.

<?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="https://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="https://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>

Vous ne trouverez pas toujours des candidats pour votre nom ambigu. L’exemple suivant montre la réponse XML, sous forme d’erreur, quand aucun candidat n’est trouvé.

<?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="https://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="https://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>

Voir aussi