Compartilhar via

Processar contatos em lotes usando o EWS no Exchange

  • Artigo

Saiba como criar, obter, atualizar e excluir lotes de contatos em uma única chamada usando a API Gerenciada do EWS ou o EWS no Exchange.

Você pode usar a API Gerenciada do EWS ou o EWS para trabalhar com lotes de contatos para reduzir o número de chamadas que um cliente faz a um servidor exchange. Quando você usa a API Gerenciada do EWS para criar, obter, atualizar e excluir contatos em lotes, você usa métodos de objeto ExchangeService , enquanto quando você trabalha com contatos únicos, usa métodos de objeto Contact . Se você estiver usando o EWS, use as mesmas operações para trabalhar com um único contato e lotes de contatos.

Tabela 1. Métodos de API Gerenciada do EWS e operações EWS para trabalhar com lotes de contatos

Para... Use este método de API Gerenciada do EWS Usar essa operação EWS
Criar contatos em lotes
 ExchangeService.CreateItems
CreateItem
Obter contatos em lotes
 ExchangeService.BindToItems ou ExchangeService.LoadPropertiesForItems
GetItem
Atualizar contatos em lotes
 ExchangeService.UpdateItems
UpdateItem
Excluir contatos em lotes
 ExchangeService.DeleteItems
DeleteItem

Neste artigo, você aprenderá a concluir tarefas básicas para lotes de contatos usando a API Gerenciada do EWS ou o EWS.

Criar contatos em lotes usando a API Gerenciada do EWS

Você pode criar contatos em lotes usando o método CreateItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir. Este exemplo cria três objetos Contact localmente, adiciona cada contato a uma coleção e, em seguida, chama o método CreateItems na coleção de contatos.

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;
}

Criar contatos em lotes usando o EWS

Você pode criar contatos em lotes usando a operação CreateItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para criar contatos em lotes.

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

O servidor responde à solicitação CreateItem com uma mensagem CreateItemResponse que inclui um valor ResponseCode de NoError para cada um dos novos contatos, o que indica que cada contato foi criado e salvo com êxito.

Obter contatos em lotes usando a API Gerenciada do EWS

Você pode obter contatos em lotes usando o método BindToItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir. Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.

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;
        }

Obter contatos em lotes usando o EWS

Você pode obter contatos em lotes usando a operação GetItem EWS e o código no exemplo a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para obter contatos em lotes. O atributo ItemId foi abreviado para legibilidade.

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

O servidor responde à solicitação GetItem com uma mensagem GetItemResponse que inclui a ID e o nome de exibição de cada um dos contatos solicitados.

Atualizar contatos em lotes usando a API Gerenciada do EWS

Você pode atualizar contatos em lotes usando o método UpdateItems da API Gerenciada do EWS, conforme mostrado no exemplo a seguir. O exemplo anterior cria o contato, mas não especifica para quem eles trabalham. Você pode usar o código neste exemplo para atualizar todos os seus contatos de uma só vez para incluir o nome da empresa.

Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.

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;
        }

Atualizar contatos em lotes usando o EWS

Você pode atualizar contatos em lotes usando a operação GetItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para atualizar contatos em lotes. O atributo ItemId foi abreviado para legibilidade.

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

O servidor responde à solicitação UpdateItem com uma mensagem UpdateItemResponse que inclui um valor ResponseCode de NoError, que indica que cada uma das atualizações foi salva com êxito no servidor. Todos os conflitos são relatados no elemento ConflictResult .

Excluir contatos em lotes usando a API Gerenciada do EWS

Você pode excluir contatos em lotes usando o método de API Gerenciada do DeleteItems EWS, conforme mostrado no exemplo a seguir. Esse exemplo pressupõe que serviço seja um objeto ExchangeService válido e que o usuário tenha sido autenticado em um servidor Exchange.

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");
            }
        }

Excluir contatos em lotes usando o EWS

Você pode excluir contatos em lotes usando a operação DeleteItem EWS, conforme mostrado no exemplo de código a seguir. Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa a API Gerenciada do EWS para excluir contatos em lotes. O atributo ItemId foi abreviado para legibilidade.

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

O servidor responde à solicitação DeleteItem com uma mensagem DeleteItemResponse que inclui um valor ResponseCode de NoError para cada item que foi removido. Observe que a operação também retornará êxito se a ID do item não puder ser encontrada.

Verificando se um processo em lote foi concluído com êxito

Quando um ou mais contatos em uma solicitação em lote não podem ser processados conforme solicitado, um erro é retornado para cada contato que falhou e o restante dos contatos no lote são processados conforme o esperado. Falhas no processamento em lote podem ocorrer se o item foi excluído e, portanto, não puder ser recuperado ou atualizado, ou se o item for movido para uma pasta diferente e, portanto, tiver uma nova ID do item e não puder ser modificado com a ID do item enviada. As informações nesta seção mostram como obter detalhes de erro sobre falhas no processamento em lote de contatos.

Para verificar o sucesso de um processo em lote usando a API Gerenciada do EWS, verifique se a propriedade OverallResult do ServiceResponseCollection é igual a ServiceResult.Success. Nesse caso, todos os contatos foram processados com êxito. Se o OverallResult não for igual a ServiceResult.Success, um ou mais contatos não foram processados com êxito. Cada um dos objetos retornados no ServiceResponseCollection contém as seguintes propriedades:

Essas propriedades contêm informações sobre por que os contatos não puderam ser processados conforme solicitado. Os exemplos neste artigo imprimem o Resultado, o ErrorCode e o ErrorMessage para cada contato com falha. Você pode usar esses resultados para investigar o problema.

Para eWS, para verificar o sucesso de um processo em lote, verifique o atributo ResponseClass para cada item que está sendo processado. A seguir está a estrutura básica do ResponseMessageType, o tipo base do qual todas as mensagens de resposta são derivadas.

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

O atributo ResponseClass será definido como Êxito se o contato foi processado com êxito ou Erro se o contato não tiver sido processado com êxito. Para contatos, você não encontrará um Aviso durante o processamento em lote. Se o ResponseClass for Success, o elemento ResponseCode a seguir também será sempre definido como NoError. Se a ResponseClass for Error, você precisará verificar os valores dos elementos MessageText, ResponseCode e MessageXml para determinar o que causou o problema. O DescriptiveLinkKey está atualmente não utilizado.

Confira também