Trabalhar com itens de caixa de correio do Exchange usando o EWS no Exchange

Artigo
06/01/2021

Saiba como criar, obter, atualizar e excluir itens 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 itens em uma caixa de correio. Você pode usar itens genéricos – objetos de Item da API gerenciada por EWS ou tipos de Item do EWS para executar algumas operações (obter um item ou excluir um item usando o identificador do item); no entanto, a maior parte do tempo você terá que usar um Item fortemente tipado para executar uma operação get ou Update, pois você precisará ter acesso às propriedades que são específicas para o item fortemente tipado.

Por exemplo, você não pode usar um item genérico para recuperar um item que contenha uma data de início e de término-você precisa de um objeto de compromisso da API gerenciada do EWS ou um tipo de CalendarItem do EWS para fazer isso. E se você estiver usando a API gerenciada do EWS, você sempre precisará criar itens fortemente tipados, pois a classe de Item genérico não tem um construtor. Se você estiver trabalhando com um item que não tenha rigidez de tipos, você sempre poderá usar a classe de Item base para trabalhar com o item.

Tabela 1. Métodos da API gerenciada do EWS e operações do EWS para trabalhar com itens

Para...	Método de API gerenciada do EWS	Operação do EWS
Criar um item genérico	Nenhum Você só pode criar tipos de item específicos usando a API gerenciada do EWS; Você não pode criar itens genéricos.	CreateItem
Obter um item	Item. bind	GetItem
Atualizar um item	Item. Update	UpdateItem
Excluir um item	Item. Delete	DeleteItem

Neste artigo, você aprenderá quando você pode usar a classe base genérica e quando precisa usar um item com rigidez de tipos para concluir a tarefa. Os exemplos de código mostrarão como usar a classe base e o que fazer quando você não pode usar a classe base ou não atende às suas necessidades.

Criar um item usando a API gerenciada do EWS

A API gerenciada do EWS não tem um construtor disponível publicamente para a classe Item , portanto, você deve usar o construtor para o tipo de item específico que você deseja criar para criar um item. Por exemplo, use o Construtor de classe EmailMessage para criar uma nova mensagem de email e o Construtor de classe de contato para criar um novo contato. Da mesma forma, o servidor nunca retorna objetos de Item genérico em respostas; todos os itens genéricos são retornados como objetos EmailMessage .

Quando você sabe o tipo de item a ser criado, você pode concluir a tarefa em apenas algumas etapas. As etapas são semelhantes para todos os tipos de item:

Inicializar uma nova instância de uma das classes de Item com o objeto ExchangeService como um parâmetro.
Definir propriedades no item. Os esquemas são diferentes para cada tipo de item e, portanto, propriedades diferentes estão disponíveis para diferentes itens.
Salve o item ou salve e envie o item.

Por exemplo, você pode criar um objeto EmailMessage , definir as Propriedades Subject, Bodye ToRecipients e enviá-lo usando o método EmailMessage. SendAndSaveCopy .

// Create an email message and provide it with connection 
// configuration information by using an ExchangeService object named service.
EmailMessage message = new EmailMessage(service);
// Set properties on the email message.
message.Subject = "Company Soccer Team";
message.Body = "Are you interested in joining?";
message.ToRecipients.Add("sadie@contoso.com");
// Send the email message and save a copy.
// This method call results in a CreateItem call to EWS.
message.SendAndSaveCopy();

Para saber como criar um item de reunião ou compromisso usando a API gerenciada do EWS, confira criar compromissos e reuniões usando o EWS no Exchange 2013.

Criar um item usando o EWS

Você pode criar um item genérico ou um item fortemente tipado usando o EWS. As etapas são semelhantes para todos os tipos de item:

Use a operação CreateItem para criar um item no repositório do Exchange.
Use o elemento Items para conter um ou mais itens a serem criados.
Definir propriedades no item.

Por exemplo, você pode criar uma mensagem de email e enviá-la usando o código no exemplo a seguir. Essa é também a solicitação XML que a API gerenciada do EWS envia quando você chama o método SendAndSaveCopy .

<?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="SendAndSaveCopy">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="sentitems" />
      </m:SavedItemFolderId>
      <m:Items>
        <t:Message>
          <t:Subject>Company Soccer Team</t:Subject>
          <t:Body BodyType="HTML">Are you interested in joining?</t:Body>
          <t:ToRecipients>
            <t:Mailbox>
              <t:EmailAddress>sadie@contoso.com </t:EmailAddress>
              </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
      </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, que indica que o email foi criado com êxito e o ItemId da mensagem recém-criada.

Para saber como criar um item de reunião ou compromisso usando o EWS, confira criar compromissos e reuniões usando o EWS no Exchange 2013.

Obter um item usando a API gerenciada do EWS

Para usar a API gerenciada do EWS para obter um item se você souber o Item.ID do item a ser recuperado, basta chamar um dos métodos BIND no item e o item será recuperado. Como prática recomendada, recomendamos que você limite as propriedades retornadas somente para as que forem necessárias. Este exemplo retorna a propriedade item ID e a propriedade Subject .

Este exemplo pressupõe que o serviço é um objeto ExchangeService válido e que o usuário foi autenticado em um servidor Exchange. A variável local ItemId é a ID do item a ser atualizado.

// As a best practice, limit the properties returned to only those that are required.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, ItemSchema.Subject);
// Bind to the existing item by using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId, propSet);

Se você estiver procurando um item que atenda a critérios específicos, faça o seguinte:

Vincule à pasta que contém os itens a serem obtidos.
Crie uma instância de SearchFilter. SearchFilterCollection ou um PropertySet para filtrar os itens a serem retornados.
Crie uma instância de um objeto item View ou CalendarView para especificar o número de itens a serem retornados.
Chame o método ExchangeService. FindItems ou ExchangeService. FindAppointments .

Por exemplo, se você quiser recuperar mensagens de email não lidas na caixa de entrada, use o código no exemplo a seguir. Este exemplo usa um SearchFilterCollection para limitar os resultados do método FindItems a mensagens não lidas e limita o modo de exibição para limitar os resultados a um item. Este código específico só funciona nos objetos EmailMessage porque o valor de EmailMessageSchema. IsRead é parte do SearchFilter.

// Bind the Inbox folder to the service object.
Folder inbox = Folder.Bind(service, WellKnownFolderName.Inbox);
// The search filter to get unread email.
SearchFilter sf = new SearchFilter.SearchFilterCollection(LogicalOperator.And, new SearchFilter.IsEqualTo(EmailMessageSchema.IsRead, false));
ItemView view = new ItemView(1);
// Fire the query for the unread items.
// This method call results in a FindItem call to EWS.
FindItemsResults<Item> findResults = service.FindItems(WellKnownFolderName.Inbox, sf, view);

Como alternativa, você pode usar um PropertySet para limitar os resultados da pesquisa, conforme mostrado no exemplo de código a seguir. Este exemplo usa o método FindAppointments para recuperar até cinco compromissos que ocorrem nos próximos 30 dias. Este código de curso só funciona em itens de calendário.

// Initialize values for the start and end times, and the number of appointments to retrieve.
DateTime startDate = DateTime.Now;
DateTime endDate = startDate.AddDays(30);
const int NUM_APPTS = 5;
// Bind the Calendar folder to the service object.
// This method call results in a GetFolder call to EWS.
CalendarFolder calendar = CalendarFolder.Bind(service, WellKnownFolderName.Calendar, new PropertySet());
// Set the start and end time and number of appointments to retrieve.
CalendarView cView = new CalendarView(startDate, endDate, NUM_APPTS);
// Limit the properties returned to the appointment's subject, start time, and end time.
cView.PropertySet = new PropertySet(AppointmentSchema.Subject, AppointmentSchema.Start, AppointmentSchema.End);
// Retrieve a collection of appointments by using the calendar view.
// This method call results in a FindAppointments call to EWS.
FindItemsResults<Appointment> appointments = calendar.FindAppointments(cView);

Observe que as informações que o servidor retorna na resposta do método BIND são diferentes das informações que o servidor retorna para uma resposta de método FindItem ou FindAppointment . O método BIND pode retornar todas as propriedades esquematizado, enquanto os métodos FindItem e FindAppointment não retornam todas as propriedades esquematizado. Portanto, se você precisar de acesso completo ao item, será necessário usar o método BIND . Se você não tiver a ID do item que deseja recuperar, use os métodos FindItem ou FindAppointment para recuperar a ID e, em seguida, use o método BIND para recuperar as propriedades que você precisa.

Para saber como obter um item de reunião ou compromisso usando a API gerenciada do EWS, confira obter compromissos e reuniões usando o EWS no Exchange.

Obter um item usando o EWS

Se você souber o ItemId do item a ser recuperado, poderá obter o item usando a operação GetItem .

O exemplo a seguir mostra a solicitação XML para obter o assunto de um item com um ItemIdespecífico. Essa é também a solicitação XML que a API gerenciada do EWS envia ao chamar o método BIND em um ItemId. Os valores de alguns atributos e elementos foram reduzidos para facilitar a leitura.

<?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="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:GetItem>
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:ItemIds>
        <t:ItemId Id="GJc/NAAA=" />
      </m:ItemIds>
    </m:GetItem>
  </soap:Body>
</soap:Envelope>

O exemplo a seguir mostra a resposta XML que o servidor retorna depois de processar a operação GetItem . A resposta indica que o item foi recuperado com êxito. Os valores de alguns atributos e elementos foram reduzidos para facilitar a leitura.

<?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="815" 
                         MinorBuildNumber="6" 
                         Version="V2_7" 
                         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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:GetItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                       xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:GetItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Items>
            <t:Message>
              <t:ItemId Id="GJc/NAAA=" ChangeKey="CQAAABYAAAAPxolXAHv3TaHUnjW8wWqXAAAGJd9Z"/>
              <t:Subject>Company Soccer Team</t:Subject>
            </t:Message>
          </m:Items>
        </m:GetItemResponseMessage>
      </m:ResponseMessages>
    </m:GetItemResponse>
  </s:Body>
</s:Envelope>

Se você não souber o ItemId do item que deseja recuperar, poderá usar a operação FindItem para localizar o item. Para usar a operação FindItem , você deve primeiro identificar a pasta que está pesquisando. Você pode identificar a pasta usando seu DistinguinguishedFolderName ou usando o FolderId. Você pode usar as operações FindFolder ou SyncFolderHierarchy para obter o FolderId necessário. Em seguida, use a operação FindItem para pesquisar na pasta resultados que correspondam ao filtro de pesquisa. Diferentemente da API gerenciada por EWS, o EWS não fornece uma operação de localização separada para compromissos. A operação FindItem recupera itens de todos os tipos.

O exemplo a seguir mostra a solicitação de operação FINDITEM XML que é enviada ao servidor para localizar compromissos na pasta calendário que ocorrem nos próximos 30 dias. Os valores de alguns atributos e elementos foram reduzidos para facilitar a leitura.

<?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:FindItem Traversal="Shallow">
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
          <t:FieldURI FieldURI="calendar:Start" />
          <t:FieldURI FieldURI="calendar:End" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:CalendarView MaxEntriesReturned="5" StartDate="2013-10-16T17:04:28.722Z" EndDate="2013-11-15T18:04:28.722Z" />
      <m:ParentFolderIds>
        <t:FolderId Id="AAAEOAAA=" ChangeKey="AgAAABYAAAAqRr3mNdNMSasqx/o9J13UAAAAAAA3" />
      </m:ParentFolderIds>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

O servidor responde à solicitação FindItem com uma mensagem FindItemResponse que inclui o valor de ResponseCode de NOERROR, que indica que a operação foi concluída com êxito. Se algum item de calendário atender aos critérios de filtragem, ele será incluído na resposta.

Observe que as informações que o servidor retorna na resposta da operação GetItem são diferentes das informações que o servidor retorna em uma resposta de operação FindItem ou FindAppointment . A operação GetItem pode retornar todas as propriedades esquematizado, enquanto as operações FindItem e FindAppointment não retornam todas as propriedades de esquematizado. Portanto, se você precisar de acesso completo ao item, será necessário usar a operação GetItem . Se você não tiver o ItemId do item que deseja recuperar, use as operações FindItem ou FindAppointment para recuperar o ItemIde, em seguida, use a operação GetItem para recuperar os elementos necessários.

Para saber como obter um item de reunião ou compromisso usando o EWS, confira obter compromissos e reuniões usando o EWS no Exchange.

Atualizar um item usando a API gerenciada do EWS

As etapas para atualizar um item usando a API gerenciada do EWS são semelhantes para todos os tipos de item; no entanto, as propriedades do item são diferentes para cada tipo de item, e o método Update tem vários métodos sobrecarregados para escolher. Para atualizar um item:

Use o método BIND para obter a versão mais recente do item, a menos que você já tenha isso. Para atualizar as propriedades específicas de um item com rigidez de tipos, você terá que associar a esse tipo de item. Para atualizar as propriedades disponíveis no tipo de item genérico, você pode associar ao objeto Item .
Atualize as propriedades do item.
Chame o método Update .

Por exemplo, você pode atualizar o assunto de um email usando o tipo de item genérico, conforme mostrado no código no exemplo a seguir.

Este exemplo pressupõe que o serviço é um objeto ExchangeService válido e que o usuário foi autenticado em um servidor Exchange. A variável local ItemId é a ID do item a ser atualizado.

// Bind to the existing item, using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId);
// Update the Subject of the email.
item.Subject = "New subject";
// Save the updated email.
// This method call results in an UpdateItem call to EWS.
item.Update(ConflictResolutionMode.AlwaysOverwrite);

Para saber como atualizar um item de reunião ou compromisso usando a API gerenciada do EWS, confira Atualizar compromissos e reuniões usando o EWS no Exchange.

Atualizar um item usando o EWS

Para atualizar um item usando o EWS, faça o seguinte:

Use a operação GetItem para obter a versão mais recente do item, a menos que você já tenha isso.
Use a operação UpdateItem para especificar os campos a serem atualizados e atribuir novos valores a esses campos.

O exemplo a seguir mostra a solicitação de operação de UPDATEITEM XML que é enviada ao servidor para atualizar o valor de assunto da mensagem de email. Os valores de alguns atributos e elementos foram reduzidos para facilitar a leitura.

<?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="Exchange2010_SP1" />
  </soap:Header>
  <soap:Body>
    <m:UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite">
      <m:ItemChanges>
        <t:ItemChange>
          <t:ItemId Id="APdZjAAA=" ChangeKey="CQAAABYAAAAqRr3mNdNMSasqx/o9J13UAAAAPdgr" />
          <t:Updates>
            <t:SetItemField>
              <t:FieldURI FieldURI="item:Subject" />
              <t:Message>
                <t:Subject>New subject</t:Subject>
              </t:Message>
            </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 o valor de ResponseCode de NOERROR, que indica que a atualização do item foi bem-sucedida.

Para saber como atualizar um item de reunião ou compromisso usando o EWS, confira Atualizar compromissos e reuniões usando o EWS no Exchange.

Excluir um item usando a API gerenciada do EWS

Você pode excluir itens movendo-os para a pasta itens excluídos ou para o dumpster. Se você souber o ItemId do item a ser excluído, basta chamar o método delete no item.

Se você precisar localizar o item antes de excluí-lo, faça o seguinte:

Chame o método FindItems ou FindAppointments para localizar o item a ser excluído.
Instanciar um PropertySet e limitá-lo às propriedades a serem retornadas ou usar um SearchFilterCollection para localizar itens específicos.
Instancie um item View ou CalendarView para especificar o número de itens a serem retornados.
Chame o método delete .

Por exemplo, o código a seguir mostra como mover uma mensagem de email para a pasta itens excluídos.

Este exemplo pressupõe que o serviço é um objeto ExchangeService válido e que o usuário foi autenticado em um servidor Exchange. A variável local ItemId é a ID do item a ser atualizado.

// Bind to the existing item, using the ItemId.
// This method call results in a GetItem call to EWS.
Item item = Item.Bind(service, itemId);
// Delete the item by moving it to the Deleted Items folder.
// This method call results in a DeleteItem call to EWS.
item.Delete(DeleteMode.MoveToDeletedItems);

Para obter mais detalhes sobre como excluir itens, consulte excluindo itens usando o EWS no Exchange. Para saber como excluir um item de reunião ou compromisso usando a API gerenciada do EWS, consulte excluir compromissos e cancelar reuniões usando o EWS no Exchange.

Excluir um item usando o EWS

Você pode excluir um item usando a operação DeleteItem .

O exemplo a seguir mostra a solicitação XML que é enviada ao servidor para mover a mensagem de email para a pasta itens excluídos. Os valores de alguns atributos e elementos foram reduzidos para facilitar a leitura.

<?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="Exchange2010_SP1" />
  </soap:Header>
  <soap:Body>
    <m:DeleteItem DeleteType="MoveToDeletedItems">
      <m:ItemIds>
        <t:ItemId Id="APdZjAAA=" ChangeKey="CQAAABYAAAAqRr3mNdNMSasqx/o9J13UAAANIFzC" />
      </m:ItemIds>
    </m:DeleteItem>
  </soap:Body>
</soap:Envelope>

O servidor responde à solicitação DeleteItem com uma mensagem DeleteItemResponse que inclui o valor de ResponseCode de NOERROR, que indica que a exclusão do item foi bem-sucedida.

Para obter mais detalhes sobre como excluir itens, consulte excluindo itens usando o EWS no Exchange. Para saber como excluir um item de reunião ou compromisso usando o EWS, confira excluir compromissos e cancelar reuniões usando o EWS no Exchange.

Mover ou copiar itens para outra caixa de correio

Você pode mover ou copiar itens entre caixas de correio usando as operações ExportItems e UploadItems . Para saber mais, confira exportando e importando itens usando o EWS no Exchange.

Trabalhar com itens de caixa de correio do Exchange usando o EWS no Exchange

Criar um item usando a API gerenciada do EWS

Criar um item usando o EWS

Obter um item usando a API gerenciada do EWS

Obter um item usando o EWS

Atualizar um item usando a API gerenciada do EWS

Atualizar um item usando o EWS

Excluir um item usando a API gerenciada do EWS

Excluir um item usando o EWS

Mover ou copiar itens para outra caixa de correio

Confira também

Recursos adicionais