Exchange 2013 の EWS を使用して、あいまいな名前を解決する

[アーティクル]
03/29/2023

EWS マネージ API または EWS を使用して、Active Directory ドメインサービス (AD DS) や、ユーザーのメールボックスの連絡先フォルダーから候補を取得し、あいまいな名前を解決する方法について説明します。

組織内のユーザーには、トレーニングセッションに参加した従業員の名前と住所を記した手書きのリストが渡されます。リストに記載された人物に電子メールで何らかの追加情報を発信したいと思っても、すべてのユーザーの電子メールアドレスを読み取ることはできません。アプリケーションのユーザーに代わり、この問題を解決したい場合は、EWS が役立つことがあります。 ExchangeService.ResolveName EWS マネージ API メソッド、または ResolveNames EWS 操作を使用して、姓の一部など、テキストの一部に一致する候補のリストを返すことができます。返されるアイテムは、パブリックのユーザーメールボックス、配布グループ、および連絡先である場合があります。

Exchange は、複数値配列内の smtp や sip などのルーティングの種類を先頭につけて、電子メールアドレスを保存しますので、ご注意ください。未解決の名前の先頭に、「sip:User1」などのルーティングの種類を付け加えた場合、ResolveName メソッドや ResolveNames 操作は、その配列の各値の部分一致を実施します。ルーティングの種類を指定しない場合、メソッドまたは操作の既定値は smtp となり、プライマリ smtp アドレスプロパティに一致させ、複数値配列は検索しません。たとえば、User1 を検索し、sip プレフィックスを含まない場合、有効なメールボックスであっても、sip はUser1@Contoso.com 受信されません。

要求 1 つに対して、あいまいな名前は 1 つしか指定できません。解決が必要なあいまいな名前の一覧がある場合、一覧をループ処理し、各エントリのメソッドまたは操作を呼び出す必要があります。ユーザーの連絡先フォルダーにある候補のアイテム ID 値は null 以外となり、その ID 値は Contact.Bind メソッドの呼び出し、または追加情報を取得するための GetItem 操作要求に使用できます。その候補が配布グループの場合、ExpandGroup(ItemId) EWS マネージ API メソッド、または ExpandDL EWS 操作を使用して、メンバーの一覧を取得できます。 returnContactDetails パラメーターまたは ReturnFullContactData EWS 属性が true に設定されている場合、ResolveName メソッドまたは ResolveNames 操作を使用して返される Active Directory エントリには、連絡先を記述する追加のプロパティが含まれます。 returnContactDetails パラメーターまたは ReturnFullContactData 属性は、連絡先と連絡先グループに対して返されるデータには影響しません。

EWS マネージ API を使用して、あいまいな名前を解決する

ResolveName メソッドを使用して、渡されるあいまいな名前に一致する候補を検索します。 ResolveName メソッドのオーバーロードを使用して、5 通りの方法で候補を検索できます。

表 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」というテキスト文字列を解決して、検索された各候補の名前と電子メールアドレスを出力する方法を示します。この例では、service が有効な ExchangeService オブジェクトであり、ユーザーが 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);
   }

100 を超える候補が存在する場合でも、この応答は最大で 100 候補しか返しません。より多くの候補から最初の 100 候補だけが返されたのかどうかを判定するには、NameResolutionCollection オブジェクトの IncludesAllResolutions の値を確認してください。値が 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);
   }

既知の連絡先フォルダー以外のフォルダーに連絡先を格納する場合は、オーバーロードされたメソッドのいずれかを使用して、候補の検索先を指定してください。次の例では、フォルダー ID に基づいて 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 を使用して、あいまいな名前を解決します

ResolveName EWS 操作を使用して、あいまいな名前の候補を特定します。 UnresolvedEntry 要素は、解決したいあいまいな名前を含んでいます。次の例は、Sadie という名前を解決する方法を示しています。これは、有効な出力例に異なる名前を使用する場合以外で、ResolveName メソッドを使用する場合に EWS マネージ API が使用する XML 要求でもあります。

<?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 候補だけが返されたどうかを判定するには、ResolutionSet 要素の IncludesLastItemInRange 属性の値を確認してください。値が true の場合は、これ以上の候補は存在しません。値が false の場合は、この操作はより多くの潜在的候補から最初の 100 候補だけを返しました。

次の例では、1 候補が検出された場合の 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>

次の方法で共有

Exchange 2013 の EWS を使用して、あいまいな名前を解決する

EWS マネージ API を使用して、あいまいな名前を解決する

EWS を使用して、あいまいな名前を解決します

関連項目

フィードバック

その他のリソース