Доступ к контактам в качестве делегата с помощью EWS в Exchange

Статья
03/29/2023

Узнайте, как получить доступ к контактам в качестве делегата с помощью управляемого API EWS или EWS в Exchange.

Управляемый API EWS или EWS можно использовать для предоставления пользователю доступа к папке "Контакты" владельца почтового ящика. Затем делегат может создавать контакты от имени владельца почтового ящика, а также извлекать, обновлять и удалять контакты из папки "Контакты" владельца почтового ящика в зависимости от его разрешений.

Делегат использует те же методы и операции для доступа к папке "Контакты" владельца почтового ящика, которая используется для доступа к собственной папке "Контакты". Основное отличие заключается в том, что для поиска или создания элемента контакта необходимо использовать явный доступ , а затем после идентификации идентификатора элемента можно использовать неявный доступ для получения, обновления или удаления элемента.

Таблица 1. Методы управляемого API EWS и операции EWS для доступа к контакту в качестве делегата

Задача	Используйте этот метод управляемого API EWS...	Используйте эту операцию 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.Delete	GetItem, затем DeleteItem

Примечание.

В примерах кода в этой статье primary@contoso.com является владельцем почтового ящика.

Необходимые предварительные задачи

Прежде чем пользователь сможет получить доступ к папке "Контакты" владельца почтового ящика в качестве делегата, пользователь должен быть добавлен в качестве делегата с разрешениями в папку "Контакты" владельца почтового ящика.

Создание контакта в качестве делегата с помощью управляемого API EWS

Управляемый API EWS позволяет использовать объект службы для пользователя-делегата для создания контактов для владельца почтового ящика. В этом примере показано, как использовать метод Save, чтобы создать собрание и отправить участникам приглашение на собрание.

В этом примере предполагается, что служба является допустимым объектом 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 должен определить папку "Контакты" владельца почтового ящика. Если папка "Контакты" владельца почтового ящика не указана, приглашение на собрание сохраняется в папке "Контакты" делегата, а не в папке "Контакты" владельца почтового ящика. Вы можете включить папку "Контакты" владельца почтового ящика в вызов метода Save двумя способами. Рекомендуется создать новый экземпляр объекта FolderId, используя WellKnownFolderName и адрес SMTP-сервера владельца почтового ящика.

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

Однако можно также сначала выполнить привязку к папке Контакты, а затем использовать идентификатор папки в вызове метода Save . Тем не менее, помните, что при этом создается дополнительный вызов 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 .

Это также XML-запрос, который управляемый API EWS отправляет при использовании метода Save для создания контакта.

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

Сервер отвечает на запрос CreateItem сообщением CreateItemResponse , которое содержит значение элемента ResponseCodeNoError, указывающее, что контакт успешно создан. Ответ также содержит идентификатор элемента только что созданного контакта.

Разрешение контакта в качестве делегата с помощью управляемого API EWS

Чтобы найти контакт на основе возможно неоднозначного имени или термина, необходимо использовать один из методов ExchangeService.ResolveName , включающий параметр FolderId , чтобы можно было указать папку "Контакты" владельца почтового ящика.

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 возвращает ответ с идентификатором, вы можете получить, обновить или удалить контакт с помощью идентификатора и неявного доступа. При этом не нужно указывать SMTP-адрес владельца почтового ящика.

Разрешение контакта в качестве делегата с помощью EWS

EWS позволяет использовать объект службы для делегированного пользователя для разрешения частичных имен в папке "Контакты" владельца почтового ящика. В этом примере показано, как использовать операцию ResolveNames для поиска собраний в папке "Контакты" владельца почтового ящика со словом "johnson".

Это также XML-запрос, который управляемый API EWS отправляет при использовании метода ResolveName для разрешения контакта.

 <?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 , которое содержит значение элемента ResponseCodeNoError, указывающее, что операция успешно завершена и найден только один результат, или ErrorNameResolutionMultipleResults , если найдено несколько результатов. Это то, что показано в третьем примере кода на основе контакта Создание контакта в качестве делегата с помощью управляемого API EWS. Ответ также содержит 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 для контактов, которые соответствуют неоднозначным имени, вы можете получать, обновлять или удалять элементы контакта в качестве делегата с помощью EWS с помощью ItemId и неявного доступа, и вам не нужно указывать SMTP-адрес владельца почтового ящика.

Получение, обновление и удаление элементов контактов в качестве делегата с помощью управляемого API EWS

Управляемый API EWS можно использовать для получения, обновления или удаления контакта так же, как и при использовании делегированного доступа. Единственное отличие состоит в том, что объект службы предназначен для пользователя-делегата. Идентификатор элемента, включенный в вызов метода Bind , однозначно идентифицирует элемент в хранилище почтовых ящиков в папке "Контакты" владельца почтового ящика.

Табл. 2. Методы управляемого API EWS, работающие с контактом в качестве делегата

Задача	Метод управляемого API EWS	Пример кода
Получение контакта.	Bind	Получение элемента с помощью управляемого API EWS
Обновление контакта	Bind, затем Update	Изменение элемента с помощью управляемого API EWS
Удалить контакт	Bind, затем Delete	Удаление элемента с помощью управляемого API EWS

Получение, обновление или удаление элементов контактов в качестве делегата с помощью EWS

Вы можете использовать EWS для получения, обновления или удаления контакта собрания или встречи так же, как вы выполняете эти действия, когда не используете делегированный доступ. Единственное отличие состоит в том, что объект службы предназначен для пользователя-делегата. Идентификатор элемента, включенный в запрос GetItem , однозначно идентифицирует элемент в хранилище почтовых ящиков в папке "Контакты" владельца почтового ящика.

Табл. 3. Операции EWS для работы с контактом в качестве делегата

Задача	Операция служб EWS	Пример
Получение контакта.	GetItem	Получение элемента с помощью веб-служб Exchange
Обновление контакта	GetItem, затем UpdateItem	Изменение элемента с помощью веб-служб Exchange
Удалить контакт	GetItem, затем DeleteItem	Удаление элемента с помощью веб-служб Exchange