Exchange で EWS を使用して、代理人として連絡先にアクセスする

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

Exchange の EWS マネージ API または EWS を使用して、代理人として連絡先にアクセスする方法を説明します。

EWS マネージ API または EWS を使用して、ユーザーにメールボックス所有者の連絡先フォルダーへのアクセス権を付与できます。代理人は、メールボックス所有者の代わりに連絡先を作成し、アクセス許可に応じて、メールボックス所有者の連絡先フォルダーから連絡先を取得、更新、および削除することができます。

代理人として、独自の連絡先フォルダーへのアクセスに使用するメールボックス所有者の連絡先フォルダーにアクセスする場合と同じ方法と操作を使用します。主な違いは、明示的なアクセスを使用して連絡先アイテムを検索または作成する必要があり、アイテム ID を特定した後、暗黙的なアクセスを使用してアイテムを取得、更新、または削除できることです。

表 1. 代理人として連絡先にアクセスするための EWS マネージ API メソッドと EWS 操作

目的	使用する EWS マネージ API メソッド…	使用する EWS 操作…
代理人として連絡先を作成する	Item.Save: FolderId パラメーターがメールボックス所有者の連絡先フォルダーへの明示的なアクセスを提供する場合	CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合
代理人として複数の連絡先を作成する	ExchangeService.CreateItems: FolderId パラメーターがメールボックス所有者の連絡先フォルダーに明示的なアクセスを提供する場合	CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合
代理人として連絡先を解決する	ExchangeService.ResolveName: FolderId パラメーターがメールボックス所有者の連絡先フォルダーへの明示的なアクセスを提供する場合	ResolveNames: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合
代理人として連絡先を検索する	ExchangeService.FindItems: FolderId パラメーターがメールボックス所有者の連絡先フォルダーに明示的なアクセスを提供する場合	FindItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合
代理人として連絡先を取得する	Contact.Bind	GetItem
代理人として連絡先を更新する	Contact.Bind の後に Contact.Update を使用する	GetItem の後に UpdateItem
代理人として連絡先を削除する	Contact.Bind の後に Contact.Update 使用する	GetItem の後に DeleteItem

注:

この記事のコード例では、 primary@contoso.com はメールボックスの所有者です。

事前に必要なタスク

ユーザーは、代理人としてメールボックス所有者の連絡先フォルダーにアクセスできるようにするために、アクセス許可を持つ代理人としてメールボックス所有者の連絡先フォルダーに追加される必要があります。

EWS マネージ API を使用して、代理人として連絡先を作成する

EWS マネージ API を使用すると、代理ユーザーのサービスオブジェクトを使用して、メールボックス所有者の連絡先を作成することができます。この例は、Save メソッドを使用して会議を作成し、出席者に会議出席依頼を送信する方法を示しています。

この例では、service が代理人の有効な ExchangeService オブジェクトであり、代理人にメールボックス所有者の連絡先フォルダーの適切なアクセス許可が付与されていることを前提にしています。

 public static void DelegateAccessCreateContact(ExchangeService service)
{
    // Create the contact.
    Contact contact = new Contact(service);
    // Specify the name and how the contact should be filed.
    contact.GivenName = "Brian";
    contact.MiddleName = "David";
    contact.Surname = "Johnson";
    contact.FileAsMapping = FileAsMapping.SurnameCommaGivenName;
    // Specify the company name.
    contact.CompanyName = "Contoso";
    // Specify the business, home, and car phone numbers.
    contact.PhoneNumbers[PhoneNumberKey.BusinessPhone] = "425-555-0110";
    contact.PhoneNumbers[PhoneNumberKey.HomePhone] = "425-555-0120";
    contact.PhoneNumbers[PhoneNumberKey.CarPhone] = "425-555-0130";
    // Specify two email addresses.
    contact.EmailAddresses[EmailAddressKey.EmailAddress1] = 
        new EmailAddress("brian_1@contoso.com");
    contact.EmailAddresses[EmailAddressKey.EmailAddress2] = 
        new EmailAddress("brian_2@contoso.com");
    // Save the contact in the mailbox owner's Contacts folder.
    // This method call results in a CreateItem call to EWS. 
    // The contact identifier contains the context for the mailbox owner's 
    // Contact folder. Any additional actions take on this contact will 
    // be performed in the mailbox owner's mailbox. 
    contact.Save(new FolderId(WellKnownFolderName.Contacts, 
        "primary@contoso.com"));
    // Verify that the contact was created.
    // This method call results in a GetItem call to EWS
    // to load the display name property on the contact. 
    contact.Load(new PropertySet (ContactSchema.DisplayName));
    Console.WriteLine("\nContact created: " + contact.DisplayName + "\n");
}

アイテムの保存時には、Save メソッド呼び出しでメールボックス所有者の連絡先フォルダーを識別する必要があることにご注意ください。メールボックス所有者の連絡先フォルダーを指定しない場合、会議出席依頼はメールボックス所有者の連絡先フォルダーではなく、代理人の連絡先フォルダーに保存されます。メールボックス所有者の連絡先フォルダーは、2 つの方法で Save メソッド呼び出しに含めることができます。メールボックス所有者の WellKnownFolderName と SMTP アドレスを使用して、FolderId オブジェクトの新しいインスタンスをインスタンス化することをお勧めします。

contact.Save(new FolderId(WellKnownFolderName.Contacts, "primary@contoso.com"));

ただし、最初に連絡先フォルダーへの Bind を使用してから、 Save メソッド呼び出しでフォルダーの ID を使用することもできます。ただし、これにより追加の EWS 呼び出しが作成されることにご注意ください。

    // Identify the mailbox owner's SMTP address 
    // and bind to their Contacts folder.
    Mailbox primary = new Mailbox("primary@contoso.com"); 
    Folder primaryContacts = Folder.Bind(service, new FolderId(WellKnownFolderName.Contacts, primary)); 
…
    // Save the contact to the mailbox owner's Contacts folder.
    meeting.Save(primaryContacts.Id);

EWS を使用して、代理人として連絡先を作成する

EWS を使用すると、代理ユーザーのサービスオブジェクトを使用して、メールボックス所有者の連絡先アイテムを作成することができます。この例では、CreateItem を使用して連絡先を作成する方法を示します。

これは、連絡先の作成に Save メソッドを使用する場合、EWS マネージ API が送信する XML 要求でもあります。

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:CreateItem MessageDisposition="SaveOnly">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="contacts">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:SavedItemFolderId>
      <m:Items>
        <t:Contact>
          <t:FileAsMapping>LastCommaFirst</t:FileAsMapping>
          <t:GivenName>Brian</t:GivenName>
          <t:MiddleName>David</t:MiddleName>
          <t:CompanyName>Contoso</t:CompanyName>
          <t:EmailAddresses>
            <t:Entry Key="EmailAddress1">brian_1@contoso.com</t:Entry>
            <t:Entry Key="EmailAddress2">brian_2@contoso.com</t:Entry>
          </t:EmailAddresses>
          <t:PhoneNumbers>
            <t:Entry Key="BusinessPhone">425-555-0110</t:Entry>
            <t:Entry Key="HomePhone">425-555-0120</t:Entry>
            <t:Entry Key="CarPhone">425-555-0130</t:Entry>
          </t:PhoneNumbers>
          <t:Surname>Johnson</t:Surname>
        </t:Contact>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

サーバーは、連絡先が正常に作成されたことを示す NoError の ResponseCode 要素値を含む CreateItemResponse メッセージで CreateItem 要求に応答します。応答には、新しく作成された連絡先のアイテム ID も含まれます。

EWS マネージ API を使用して、代理人として連絡先を解決する

場合によって、あいまいな名前または語句に基づいて連絡先を検索するには、メールボックス所有者の連絡先フォルダーを指定するようにするため、FolderId を含む ExchangeService.ResolveName メソッドのいずれかを使用する必要があります。

private static void DelegateAccessResolveContacts(ExchangeService service)
{
    // Create a list to store folders to search.
    List<FolderId> folders = new List<FolderId>();
   
    // Add the mailbox owner's folder to the list.
    folders.Add(new FolderId(WellKnownFolderName.Contacts, 
        "primary@contoso.com"));
    
    // Resolve the ambiguous name "Johnson".
    // This method call results in a ResolveNames call to EWS.
    NameResolutionCollection resolvedNames = service.ResolveName(
        "johnson", folders, ResolveNameSearchLocation.ContactsOnly, true);
    // Output the list of candidate email addresses and contact names.
    foreach (NameResolution nameRes in resolvedNames)
    {
        Console.WriteLine("Contact e-mail address: " + nameRes.Mailbox.Address);
        Console.WriteLine("Contact ID: " + nameRes.Mailbox.Id);
    }
}

ResolveNames メソッドの呼び出しで ID を持つ応答が返された後は、ID と暗黙的なアクセスを使用して連絡先を取得、更新、または削除できます。メールボックス所有者の SMTP アドレスを指定する必要はありません。

EWS を使用して、代理人として連絡先を解決する

EWS を使用すると、代理ユーザーのサービスオブジェクトを使用して、メールボックス所有者の連絡先内の部分的な名前を解決できます。この例では、ResolveNames 操作を使用して、"johnson" という単語が含まれるメールボックス所有者の連絡先フォルダー内で会議を検索する方法を示します。

これは、連絡先の解決に ResolvName メソッドを使用する場合、EWS マネージ API が送信する XML 要求でもあります。

 <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:ResolveNames ReturnFullContactData="true"
                    SearchScope="Contacts">
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="contacts">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:ParentFolderIds>
      <m:UnresolvedEntry>johnson</m:UnresolvedEntry>
    </m:ResolveNames>
  </soap:Body>
</soap:Envelope>

サーバーは、ResolveNames 要求に対してResolveNamesResponse メッセージで応答します。このメッセージには、操作が正常に完了され、結果が 1 つだけ検出されたことを示す NoError と、複数の結果が検出された場合は ErrorNameResolutionMultipleResults という ResponseCode 要素値が含まれます。これは、連絡先 (「EWS マネージ API を使用して、代理人として連絡先を作成する」) に基づく 3 番目のコード例で示されています。応答には各結果の ItemId も含まれます。

ItemId 要素の値は読みやすいよう短縮されています。

 <?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15"
                         MinorVersion="0"
                         MajorBuildNumber="893"
                         MinorBuildNumber="17"
                         Version="V2_10"
                         xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body>
    <m:ResolveNamesResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                            xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:ResolveNamesResponseMessage ResponseClass="Warning">
          <m:MessageText>Multiple results were found.</m:MessageText>
          <m:ResponseCode>ErrorNameResolutionMultipleResults</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
          <m:ResolutionSet TotalItemsInView="2"
                           IncludesLastItemInRange="true">
            <t:Resolution>
              <t:Mailbox>
                <t:Name>brian_1@contoso.com</t:Name>
                <t:EmailAddress>brian_1@contoso.com</t:EmailAddress>
                <t:RoutingType>SMTP</t:RoutingType>
                <t:MailboxType>Contact</t:MailboxType>
                <t:ItemId Id="iMihAAA="
                          ChangeKey="EQAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAABiPQo" />
              </t:Mailbox>
            </t:Resolution>
            <t:Resolution>
              <t:Mailbox>
                <t:Name>brian_2@contoso.com</t:Name>
                <t:EmailAddress>brian_2@contoso.com</t:EmailAddress>
                <t:RoutingType>SMTP</t:RoutingType>
                <t:MailboxType>Contact</t:MailboxType>
                <t:ItemId Id="iMihAAA="
                          ChangeKey="EQAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAABiPQo" />
              </t:Mailbox>
            </t:Resolution>
          </m:ResolutionSet>
        </m:ResolveNamesResponseMessage>
      </m:ResponseMessages>
    </m:ResolveNamesResponse>
  </s:Body>
</s:Envelope>

あいまいな名前と一致する連絡先の ItemId を取得し、ItemId と暗黙的なアクセスを使用して EWS を使用して代理人として連絡先アイテムを取得、更新、または削除できるようになりました。メールボックス所有者の SMTP アドレスを指定する必要はありません。

EWS マネージ API を使用して、代理人として連絡先アイテムを取得、更新、または削除する

EWS マネージ API を使用すると、代理人アクセスを使用していない場合に取得、更新、または削除のアクションを実行するのと同じ方法で、連絡先アイテムを取得、更新、または削除することができます。唯一の違いは、サービスオブジェクトが代理ユーザーを対象にしている点です。 Bind メソッド呼び出しに含まれるアイテム ID は、メールボックス所有者の連絡先フォルダー内のメールボックスストアにあるアイテムを一意に識別します。

表 2. 代理人として連絡先を操作する EWS マネージ API メソッド

タスク	EWS マネージ API メソッド	コード例
連絡先を取得する	Bind	EWS マネージ API を使用してアイテムを取得する
連絡先を更新する	Bind の後に Update	EWS マネージ API を使用してアイテムを更新する
連絡先を削除する	Bind の後に Delete	EWS マネージ API を使用してアイテムを削除する

EWS を使用して、代理人として連絡先アイテムを取得、更新、または削除する

EWS を使用すると、代理人アクセスを使用していない場合に取得、更新、または削除のアクションを実行するのと同じ方法で、連絡先アイテムを取得、更新、または削除することができます。唯一の違いは、サービスオブジェクトが代理ユーザーを対象にしている点です。 GetItem 要求に含まれるアイテム ID は、メールボックス所有者の連絡先フォルダー内のメールボックスストアにあるアイテムを一意に識別します。

表 3. 代理人として連絡先を操作するための EWS 操作

タスク	EWS 操作	サンプル
連絡先を取得する	GetItem	EWS を使用してアイテムを取得する
連絡先を更新する	GetItem の後に UpdateItem	EWS を使用してアイテムを更新する
連絡先を削除する	GetItem の後に DeleteItem	EWS を使用してアイテムを削除する