在 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.

作为代理,您可以使用相同的方法和操作来访问邮箱所有者的 "联系人" 文件夹,用于访问自己的 "联系人" 文件夹。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. 主要区别在于,必须使用显式访问来查找或创建联系人项目,然后在确定项目 ID 之后,可以使用隐式访问来获取、更新或删除项目。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
项。保存 FolderId参数提供对邮箱所有者的 "联系人" 文件夹的显式访问权限的位置Item.Save where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem其中邮箱元素指定邮箱所有者的EmailAddressCreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
将多个联系人创建为代理人Create multiple contacts as a delegate
FolderId参数提供对邮箱所有者的 "联系人" 文件夹的显式访问权限CreateItems ExchangeServiceExchangeService.CreateItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem其中邮箱元素指定邮箱所有者的EmailAddressCreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
将联系人解析为代理人Resolve a contact as a delegate
FolderId参数提供对邮箱所有者的 "联系人" 文件夹的显式访问权限ResolveName ExchangeServiceExchangeService.ResolveName where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
ResolveNames其中邮箱元素指定邮箱所有者的EmailAddressResolveNames where the Mailbox element specifies the EmailAddress of the mailbox owner
搜索或查找联系人为代理Search for or find a contact as a delegate
FolderId参数提供对邮箱所有者的 "联系人" 文件夹的显式访问权限FindItems ExchangeServiceExchangeService.FindItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
FindItem其中邮箱元素指定邮箱所有者的EmailAddressFindItem where the Mailbox element specifies the EmailAddress of the mailbox owner
获取作为代理的联系人Get a contact as a delegate
Contact。绑定Contact.Bind
GetItemGetItem
将联系人更新为代理Update a contact as a delegate
联系我们,后跟contact。更新Contact.Bind followed by Contact.Update
GetItem后接UpdateItemGetItem followed by UpdateItem
将联系人删除为代理人Delete a contact as a delegate
联系人。请先绑定,后跟联系人。删除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.

本示例假定服务是委派的有效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. 您可以通过两种方式将邮箱所有者的 "联系人" 文件夹包含在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"));

但是,您还可以先绑定到 "联系人" 文件夹,然后在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 使您可以使用委派用户的服务对象为邮箱所有者创建联系人项目。EWS enables you to use the service object for the delegate user to create contact items for the mailbox owner. 本示例演示如何使用CreateItem操作来创建联系人。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请求,其中包含ResponseCode元素值为NoError,表示已成功创建该联系人。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. 该响应还包含新创建的联系人的项目 ID。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方法之一,以便您可以指定邮箱所有者的 "联系人" 文件夹。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 使您可以使用委派用户的服务对象来解析邮箱所有者的 "联系人" 文件夹中的部分名称。EWS enables you to use the service object for the delegate user to resolve partial names in the mailbox owner's Contacts folder. 本示例演示如何使用ResolveNames操作查找邮箱所有者的 "联系人" 文件夹中包含 "johnson" 一词的会议。This example shows how to use the ResolveNames operation to find meetings in the mailbox owner's Contacts folder that contain the word "johnson".

这也是在使用ResolveName方法解析联系人时,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请求,其中包含ResponseCode元素值为NoErrorResolveNamesResponse消息,该消息指示操作已成功完成且仅找到一个结果,或者如果发现多个结果,则为ErrorNameResolutionMultipleResults 。如果找到多个结果,则基于该联系人的第三个代码示例中显示的是使用 EWS 托管 API 创建一个联系人作为代理人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. 该响应还包含每个结果的ItemIdThe 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隐式访问获取、更新或删除联系人项目作为代理, — 而无需指定邮箱所有者的 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 来获取、更新或删除联系人,方式与您在不使用代理访问时执行这些操作的方式相同。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. Bind方法调用中包含的项目 ID 在邮箱所有者的 "联系人" 文件夹中唯一标识邮箱存储中的项目。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
绑定Bind
使用 EWS 托管 API 获取项Get an item by using the EWS Managed API
更新联系人Update a contact
绑定后接更新Bind followed by Update
使用 EWS 托管 API 更新项Update an item by using the EWS Managed API
删除联系人Delete a contact
绑定后接删除Bind 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 获取、更新或删除会议或约会联系人,方式与您在不使用代理访问时执行这些操作的方式相同。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. GetItem请求中包含的项目 ID 在邮箱所有者的 "联系人" 文件夹中唯一标识邮箱存储中的项目。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后接UpdateItemGetItem followed by UpdateItem
使用 EWS 更新项Update an item by using EWS
删除联系人Delete a contact
GetItem后接DeleteItemGetItem followed by DeleteItem
使用 EWS 删除项Delete an item by using EWS

另请参阅See also