Поделиться через

Пакетная обработка контактов с помощью EWS в Exchange

  • Статья

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

Управляемый API EWS или EWS можно использовать для работы с пакетами контактов, чтобы уменьшить количество вызовов, которые клиент выполняет на сервер Exchange Server. При использовании Управляемого API EWS для создания, получения, обновления и удаления контактов в пакетах используются методы объектов ExchangeService , а при работе с отдельными контактами — методы объекта Contact . Если вы используете EWS, вы используете одни и те же операции для работы как с одним контактом, так и с пакетами контактов.

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

Задача Используйте этот метод управляемого API EWS Используйте эту операцию EWS
Создание контактов в пакетах
 ExchangeService.CreateItems
CreateItem
Получение контактов в пакетах
 ExchangeService.BindToItems или ExchangeService.LoadPropertiesForItems
GetItem
Обновление контактов в пакетах
 ExchangeService.UpdateItems
UpdateItem
Удаление контактов в пакетах
 ExchangeService.DeleteItems
DeleteItem

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

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

Контакты можно создавать пакетами с помощью метода CreateItems управляемого API EWS, как показано в следующем примере. В этом примере три объекта Contact создаются локально, каждый контакт добавляется в коллекцию, а затем вызывается метод CreateItems для коллекции контактов.

public static Collection<ItemId> CreateContactsInBatch(ExchangeService service)
{
    // These are unsaved local instances of a Contact object.
    // Despite the required parameter of an ExchangeService object (service), no call
    // to an Exchange server is made when the objects are instantiated.
    // A call to the Exchange server is made when the service.CreateItems() method is called.
    Contact contact1 = new Contact(service);
    Contact contact2 = new Contact(service);
    Contact contact3 = new Contact(service);
    // Set the properties on the first contact.
    contact1.DisplayName = "Sadie Daniels";
    contact1.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("sadie@contoso.com");
    
    // Set the properties on the second contact.
    contact2.DisplayName = "Alfred Welker";
    contact2.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("alfred@contoso.com");
    // Set the properties on the third contact.
    contact3.DisplayName = "Hope Gross";
    contact3.EmailAddresses[EmailAddressKey.EmailAddress1] = new EmailAddress("hope@contoso.com");
    // Add the Contact objects to a collection.
    Collection<Contact> contactItems = new Collection<Contact>() { contact1, contact2, contact3 };
    // Create the batch of contacts on the server.
    // This method call results in an CreateItem call to EWS.
    ServiceResponseCollection<ServiceResponse> response = service.CreateItems(contactItems, WellKnownFolderName.Contacts, null, null);
    // Instantiate a collection of item IDs to populate from the values that are returned by the Exchange server.
    Collection<ItemId> itemIds = new Collection<ItemId>();
    // Collect the item IDs from the created contacts.
    foreach (Contact contact in contactItems)
    {
        try
        {
            itemIds.Add(contact.Id);
            Console.WriteLine("Contact '{0}' created successfully.", contact.DisplayName);
        }
        catch (Exception ex)
        {
            // Print out the exception and the last eight characters of the item ID.
            Console.WriteLine("Exception while creating contact {0}: {1}", contact.Id.ToString().Substring(144), ex.Message);
        }
    }
    // Determine whether the CreateItems method call completed successfully.
    if (response.OverallResult == ServiceResult.Success)
    {
            Console.WriteLine("All locally created contacts were successfully created in the Contacts folder.");
            Console.WriteLine("\r\n");
    }
   
    // If the method did not return success, print the result message for each contact.
    else
    {
        int counter = 1;
        foreach (ServiceResponse resp in response)
        {
            // Print out the result and the last eight characters of the item ID.
            Console.WriteLine("Result (contact {0}), id {1}: {2}", counter, itemIds[counter - 1].ToString().Substring(144), resp.Result);
            Console.WriteLine("Error Code: {0}", resp.ErrorCode);
            Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
            Console.WriteLine("\r\n");
            counter++;
        }
    }
    return itemIds;
}

Создание контактов в пакетах с помощью EWS

Контакты можно создавать пакетами с помощью операции CreateItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для создания контактов в пакетах.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://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>
        <m:SavedItemFolderId>
          <t:DistinguishedFolderId Id="contacts" />
        </m:SavedItemFolderId>
        <m:Items>
          <t:Contact>
            <t:DisplayName>Sadie Daniels</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">sadie@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
          <t:Contact>
            <t:DisplayName>Alfred Welker</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">alfred@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
          <t:Contact>
            <t:DisplayName>Hope Gross</t:DisplayName>
            <t:EmailAddresses>
              <t:Entry Key="EmailAddress1">hope@contoso.com</t:Entry>
            </t:EmailAddresses>
          </t:Contact>
        </m:Items>
      </m:CreateItem>
    </soap:Body>
  </soap:Envelope>

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

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

Вы можете получать контакты пакетными пакетами с помощью метода BindToItems управляемого API EWS, как показано в следующем примере. В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

public static Collection<Contact> BatchGetContactItems(ExchangeService service, Collection<ItemId> itemIds)
        {
            // Create a property set that limits the properties returned by the Bind method to only those that are required.
            PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, ContactSchema.DisplayName);
            // Get the items from the server.
            // This method call results in a GetItem call to EWS.
            ServiceResponseCollection<GetItemResponse> response = service.BindToItems(itemIds, propSet);
            // Instantiate a collection of Contact objects to populate from the values that are returned by the Exchange server.
            Collection<Contact> contactItems = new Collection<Contact>();
            foreach (GetItemResponse getItemResponse in response)
            {
                try
                {
                    Item item = getItemResponse.Item;
                    Contact contact = (Contact)item;
                    contactItems.Add(contact);
                    // Print out confirmation and the last eight characters of the item ID.
                    Console.WriteLine("Found item {0}.", contact.Id.ToString().Substring(144));
                }
                catch (Exception ex)
                {
                    Console.WriteLine("Exception while getting a contact: {0}", ex.Message);
                }
            }
            // Check for success of the BindToItems method call.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("All contacts retrieved successfully.");
                Console.WriteLine("\r\n");
            }
            return contactItems;
        }

Получение контактов в пакетах с помощью EWS

Вы можете получать контакты пакетами с помощью операции GetItem EWS и кода в следующем примере. Это также XML-запрос, который управляемый API EWS отправляет при использовании управляемого API EWS для получения контактов пакетными пакетами. Атрибут ItemId сокращен для удобства чтения.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://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:GetItem>
        <m:ItemShape>
          <t:BaseShape>IdOnly</t:BaseShape>
          <t:AdditionalProperties>
            <t:FieldURI FieldURI="contacts:DisplayName" />
          </t:AdditionalProperties>
        </m:ItemShape>
        <m:ItemIds>
          <t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
          <t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
          <t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
        </m:ItemIds>
      </m:GetItem>
    </soap:Body>
  </soap:Envelope>

Сервер отвечает на запрос GetItemсообщением GetItemResponse , которое содержит идентификатор и отображаемое имя для каждого из запрошенных контактов.

Обновление контактов в пакетах с помощью управляемого API EWS

Контакты можно обновлять пакетами с помощью метода UpdateItems управляемого API EWS, как показано в следующем примере. В предыдущем примере создается контакт, но не указывается, с кем они работают. Код в этом примере можно использовать для одновременного обновления всех контактов, чтобы включить их название компании.

В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

public static Collection<Contact> BatchUpdateContactItems(ExchangeService service, Collection<Contact> contactItems)
        {
            // Update the company name of each contact locally.
            foreach (Contact contact in contactItems)
            {
                // Update the company name of the contact.
                contact.CompanyName = "Contoso";
                // Print out confirmation with the last eight characters of the item ID and the contact company name.
                Console.WriteLine("Updated local contact {0} with the company name '{1}'.", contact.Id.ToString().Substring(144), contact.CompanyName);
            }
            
            // Send the item updates to the server.
            // This method call results in an UpdateItem call to EWS.
            ServiceResponseCollection<UpdateItemResponse> response = service.UpdateItems(contactItems, WellKnownFolderName.Contacts, ConflictResolutionMode.AutoResolve, null, null);
            // Verify the success of the UpdateItems method call.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("All contacts updated successfully.\r\n");
            }
            // If the method did not return success, print the result message for each contact.
            else
            {
                Console.WriteLine("All contacts were not successfully saved on the server.\r\n");
                int counter = 1;
                foreach (ServiceResponse resp in response)
                {
                    Console.WriteLine("Result for (contact {0}): {1}", counter, resp.Result);
                    Console.WriteLine("Error Code: {0}", resp.ErrorCode);
                    Console.WriteLine("ErrorMessage: {0}\r\n", resp.ErrorMessage);
                    counter++;
                }
            }
            return contactItems;
        }

Обновление контактов в пакетах с помощью EWS

Вы можете обновлять контакты пакетами с помощью операции GetItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для обновления контактов в пакетах. Атрибут ItemId сокращен для удобства чтения.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://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:UpdateItem ConflictResolution="AutoResolve">
        <m:SavedItemFolderId>
          <t:DistinguishedFolderId Id="contacts" />
        </m:SavedItemFolderId>
        <m:ItemChanges>
          <t:ItemChange>
            <t:ItemId Id="ceJwVAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yS" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
          <t:ItemChange>
            <t:ItemId Id="ceJwWAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yT" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
          <t:ItemChange>
            <t:ItemId Id="ceJwXAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yU" />
            <t:Updates>
              <t:SetItemField>
                <t:FieldURI FieldURI="contacts:CompanyName" />
                <t:Contact>
                  <t:CompanyName>Contoso</t:CompanyName>
                </t:Contact>
              </t:SetItemField>
            </t:Updates>
          </t:ItemChange>
        </m:ItemChanges>
      </m:UpdateItem>
    </soap:Body>
  </soap:Envelope>

Сервер отвечает на запрос UpdateItemсообщением UpdateItemResponse , которое содержит значение ResponseCodeNoError, указывающее, что каждое из обновлений успешно сохранено на сервере. Все конфликты отображаются в элементе ConflictResult .

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

Вы можете удалять контакты пакетами с помощью метода EWS EWS Managed API DeleteItems , как показано в следующем примере. В этом примере предполагается, что служба является действительным объектом ExchangeService, и что пользователь прошел проверку подлинности на сервере Exchange server.

public static void BatchDeleteContactItems(ExchangeService service, Collection<ItemId> itemIds)
        {
            // Delete the batch of contact objects.
            // This method call results in an DeleteItem call to EWS.
            ServiceResponseCollection<ServiceResponse> response = service.DeleteItems(itemIds, DeleteMode.SoftDelete, null, AffectedTaskOccurrence.AllOccurrences);
            // Check for success of the DeleteItems method call.
            // DeleteItems returns success even if it does not find all the item IDs.
            if (response.OverallResult == ServiceResult.Success)
            {
                Console.WriteLine("Contacts deleted successfully.\r\n");
            }
            // If the method did not return success, print a message.
            else
            {
                Console.WriteLine("Not all contacts deleted successfully.\r\n");
            }
        }

Удаление контактов в пакетах с помощью EWS

Контакты можно удалять пакетами с помощью операции DeleteItem EWS, как показано в следующем примере кода. Это также XML-запрос, который отправляет управляемый API EWS при использовании управляемого API EWS для удаления контактов пакетами. Атрибут ItemId сокращен для удобства чтения.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
xmlns:t="http://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:DeleteItem DeleteType="SoftDelete" AffectedTaskOccurrences="AllOccurrences">
        <m:ItemIds>
          <t:ItemId Id="ceJwYAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yY" />
          <t:ItemId Id="ceJwZAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51yZ" />
          <t:ItemId Id="ceJwaAAA=" ChangeKey="EQAAABYAAAD2WuN+TpqwSrNP9JCCMKC0AAFc51ya" />
        </m:ItemIds>
      </m:DeleteItem>
    </soap:Body>
  </soap:Envelope>

Сервер отвечает на запрос DeleteItem сообщением DeleteItemResponse , которое содержит значение ResponseCodeNoError для каждого удаленного элемента. Обратите внимание, что операция также возвращает успешное выполнение, если не удалось найти идентификатор элемента.

Проверка успешного выполнения пакетного процесса

Если один или несколько контактов в пакетном запросе не могут быть обработаны в соответствии с запросом, для каждого контакта, который завершился сбоем, возвращается ошибка, а остальные контакты в пакете обрабатываются должным образом. Сбои в пакетной обработке могут возникать, если элемент был удален и, следовательно, не может быть получен или обновлен, или если элемент перемещен в другую папку и, следовательно, имеет новый идентификатор элемента и не может быть изменен с помощью отправленного идентификатора элемента. В этом разделе показано, как получить сведения об ошибках при пакетной обработке контактов.

Чтобы проверить успешность пакетного процесса с помощью управляемого API EWS, можно проверить, что свойство OverallResultобъекта ServiceResponseCollection равно ServiceResult.Success. В этом случае все контакты успешно обработаны. Если значение OverallResult не равно ServiceResult.Success, один или несколько контактов не были успешно обработаны. Каждый из объектов, возвращаемых в ServiceResponseCollection , содержит следующие свойства:

Эти свойства содержат сведения о том, почему контакты не могут быть обработаны по запросу. В примерах, приведенных в этой статье, отображаются значения Result, ErrorCode и ErrorMessage для каждого неудачного контакта. Эти результаты можно использовать для изучения проблемы.

Для EWS, чтобы проверить успешность пакетного процесса, проверьте атрибут ResponseClass для каждого обрабатываемого элемента. Ниже приведена базовая структура ResponseMessageType, базового типа, от которого извлекаются все ответные сообщения.

<ResponseMessage ResponseClass="Success | Warning | Error">
            <MessageText/>
            <ResponseCode/>
            <DescriptiveLinkKey/>
            <MessageXml/>
</ResponseMessage>

Атрибут ResponseClass имеет значение Успешно , если контакт был успешно обработан, или Ошибка , если контакт не был успешно обработан. Для контактов во время пакетной обработки предупреждение не отображается. Если параметр ResponseClass имеет значение Success, то следующий элемент ResponseCode также всегда имеет значение NoError. Если класс ResponseClass имеет значение Error, необходимо проверить значения элементов MessageText, ResponseCode и MessageXml , чтобы определить причину проблемы. DescriptiveLinkKey в настоящее время не используется.

См. также