Trabajar con elementos de buzón de Exchange mediante EWS en Exchange
Obtenga información sobre cómo crear, obtener, actualizar y eliminar elementos mediante la API administrada de EWS o EWS en Exchange.
Puede usar la API administrada de EWS o EWS para trabajar con elementos de un buzón. Puede usar elementos genéricos (objetos de elemento de API administrada de EWS o tipos de elementos de EWS) para realizar algunas operaciones (obtener un elemento o eliminar un elemento mediante el identificador del elemento); sin embargo, la mayor parte del tiempo tendrá que usar un elemento fuertemente tipado para realizar una operación de obtención o actualización, ya que necesitará acceso a las propiedades específicas del elemento fuertemente tipado.
Por ejemplo, no puede usar un elemento genérico para recuperar un elemento que contiene una fecha de inicio y finalización: necesita un objeto appointment de API administrada de EWS o un tipo CalendarItem de EWS para hacerlo. Y si usa la API administrada de EWS, siempre tiene que crear elementos fuertemente tipados, porque la clase item genérica no tiene un constructor. Si está trabajando con un elemento que no está fuertemente tipado, siempre puede usar la clase item base para trabajar con el elemento.
Tabla 1. Métodos de API administrada de EWS y operaciones de EWS para trabajar con elementos
| Para | Método de la API administrada de EWS | Operación de EWS |
|---|---|---|
| Creación de un elemento genérico |
Ninguno. Solo puede crear tipos de elementos específicos mediante la API administrada de EWS; no se pueden crear elementos genéricos. |
CreateItem |
| Obtener un elemento |
Item.Bind |
GetItem |
| Actualizar un elemento |
Item.Update |
UpdateItem |
| Eliminar un elemento |
Item.Delete |
DeleteItem |
En este artículo, aprenderá cuándo puede usar la clase base genérica y cuándo debe usar un elemento fuertemente tipado para completar la tarea. En los ejemplos de código se muestra cómo usar la clase base y qué hacer cuando no se puede usar la clase base o no se ajusta a sus necesidades.
Creación de un elemento mediante la API administrada de EWS
La API administrada de EWS no tiene un constructor disponible públicamente para la clase Item , por lo que debe usar el constructor para el tipo de elemento específico que desea crear para crear un elemento. Por ejemplo, use el constructor de clases EmailMessage para crear un mensaje de correo electrónico y el constructor de clase Contact para crear un nuevo contacto. Del mismo modo, el servidor nunca devuelve objetos Item genéricos en las respuestas; todos los elementos genéricos se devuelven como objetos EmailMessage .
Cuando conozca el tipo de elemento que se va a crear, puede completar la tarea en unos pocos pasos. Los pasos son similares para todos los tipos de elementos:
Inicialice una nueva instancia de una de las clases Item con el objeto ExchangeService como parámetro.
Establezca las propiedades en el elemento. Los esquemas son diferentes para cada tipo de elemento, por lo que hay diferentes propiedades disponibles para diferentes elementos.
Guarde el elemento o guárdelo y envíelo.
Por ejemplo, puede crear un objeto EmailMessage , establecer las propiedades Subject, Body y ToRecipients y, a continuación, enviarlo mediante el 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 obtener información sobre cómo crear un elemento de reunión o cita mediante la API administrada de EWS, consulte Creación de citas y reuniones mediante EWS en Exchange 2013.
Creación de un elemento mediante EWS
Puede crear un elemento genérico o un elemento fuertemente tipado mediante EWS. Los pasos son similares para todos los tipos de elementos:
Use la operación CreateItem para crear un elemento en el almacén de Exchange.
Use el elemento Items para contener uno o varios elementos que se van a crear.
Establezca las propiedades en el elemento.
Por ejemplo, puede crear un mensaje de correo electrónico y enviarlo mediante el código del ejemplo siguiente. Esta también es la solicitud XML que la API administrada de EWS envía cuando se llama al método SendAndSaveCopy .
<?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 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>
El servidor responde a la solicitud CreateItem con un mensaje CreateItemResponse que incluye un valor ResponseCode de NoError, que indica que el correo electrónico se creó correctamente y el ItemId del mensaje recién creado.
Para obtener información sobre cómo crear un elemento de reunión o cita mediante EWS, vea Crear citas y reuniones mediante EWS en Exchange 2013.
Obtener un elemento mediante la API administrada de EWS
Para usar la API administrada de EWS para obtener un elemento si conoce el Item.Id del elemento que se va a recuperar, simplemente llame a uno de los métodos Bind en el elemento y se recupere el elemento. Como procedimiento recomendado, se recomienda limitar las propiedades devueltas solo a las necesarias. En este ejemplo se devuelve la propiedad Id de elemento y la propiedad Subject .
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange. La variable local itemId es el identificador del elemento que se va a actualizar.
// 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);
Si busca un elemento que cumpla criterios específicos, haga lo siguiente:
Enlace a la carpeta que contiene los elementos que se van a obtener.
Cree una instancia de SearchFilter.SearchFilterCollection o propertySet para filtrar los elementos que se van a devolver.
Cree una instancia de un objeto ItemView o CalendarView para especificar el número de elementos que se devolverán.
Llame al método ExchangeService.FindItems o ExchangeService.FindAppointments .
Por ejemplo, si desea recuperar mensajes de correo electrónico no leídos en la Bandeja de entrada, use el código del ejemplo siguiente. En este ejemplo se usa SearchFilterCollection para limitar los resultados del método FindItems a mensajes no leídos y se limita ItemView para limitar los resultados a un elemento. Este código determinado solo funciona en objetos EmailMessage porque el valor EmailMessageSchema.IsRead forma parte de 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, puede usar un PropertySet para limitar los resultados de la búsqueda, como se muestra en el ejemplo de código siguiente. En este ejemplo se usa el método FindAppointments para recuperar hasta cinco citas que se producen en los próximos 30 días. Este código, por supuesto, solo funciona en elementos de calendario.
// 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);
Tenga en cuenta que la información que devuelve el servidor en la respuesta del método Bind es diferente de la información que devuelve el servidor para una respuesta de método FindItem o FindAppointment . El método Bind puede devolver todas las propiedades esquematizadas, mientras que los métodos FindItem y FindAppointment no devuelven todas las propiedades esquematizadas. Por lo tanto, si necesita acceso completo al elemento, tendrá que usar el método Bind . Si no tiene el id. de elemento del elemento que desea recuperar, use los métodos FindItem o FindAppointment para recuperar el identificador y, a continuación, use el método Bind para recuperar las propiedades que necesita.
Para obtener información sobre cómo obtener un elemento de reunión o cita mediante la API administrada de EWS, vea Obtener citas y reuniones mediante EWS en Exchange.
Obtener un elemento mediante EWS
Si conoce el ItemId del elemento que se va a recuperar, puede obtener el elemento mediante la operación GetItem .
En el ejemplo siguiente se muestra la solicitud XML para obtener el asunto de un elemento con un ItemId específico. Esta es también la solicitud XML que la API administrada de EWS envía al llamar al método Bind en un ItemId. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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="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>
En el ejemplo siguiente se muestra la respuesta XML que devuelve el servidor después de procesar la operación GetItem . La respuesta indica que el elemento se recuperó correctamente. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://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>
Si no conoce el itemId del elemento que desea recuperar, puede usar la operación FindItem para buscar el elemento. Para usar la operación FindItem , primero debe identificar la carpeta que está buscando. Puede identificar la carpeta mediante su DistinguinguishedFolderName o mediante FolderId. Puede usar las operaciones FindFolder o SyncFolderHierarchy para obtener el FolderId que necesita. A continuación, use la operación FindItem para buscar en esa carpeta resultados que coincidan con el filtro de búsqueda. A diferencia de la API administrada de EWS, EWS no proporciona una operación de búsqueda independiente para las citas. La operación FindItem recupera elementos de todos los tipos.
En el ejemplo siguiente se muestra la solicitud de operación FindItem XML que se envía al servidor para buscar citas en la carpeta Calendario que se producen en los próximos 30 días. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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: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>
El servidor responde a la solicitud FindItem con un mensaje FindItemResponse que incluye el valor ResponseCode de NoError, lo que indica que la operación se completó correctamente. Si algún elemento de calendario cumple los criterios de filtrado, se incluyen en la respuesta.
Tenga en cuenta que la información que devuelve el servidor en la respuesta de la operación GetItem es diferente de la información que devuelve el servidor en una respuesta de operación FindItem o FindAppointment . La operación GetItem puede devolver todas las propiedades esquematizadas, mientras que las operaciones FindItem y FindAppointment no devuelven todas las propiedades esquematizadas. Por lo tanto, si necesita acceso completo al elemento, tendrá que usar la operación GetItem . Si no tiene el ItemId del elemento que desea recuperar, use las operaciones FindItem o FindAppointment para recuperar el ItemId y, a continuación, use la operación GetItem para recuperar los elementos que necesita.
Para obtener información sobre cómo obtener un elemento de reunión o cita mediante EWS, vea Obtener citas y reuniones mediante EWS en Exchange.
Actualización de un elemento mediante la API administrada de EWS
Los pasos para actualizar un elemento mediante la API administrada de EWS son similares para todos los tipos de elementos; sin embargo, las propiedades del elemento son diferentes para cada tipo de elemento y el método Update tiene muchos métodos sobrecargados entre los que elegir. Para actualizar un elemento:
Use el método Bind para obtener la versión más reciente del elemento, a menos que ya lo tenga. Para actualizar las propiedades específicas de un elemento fuertemente tipado, tendrá que enlazar a ese tipo de elemento. Para actualizar las propiedades disponibles en el tipo de elemento genérico, puede enlazar al objeto Item .
Actualice las propiedades del elemento.
Llame al método Update .
Por ejemplo, puede actualizar el asunto de un correo electrónico mediante el tipo de elemento genérico, como se muestra en el código del ejemplo siguiente.
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange. La variable local itemId es el identificador del elemento que se va a actualizar.
// 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 obtener información sobre cómo actualizar un elemento de reunión o cita mediante la API administrada de EWS, vea Actualizar citas y reuniones mediante EWS en Exchange.
Actualización de un elemento mediante EWS
Para actualizar un elemento mediante EWS, haga lo siguiente:
Use la operación GetItem para obtener la versión más reciente del elemento, a menos que ya lo tenga.
Use la operación UpdateItem para especificar campos para actualizar y asignar nuevos valores a esos campos.
En el ejemplo siguiente se muestra la solicitud de operación UpdateItem XML que se envía al servidor para actualizar el valor Subject del mensaje de correo electrónico. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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="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>
El servidor responde a la solicitud UpdateItem con un mensaje UpdateItemResponse que incluye el valor ResponseCode de NoError, lo que indica que la actualización del elemento se realizó correctamente.
Para obtener información sobre cómo actualizar un elemento de reunión o cita mediante EWS, vea Actualizar citas y reuniones mediante EWS en Exchange.
Eliminación de un elemento mediante la API administrada de EWS
Para eliminar elementos, muéstrelos a la carpeta Elementos eliminados o al contenedor de memoria. Si conoce el ItemId del elemento que se va a eliminar, simplemente llame al método Delete en el elemento.
Si necesita encontrar el elemento antes de eliminarlo, haga lo siguiente:
Llame al método FindItems o FindAppointments para buscar el elemento que se va a eliminar.
Cree una instancia de PropertySet y limite el valor a las propiedades que se van a devolver o use SearchFilterCollection para buscar elementos específicos.
Cree una instancia de ItemView o CalendarView para especificar el número de elementos que se devolverán.
Llame al método Delete .
Por ejemplo, el código siguiente muestra cómo mover un mensaje de correo electrónico a la carpeta Elementos eliminados.
En este ejemplo se supone que service es un objeto ExchangeService válido y que el usuario se ha autenticado en un servidor Exchange. La variable local itemId es el identificador del elemento que se va a actualizar.
// 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 obtener más información sobre cómo eliminar elementos, vea Eliminación de elementos mediante EWS en Exchange. Para obtener información sobre cómo eliminar un elemento de reunión o cita mediante la API administrada de EWS, consulte Eliminación de citas y cancelación de reuniones mediante EWS en Exchange.
Eliminación de un elemento mediante EWS
Puede eliminar un elemento mediante la operación DeleteItem .
En el ejemplo siguiente se muestra la solicitud XML que se envía al servidor para mover el mensaje de correo electrónico a la carpeta Elementos eliminados. Los valores de algunos atributos y elementos se han acortado para mejorar la legibilidad.
<?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="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>
El servidor responde a la solicitud DeleteItem con un mensaje DeleteItemResponse que incluye el valor ResponseCode de NoError, lo que indica que la eliminación del elemento se realizó correctamente.
Para obtener más información sobre cómo eliminar elementos, vea Eliminación de elementos mediante EWS en Exchange. Para obtener información sobre cómo eliminar un elemento de reunión o cita mediante EWS, vea Eliminar citas y cancelar reuniones mediante EWS en Exchange.
Mover o copiar elementos a otro buzón
Puede mover o copiar elementos entre buzones mediante las operaciones ExportItems y UploadItems . Para obtener más información, vea Exportación e importación de elementos mediante EWS en Exchange.
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de