Exchange で EWS を使用して、代理人として連絡先にアクセスするAccess contacts as a delegate by using EWS in Exchange

Exchange の EWS マネージ API または EWS を使用して、代理人として連絡先にアクセスする方法を説明します。Learn how to access contacts as a delegate by using the EWS Managed API or EWS in Exchange.

EWS マネージ API または EWS を使用して、ユーザーにメールボックス所有者の連絡先フォルダーへのアクセス権を付与できます。代理人は、メールボックス所有者の代わりに連絡先を作成し、アクセス許可に応じて、メールボックス所有者の連絡先フォルダーから連絡先を取得、更新、および削除することができます。You can use the EWS Managed API or EWS to give a user access to a mailbox owner's Contacts folder. The delegate can then create contacts on behalf of the mailbox owner, and retrieve, update, and delete contacts from the mailbox owner's Contacts folder, depending on their permissions.

代理人として、同じメソッドと操作を使用して、自分の連絡先フォルダーへのアクセスに使用する、メールボックス所有者の連絡先フォルダーにアクセスします。大きな違いは、明示的なアクセスを使用して連絡先アイテムを検索または作成する必要がある点です。アイテム ID を識別すると、暗黙的なアクセスを使用してアイテムを取得、更新、または削除できます。As a delegate, you use the same methods and operations to access a mailbox owner's Contacts folder that you use to access your own Contacts folder. The main difference is that you have to use explicit access to find or create a contact item, and then after you identify the item ID, you can use implicit access to get, update, or delete the item.

表 1. 代理人として連絡先にアクセスするための EWS マネージ API メソッドと EWS 操作Table 1. EWS Managed API methods and EWS operations for accessing a contact as a delegate

目的If you want to… 使用する EWS マネージ API メソッド…Use this EWS Managed API method… 使用する EWS 操作…Use this EWS operation…
代理人として連絡先を作成するCreate a contact as a delegate
Item.Save: FolderId パラメーターがメールボックス所有者の連絡先フォルダーへの明示的なアクセス を提供する場合Item.Save where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合CreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
代理人として複数の連絡先を作成するCreate multiple contacts as a delegate
ExchangeService.CreateItems: FolderId パラメーターがメールボックス所有者の連絡先フォルダーに明示的なアクセスを提供する場合ExchangeService.CreateItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合CreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
代理人として連絡先を解決するResolve a contact as a delegate
ExchangeService.ResolveName: FolderId パラメーターがメールボックス所有者の連絡先フォルダーへの明示的なアクセスを提供する場合ExchangeService.ResolveName where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
ResolveNames: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合ResolveNames where the Mailbox element specifies the EmailAddress of the mailbox owner
代理人として連絡先を検索するSearch for or find a contact as a delegate
ExchangeService.FindItems: FolderId パラメーターがメールボックス所有者の連絡先フォルダーに明示的なアクセスを提供する場合ExchangeService.FindItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
FindItem: Mailbox 要素がメールボックス所有者の EmailAddress を指定する場合FindItem where the Mailbox element specifies the EmailAddress of the mailbox owner
代理人として連絡先を取得するGet a contact as a delegate
Contact.BindContact.Bind
GetItemGetItem
代理人として連絡先を更新するUpdate a contact as a delegate
Contact.Bind の後に Contact.Update を使用するContact.Bind followed by Contact.Update
GetItem の後に UpdateItemGetItem followed by UpdateItem
代理人として連絡先を削除するDelete a contact as a delegate
Contact.Bind の後に Contact.Update 使用するContact.Bind followed by Contact.Delete
GetItem の後に DeleteItemGetItem followed by DeleteItem

注意

この記事のコード例では、primary@contoso.com がメールボックス所有者です。In the code examples in this article, primary@contoso.com is the mailbox owner.

事前に必要なタスクPrerequisite tasks

ユーザーは、代理人としてメールボックス所有者の連絡先フォルダーにアクセスできるようにするために、アクセス許可を持つ代理人としてメールボックス所有者の連絡先フォルダーに追加される必要があります。Before a user can access the mailbox owner's Contacts folder as a delegate, the user must be added as a delegate with permissions to the mailbox owner's Contacts folder.

EWS マネージ API を使用して、代理人として連絡先を作成するCreate a contact as a delegate by using the EWS Managed API

EWS マネージ API を使用すると、代理ユーザーのサービス オブジェクトを使用して、メールボックス所有者の連絡先を作成することができます。The EWS Managed API enables you to use the service object for the delegate user to create contacts for the mailbox owner. この例は、Save メソッドを使用して会議を作成し、出席者に会議出席依頼を送信する方法を示しています。This example shows how to use the Save method to create a meeting and send meeting requests to the attendees.

この例では、service が代理人の有効な ExchangeService オブジェクトであり、代理人にメールボックス所有者の連絡先フォルダーの適切なアクセス許可が付与されていることを前提にしています。This example assumes that service is a valid ExchangeService object for the delegate and that the delegate has been granted the appropriate permissions for the mailbox owner's Contacts folder.

 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 メソッド呼び出しでメールボックス所有者の連絡先フォルダーを識別する必要があることにご注意ください。Note that when you save the item, the Save method call must identify the mailbox owner's Contacts folder. メールボックス所有者の連絡先フォルダーを指定しない場合、会議出席依頼はメールボックス所有者の連絡先フォルダーではなく、代理人の連絡先フォルダーに保存されます。If the mailbox owner's Contacts folder is not specified, the meeting request gets saved to the delegate's Contacts folder and not the mailbox owner's Contacts folder. メールボックス所有者の連絡先フォルダーは、2 つの方法で Save メソッド呼び出しに含めることができます。You can include the mailbox owner's Contacts folder in the Save method call in two way. メールボックス所有者の WellKnownFolderName と SMTP アドレスを使用して、FolderId オブジェクトの新しいインスタンスをインスタンス化することをお勧めします。We recommend that you instantiate a new instance of the FolderId object by using the WellKnownFolderName and the SMTP address of the mailbox owner.

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

ただし、最初に連絡先フォルダーへの Bind を使用してから、 Save メソッド呼び出しでフォルダーの ID を使用することもできます。However, you can also Bind to the Contacts folder first, and then use the ID of the folder in the Save method call. ただし、これにより追加の EWS 呼び出しが作成されることにご注意ください。Be aware, however, that this creates an extra EWS call.

    // 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 を使用して、代理人として連絡先を作成するCreate a contact as a delegate by using EWS

EWS を使用すると、代理ユーザーのサービス オブジェクトを使用して、メールボックス所有者の連絡先アイテムを作成することができます。この例では、CreateItem を使用して連絡先を作成する方法を示します。EWS enables you to use the service object for the delegate user to create contact items for the mailbox owner. This example shows how to use the CreateItem operation to create a contact.

これは、連絡先の作成Save メソッドを使用する場合、EWS マネージ API が送信する XML 要求でもあります。This is also the XML request that the EWS Managed API sends when you use the Save method to create a contact.

<?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>

サーバーは、CreateItemResponse メッセージを含む CreateItem 要求に応答します。このメッセージには、連絡先が正常に作成されたことを示す、NoErrorResponseCode 要素の値が含まれます。また、応答には新しく作成された連絡先のアイテム ID も含まれます。The server responds to the CreateItem request with a CreateItemResponse message that includes a ResponseCode element value of NoError, which indicates that the contact was created successfully. The response also contains the item ID of the newly created contact.

EWS マネージ API を使用して、代理人として連絡先を解決するResolve a contact as a delegate by using the EWS Managed API

場合によって、あいまいな名前または語句に基づいて連絡先を検索するには、メールボックス所有者の連絡先フォルダーを指定するようにするため、FolderId を含む ExchangeService.ResolveName メソッドのいずれかを使用する必要があります。To find a contact based on a possibly ambiguous name or term, you must use one of the ExchangeService.ResolveName methods that includes a FolderId parameter, so that you can specify the mailbox owner's Contacts folder.

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 アドレスを指定する必要はありません。After the ResolveNames method call returns a response with an ID, you can get, update or delete the contact using the ID and implicit access—and you do not need to specify the mailbox owner's SMTP address.

EWS を使用して、代理人として連絡先を解決するResolve a contact as a delegate by using EWS

EWS を使用すると、代理ユーザーのサービス オブジェクトを使用して、メールボックス所有者の連絡先内の部分的な名前を解決できます。この例では、ResolveNames 操作を使用して、"johnson" という単語が含まれるメールボックス所有者の連絡先フォルダー内で会議を検索する方法を示します。 EWS enables you to use the service object for the delegate user to resolve partial names in the mailbox owner's Contacts folder. This example shows how to use the ResolveNames operation to find meetings in the mailbox owner's Contacts folder that contain the word "johnson".

これは、連絡先の解決ResolvName メソッドを使用する場合、EWS マネージ API が送信する XML 要求でもあります。This is also the XML request that the EWS Managed API sends when you use the ResolveName method to resolve a contact.

 <?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 番目のコード例で示されています。The server responds to the ResolveNames request with a ResolveNamesResponse message that includes a ResponseCode element value of NoError, which indicates that the operation completed successfully and found only one result, or ErrorNameResolutionMultipleResults if multiple results were found - which is what's shown in third code example based on the contact Create a contact as a delegate by using the EWS Managed API. 応答には各結果の ItemId も含まれます。The response also contains the ItemId of each result.

ItemId 要素の値は読みやすいよう短縮されています。The value of the ItemId element has been shortened for readability.

 <?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 アドレスを指定する必要はありません。Now that you have the ItemId for the contacts that match the ambiguous name, you can Get, update, or delete contact items as a delegate by using EWS by using the ItemId and implicit access—and you do not need to specify the mailbox owner's SMTP address.

EWS マネージ API を使用して、代理人として連絡先アイテムを取得、更新、または削除するGet, update, or delete contact items as a delegate by using the EWS Managed API

EWS マネージ API を使用すると、代理人アクセスを使用していない場合に取得、更新、または削除のアクションを実行するのと同じ方法で、連絡先アイテムを取得、更新、または削除することができます。唯一の違いは、サービス オブジェクトが代理ユーザーを対象にしている点です。Bind メソッド呼び出しに含まれるアイテム ID は、メールボックス所有者の連絡先フォルダー内のメールボックス ストアにあるアイテムを一意に識別します。You can use the EWS Managed API to get, update, or delete a contact in the same way that you perform these actions when you're not using delegate access. The only difference is that the service object is for the delegate user. The item ID included in the Bind method call uniquely identifies the item in the mailbox store, in the mailbox owner's Contacts folder.

表 2. 代理人として連絡先を操作する EWS マネージ API メソッドTable 2. EWS Managed API methods working with a contact as a delegate

タスクTask EWS マネージ API メソッドEWS Managed API method コード例Code example
連絡先を取得するGet a contact
BindBind
EWS マネージ API を使用してアイテムを取得するGet an item by using the EWS Managed API
連絡先を更新するUpdate a contact
Bind の後に UpdateBind followed by Update
EWS マネージ API を使用してアイテムを更新するUpdate an item by using the EWS Managed API
連絡先を削除するDelete a contact
Bind の後に DeleteBind followed by Delete
EWS マネージ API を使用してアイテムを削除するDelete an item by using the EWS Managed API

EWS を使用して、代理人として連絡先アイテムを取得、更新、または削除するGet, update, or delete contact items as a delegate by using EWS

EWS を使用すると、代理人アクセスを使用していない場合に取得、更新、または削除のアクションを実行するのと同じ方法で、連絡先アイテムを取得、更新、または削除することができます。唯一の違いは、サービス オブジェクトが代理ユーザーを対象にしている点です。GetItem 要求に含まれるアイテム ID は、メールボックス所有者の連絡先フォルダー内のメールボックス ストアにあるアイテムを一意に識別します。You can use EWS to get, update, or delete a meeting or appointment contact in the same way that you perform these actions when you're not using delegate access. The only difference is that the service object is for the delegate user. The item ID included in the GetItem request uniquely identifies the item in the mailbox store, in the mailbox owner's Contacts folder.

表 3. 代理人として連絡先を操作するための EWS 操作Table 3. EWS operations for working with a contact as a delegate

タスクTask EWS 操作EWS operation サンプルSample
連絡先を取得するGet a contact
GetItemGetItem
EWS を使用してアイテムを取得するGet an item by using EWS
連絡先を更新するUpdate a contact
GetItem の後に UpdateItem を使用するGetItem followed by UpdateItem
EWS を使用してアイテムを更新するUpdate an item by using EWS
連絡先を削除するDelete a contact
GetItem の後に DeleteItem を使用するGetItem followed by DeleteItem
EWS を使用してアイテムを削除するDelete an item by using EWS

関連項目See also