Uso de la API administrada de Exchange Web Services
En este artículo me gustaría hablar de la API administrada de Exchange Web Services.
La API gestionada o administrada de Exchange Web Services (EWS) permite el desarrollo, de una manera simple y completa, de aplicaciones cliente que hagan uso de los EWS. De este modo, gracias a esta API, se pueden acceder a los EWS en Office365, Exchange Online y las versiones de Exchange a partir de Exchange Server 2007 Service Pack 1.
Dicha API se puede utilizar mediante lenguaje de programación C# o directamente con Powershell.
Alguna de las cosas que se pueden hacer con esta API son:
- Crear, enviar o responder mensajes de correo.
- Buscar carpetas, mensajes, reuniones y tareas.
- Gestionar elementos del calendario.
- Utilizar el servicio de Autodiscover para una cuenta de correo, y obtener así la configuración del usuario y dominio inherentes a la misma, necesaria para establecer una conexión con el servidor Exchange.
Otros usos más avanzados incluirían sincronización, tratamiento de listas de distribución o conversaciones.
A modo de esbozo, cabe destacar que todos los métodos y tipos empleados en la API se enmarcan en tres namespaces:
- Microsoft.Exchange.WebServices.Auth.Validation: contiene tipos y métodos empleados para validar los tokens de identidad del usuario enviados desde un servidor Exchange. Solo aplicables a Exchange Online o Exchange Server 2013 en adelante. Este namespace está incluido en la API Microsoft.Exchange.WebServices.Auth.dll.
- Microsoft.Exchange.WebServices.Autodiscover: incluye tipos empleados en la comunicación con el servicio Autodiscover alojado en un servidor Exchange. Proporciona básicamente información de configuración a los clientes EWS, lo que habilita a estos a dirigirse al servicio URL apropiado. Al igual que el otro namespace, está incluido en la API Microsoft.Exchange.WebServices.dll.
- Microsoft.Exchange.WebServices.Data: proporciona la base de la funcionalidad de la API. Contiene tipos usados en la comunicación con un servidor Exchange a través de EWS.
Para utilizar la API se necesita de lo siguiente:
- Una versión de dicha API. Se utilizará la versión 2.2 (última versión disponible en el momento de escribir este artículo). Requiere una instalación.
- Un cuenta de correo en un servidor Exchange (cualquiera de las versiones anteriormente nombradas) con sus correspondientes credenciales.
- La versión de .NET Framework debe ser igual o superior a la 3.5.
Para dar un pequeño sentido práctico a lo dicho, se muestra a continuación como se llevaría cabo la activación/desactivación del mensaje Out Of Office (OOF) tanto en Powershell como en C# utilizando la API (aquí se explicó como realizarlo en Powershell mediante cmdlet directo):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
# Se necesita instalar la API del Exchange Web Services # Descargarla en - http://www.microsoft.com/en-us/download/confirmation.aspx?id=42022 Add-Type -Path "C:Program FilesMicrosoftExchangeWeb Services2.2Microsoft.Exchange.WebServices.dll" # Solicita las credenciales $cred=Get-Credential Write-Host -ForegroundColor White "Configurando..." $emailAccount = "usuario@empresa.com" # Cambiar la versión de Exchange que corresponda al entorno $EWS = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService([Microsoft.Exchange.WebServices.Data.ExchangeVersion]::Exchange2013_SP1) $EWS.Credentials=New-Object Microsoft.Exchange.WebServices.Data.WebCredentials -ArgumentList $cred.UserName,$cred.GetNetworkCredential().Password # Autodiscovery Write-Host -ForegroundColor White "Autodiscovering...(esto puede llevar un rato)" $EWS.AutodiscoverUrl($emailAccount,{$true}) # Guardando la configuración de Out Of Office $oofSetting=$EWS.GetUserOofSettings($emailAccount) Write-Host -ForegroundColor White "La configuración de Out Of Office se ha guardado en `$oofSetting" ############################################################# # Activa el Out Of Office $oofSetting.InternalReply.ToString() # Muestra el mensaje interno $oofSetting.ExternalReply.ToString() # Muestra el mensaje externo de la organización $oofSetting.Duration # Muestra la fecha de inicio y la fecha de fin de duracion del mensaje $oofSetting.InternalReply.Message="Ahora mismo no me encuentro en la oficina" # Establece el mensaje interno $oofSetting.ExternalReply.Message="Ahora mismo no me encuentro en la oficina" # Establece el mensaje externo de la organizacion $oofSetting.State=[Microsoft.Exchange.WebServices.Data.OofState]::Enabled # Cambia el estado a activado $EWS.SetUserOofSettings($emailAccount,$oofSetting) # Y aplica el cambio # Desactiva el Out Of Office $oofSetting.State=[Microsoft.Exchange.WebServices.Data.OofState]::Disabled # Cambia el estado a desactivado $EWS.SetUserOofSettings($emailAccount,$oofSetting) # Y aplica el cambio |
Y empleando C#, el modo de hacerlo sería el siguiente:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; using Microsoft.Exchange.WebServices.Data; namespace OutOfOffice { class Program { static void Main(string[] args) { ExchangeService service = new ExchangeService(ExchangeVersion.Exchange2013_SP1); String mensaje,estado,email,password; OofSettings oofsettings; Microsoft.Exchange.WebServices.Data.OofState desactivado = Microsoft.Exchange.WebServices.Data.OofState.Disabled; Microsoft.Exchange.WebServices.Data.OofState activado = Microsoft.Exchange.WebServices.Data.OofState.Enabled; email="usuario@empresa.com"; password="password"; service.Credentials = new WebCredentials(email,password); service.TraceEnabled = true; service.TraceFlags = TraceFlags.None; //Servicio de Autodiscover// System.Console.WriteLine("Autodiscovering...(puede llevar un rato)"); service.AutodiscoverUrl(email, RedirectionUrlValidationCallback); //Guarda la configuración de Out Of Office en una variable// oofsettings = service.GetUserOofSettings(email); //Guarda el mensaje interno en la variable mensaje y lo muestra// mensaje = oofsettings.InternalReply.ToString(); System.Console.WriteLine(mensaje); //Cambia el estado de OOO a activado y lo aplica// oofsettings.State = activado; service.SetUserOofSettings(email, oofsettings); //Muestra el estado del Out Of Office (Enabled/Disabled/Scheduled)// estado = oofsettings.State.ToString(); System.Console.Write("Status Out Of Office: "); System.Console.WriteLine(estado); //Cambia el estado de OOO a desactivado y lo aplica// oofsettings.State = desactivado; service.SetUserOofSettings(email, oofsettings); } private static bool RedirectionUrlValidationCallback(string redirectionUrl) { //Por defecto en la callback de validación se rechaza la URL// bool result = false; Uri redirectionUri = new Uri(redirectionUrl); //Valida los contenidos de la redireccion URL. En esta sencilla callback de validacion, la URL de redireccion se considera// //valida si se esta utilizando HTTPS para encriptar las credenciales de autenticacion// if (redirectionUri.Scheme == "https") { result = true; } return result; } } } |
Como puede verse, el uso de la API es directo en ambos casos.
Y esto es todo por ahora. Espero que este ejemplo, aunque sencillo, sirva para ilustrar la sencillez de uso de esta versátil e interesante API.