Como cada tres meses, acaba de ver a luz un nuevo número de la revista digital CompartiMOSS. En dicho número he colaborado con un artículo introduciendo las nuevas API’s para desarrolladores en Office 365.
En este nuevo número ENCAMINA ha estado muy representada ya que nuestros compañeros Alberto Díaz, Javier Menendez y Luis Emilio Lopez han escrito un artículo. Sin que suene a pelota os recomiendo estos artículos por varios motivos:
Además de estos artículos para mi hay una serie de artículos que son de obligada lectura:
Nota: Estas API’s están en fase de Preview y pueden sufrir alguna modificación cuando se lance la versión definitiva. Naturalmente, no se recomienda el uso de ninguna de estas API’s en un entorno de producción.
Introducción
En la Conferencia de SharePoint que tuvo lugar en las Vegas el pasado mes de Abril, Microsoft presentó muchas novedades para nuestro servidor favorito sobre todo en la versión Online: nuevos formularios para sustituir a InfoPath, Office Graph, novedades en las APPs (App Model Cloud), versión SDK para Android, mejoras en la API REST, novedades en NAPA… y la aparición de nuevas API para Office 365.
Estas APIS son:
Además de estas API’s, el uso de las mismas es posible gracias a otra de las novedades que se han introducido como es la posibilidad de implementar OAuth fuera del contexto de SharePoint. Es decir, tengo una aplicación fuera del contexto de Office365, y le puedo dar permisos para utilizar estos datos. Esta técnica de delegación de las credenciales está presente en casi todas las aplicaciones móviles, como por ejemplo cualquier app de Twitter, Instagram, etc. Cómo se implementa esta delegación de credenciales no es objeto de este artículo, para información de cómo realizarlo se puede consultar este enlace: http://msdn.microsoft.com/es-ES/library/office/dn605895
Damos tanta importancia a estas API’s es porque desde que se presentó el nuevo modelo de Apps y la Office Store, Microsoft no había presentado casi novedades. Algunas de estas API’s (como por ejemplo la API de Exchange) eran continuas reclamaciones que le hacíamos los desarrolladores para poder implementar aplicaciones interesantes y de calidad en la Office Store utilizando Exchange Online. Además el hecho de que estas API’s puedan ser Cross-Plataform da un motivo más a clientes para unirse a Office 365, bien en un entorno hibrido, bien en un entorno cloud.
Desgranando las API’s de Exchange
Las API’s que se incluyen dentro de Exchange son las que más novedades trae y, quizás, de la que más partido se le pueda obtener. Principalmente porque Exchange fue de los primeros productos que se deciden migrar a la nube, con lo cual, la base instalada es bastante amplia.
Mail REST API
La Mail REST API proporciona acceso total a los mensajes de correo electrónico en el buzón de un usuario en Exchange Online. Tenemos las siguientes endpoints disponibles:
Podemos obtener el correo electrónico de dos maneras diferentes. Se puede solicitar un conjunto de mensajes de correo electrónico desde una carpeta, opcionalmente filtro o una ordenación, o puede solicitar una dirección de correo electrónico específica por su propiedad ID.
1.- Obtener los mails de la carpeta Inbox
| GET https://outlook.office365.com/ews/odata/Me/Inbox/MessagesAccept: application/json;odata.metadata=full
|
2.- Obtener un mail en particular: para ello tendremos que tener el Identificador del mail que queremos consultar
| GET https://outlook.office365.com/EWS/OData/Me/Messages(‘ ID del mensaje’)Accept: application/json;odata.metadata=full
|
Otra de las propiedades que se dispone es que dado que hace uso del estándar OData 4.0 podemos realizar filtros, paginación, ordenación y número de elementos a mostrar dentro de la propia petición como por ejemplo:
| GET https://outlook.office365.com/ews/odata/Me/Inbox/Messages?$orderby=DateTimeReceived&$filter=Importance eq Microsoft.Exchange.Services.OData.Model.Importance’Low’&$select=Subject,Importance,DateTimeReceived&$top=5Accept: application/json;odata.metadata=full
|
En el ejemplo propuesto ordenamos los mensajes por fecha de creación haciendo uso de $orderby, filtramos mediante el parámetro $filter por los elementos que son de importancia “Low” y mostramos los siguientes campos: Subject , Importance y DateTimeReceived utilizando $select. Indicamos el número de elementos que nos traemos con la sentencia $top donde en este caso nos trae los primeros 5 elementos.
Nota: En cuanto al número de elementos que nos podemos traer por petición tiene un máximo de 500 items, por defecto está limitado a 50 pero se puede incrementar hasta 500 items.
Para crear un mail tendremos que crear un objeto JSON con la estructura de un mail: Mensaje, Cuerpo y Recipientes. El objeto tendría la siguiente estructura:
| { «@odata.type»: «#Microsoft.Exchange.Services.OData.Model.Message», «Subject»: «Articulo Compartimos para utilizar las nuevas APIS de Office 365», «Importance»: «High», «Body»: { «ContentType»: «HTML», «Content»: «Aquí está el articulo leerlo y cualquier cosa me decís» }, «ToRecipients»: [ { «Name»: «Alberto Diaz», «Address»: «adiazcan@compartimoss.com» },{ «Name»: «JC Gonzalez», «Address»: «jcg1981@compartimoss.com» },{ «Name»: «Fabian Imaz», «Address»: «Fabian.imaz@compartimoss.com» },{ «Name»: «Gustavo Velez», «Address»: «Gustavo.velez@compartimoss.com» } ]} |
Sobre este objeto realizaremos la siguiente petición:
| POST https://outlook.office365.com/ews/odata/Me/Drafts/MessagesAccept: application/json;odata.metadata=full Content-Type: application/json;odata.metadata=full |
NOTA: En el momento que creas un mail por defecto se crea dentro de la carpeta de borradores (se puede modificar para que directamente se envíe el mail directamente estableciendo el parámetro “MessageDispostion” al valor “SendAndSaveCopy”, el valor por defecto es “SaveOnly”).
Una vez tenemos un mensaje en la carpeta de borradores, podemos realizar cualquier modificación del mismo, por un lado, generamos el objeto JSON con los campos a modificar, por ejemplo, vamos a modificar el Cuerpo del mensaje:
| {«Body»: { «ContentType»: «HTML», «Content»: «Vamos a modificar el mensaje!!” } } |
Con el objeto creado se realiza la siguiente petición:
| PATCH https://outlook.office365.com/ews/odata/Me/Messages(‘IdentificadordelMensaje’)Accept: application/json;odata.metadata=full Content-Type: application/json;odata.metadata=full |
Se puede eliminar correo electrónico, simplemente enviando una solicitud DELETE para la dirección de la entidad de mensajes como por ejemplo, la siguiente petición.
| DELETE https://outlook.office365.com/ews/odata/Me/Messages(‘IdentificadordelMensaje’) |
Mediante la API se pueden enviar mails de dos formas:
| POST https://outlook.office365.com/ews/odata/Me/Messages(‘IdentificadordelMensaje») |
| POST https://outlook.office365.com/ews/odata/Me/Drafts/Messages? MessageDisposition=SendAndSaveCopyAccept: application/json;odata.metadata=full Content-Type: application/json;odata.metadata=full |
Calendar REST API
Con el Calendar API vamos a tener acceso tanto a los grupos del Calendario como los propios elementos, desde la propia API se va a poder contestar a Reuniones o Meetings propuestos.
En Outlook y Outlook Web App, los usuarios pueden añadir varios calendarios en un solo grupo de calendario. Esto hace que sea más fácil para los usuarios ver rápidamente todos los calendarios dentro del grupo. Puede acceder a los grupos de calendarios en un buzón de correo a través de la propiedad CalendarGroups en el buzón.
El siguiente ejemplo se solicita a todos los grupos de calendario en el buzón del usuario autenticado.
| GET https://outlook.office365.com/ews/odata/Me/CalendarGroupsAccept: application/json |
Se puede acceder a los calendarios a través de la propiedad “Calendar”, ya sea en el buzón o en un grupo de calendarios específicos. También puede acceder al calendario predeterminado del usuario a través de la propiedad Calendar en el buzón. El siguiente ejemplo se solicita a todos los calendarios en el buzón.
| GET https://outlook.office365.com/ews/odata/Me/CalendarsAccept: application/json |
Con el Calendar REST API se permite crear, actualizar, eliminar, mover y copiar los elementos del calendario. También puede aceptar, rechazar o aceptar provisionalmente las solicitudes de reunión. Los elementos del calendario se dividen en las siguientes categorías:
o Citas – Una entrada básica en un calendario que no tiene asistentes. Se puede acceder a las citas a través de la propiedad Events en un calendario o el buzón.
o Reuniones – una cita con los asistentes. Las convocatorias de reunión se envían cuando se crea una reunión, y los asistentes tendrán la posibilidad de aceptar, rechazar o aceptar provisionalmente la solicitud. Se puede acceder a reuniones a través de la propiedad eventos en un calendario o el buzón.
o Reunión solicitudes – un elemento de calendario que se envía a los asistentes cuando el organizador crea, actualiza o cancela una reunión. Se puede acceder a las solicitudes de reunión a través de la propiedad de los mensajes en las carpetas o el buzón.
Operaciones con la API:
Consultar los elementos del calendario: Mediante la propiedad de Events obtenemos los elementos que tenemos en nuestros calendarios. Además, de la misma forma que con el mail, al hacer uso de OData es posible utilizar la propiedad “filter” para filtrar los elementos que se devolverán en la respuesta.
| GET https://outlook.office365.com/ews/odata/Me/Calendar/Events?$filter=Start le 2014-02-14T05:00:00Z and End ge 2014-02-10T05:00:00ZAccept: application/json |
Actualizar los elementos: Para actualizar un elemento de calendario, hay que realizar una petición PATCH para la URL del evento. En esta petición hay que incluir un objeto JSON con las propiedades para actualizar. Si actualiza una reunión en la que el usuario es el organizador, se envía una actualización a todos los asistentes. El ejemplo siguiente actualiza la ubicación de una reunión.
| PATCH https://outlook.office365.com/ews/odata/Me/Calendar/Events(‘AAMkAGI3…’)Accept: application/json;odata.metadata=full Content-Type: application/json;odata.metadata=full Objeto JSON para actualizar la ubicación de la reunión { «Location»: { «DisplayName»: «Encamina Canarias» } } |
Responder a una petición de reunión: Para responder a una petición hay que realizar varios pasos debido a que una Petición de reunión es un Objeto Mensaje y no un objeto Calendario. Por lo que en primer lugar, tendremos que consultar el mensaje. En dicho mensaje tendremos, por un lado en la propiedad “MeetingMessageType” y, en la siguiente propiedad, tendremos un EventID que es el Identificador de la solicitud (posteriormente lo utilizaremos para contestar a dicha solicitud).
Una vez hemos consultado el mensaje y tenemos la información relativa al EVENTID podemos enviar una contestación a dicha convocatoria. Como por ejemplo:
| POST https://outlook.office365.com/ews/odata/Me/Events(‘Identificador’)/Accept?MessageDisposition=SendAndSaveCopyAccept: application/json Content-Type: application/json;odata.metadata=full Expect: 100-continue
{ «Comment»: «Por mi parte perfecto. Alli estaré!» } |
Contact REST API
Con la Contact REST API puedes consultar, añadir, modificar y eliminar cualquier contacto.
Para obtener contactos, enviar una petición GET a la propiedad contactos de la carpeta de contactos. Dentro de la petición se puede utilizar el parámetro “Select” para indicar las propiedades que queremos que se devuelvan en la respuesta.
| GET https://outlook.office365.com/ews/odata/Me/Contacts?$select=DisplayName,EmailAddress1,Birthday,CategoriesAccept: application/json |
Para añadir un contacto, hay que enviar una solicitud POST en la que se envía un objeto JSON indicando que ese objeto es de tipo Contacto más la representación del contacto.
| POST https://outlook.office365.com/ews/odata/Me/ContactsAccept: application/json Content-Type: application/json;odata.metadata=full
{ «@odata.type»: «#Microsoft.Exchange.Services.OData.Model.Contact», «GivenName»: «Santiago «, «Surname»: “Porras», «EmailAddress1»: «s.porras@mvp.microsoft.com» } |
Para modificar un contacto hay que enviar una solicitud “PATCH” hacia la dirección del contacto y se adjunta un objeto JSON con las propiedades que queremos modificar.
| PATCH https://outlook.office365.com/ews/odata/Me/Contacts(‘sporras@mvp.microsoft.com’)Accept: application/json;odata.metadata=full Content-Type: application/json;odata.metadata=full Expect: 100-continue
{ «Birthday»: «1974-07-22», «Categories»: [ «MVP», «College Friend», “UX”, ] } |
Para eliminar un contacto, enviamos una petición DELETE para la dirección del contacto.
| DELETE https://outlook.office365.com/ews/odata/Me/Contacts(‘ sporras@mvp.microsoft.com ‘)Accept: application/json |
Ejemplo: Utilizas estas API’s en una aplicación ASP NET. MVC
Requisitos Previos
Manos a la obra
Una vez tenemos instalada las Office 365 API Tools, abrimos Visual Studio, crearnos un proyecto ASP. NET MVC 4 seleccionamos la plantilla WebAPI.
A continuación, a nuestro proyecto le vamos a añadir la conexión a los servicios REST de API 365. Para añadirlos, nos dirigimos al Explorador de soluciones, Agregar Servicio conectado tal y como se muestra en la siguiente imagen:
Aparecerá el Administrador de servicios. Selecciona Office365 e introduce el login de tu cuenta. Una vez autentificado contra el Tenant de Office365 podrás ver una lista de tres servicios: Active Directory, Exchange y SharePoint. Inicialmente, la columna Permisos a la derecha de cada servicio estará vacía. En nuestro ejemplo vamos a seleccionar Exchange. Una vez seleccionado pulsamos Aceptar (Imagen 2).
Dado que no están establecidos los permisos, al tratarse de una versión preview, estos se solicitan por pantalla. En nuestro caso, vamos a otorgar todos los permisos para poder ver todas las opciones que vienen incluidas y que hemos visto en este artículo.
Una vez hemos añadido la API a nuestro proyecto revisamos la estructura de nuestro proyecto que quedará de la siguiente forma:
Tal y como hemos remarcado en la imagen, se han añadido dos controladores (ExchangeSampleController, Office365CommonController) 1 modelo (Office365ServiceInfo) y una serie de vistas para poder comprobar la potencia de estas APIs.
Si analizamos los ficheros que se han añadido:
ResourceId = «https://outlook.office365.com/»;
ApiEndpoint = «https://outlook.office365.com/ews/odata»;
AccessToken = Office365CommonController.GetAccessToken(ResourceId);
Una vez analizado el código añadido, vamos a modificar el controlador por defecto, para ello dentro de nuestra solución nos dirigimos a la Carpeta “App_Start”, editamos el fichero RouteConfig.cs. En esta clase tan solo tiene un método “RegisterRoutes”, en el mismo modificamos el controlador por defecto, en nuestro caso “ExchangeSample”, quedando de la siguiente forma:
| public static void RegisterRoutes(RouteCollection routes) { routes.IgnoreRoute(«{resource}.axd/{*pathInfo}»); routes.MapRoute( name: «Default», url: «{controller}/{action}/{id}», defaults: new { controller = «ExchangeSample», action = «Index», id = UrlParameter.Optional } ); } |
Una vez realizada esta modificación, compilamos la solución y si todo ha ido correctamente visualizaremos la imagen 5
Al pulsar sobre cada opción: Calendar, Mail o Contact, se mostrarán las distintas vistas añadidas donde visualizamos la información solicitada a la API correspondiente.
Dejo a la curiosidad de los lectores, añadir muchas más funcionalidades a este ejemplo base, como las operaciones CRUD sobre Calendar, Mail o Contacts.
Conclusión
Office 365 es una plataforma que está creciendo cada vez más. Microsoft, como ha anunciado bastante en el último año, piensa que el futuro es el “CLOUD” y que más pronto que tarde todas las empresas darán el salto. Personalmente, creo que hay productos que aún les falta cierta evolución para que las empresas se planteen dar el salto completo a la nube. Pero con novedades como las presentadas en las Vegas, entre las que se encuentran estas API’s, cada vez hacen que la alternativa del cloud sea una opción más seria y más viable para las empresas.
El poder utilizar las API’s desde aplicaciones fuera del entorno Office 365, es un gran adelanto y algo que facilitará la adopción de la plataforma. Hoy en día, hay muchas empresas que requieren de aplicaciones para el envío de mails, para consultar información de Active Directory, o incluso gestionar calendarios entre los integrantes de su organización. Ahora mismo, el obtener esta información mediante desarrollo es muy complejo y para solventar este inconveniente se planteaban escenarios híbridos. Pero esta solución es más cara y en algunos escenarios no dispones ni de las ventajas del cloud ni las ventajas de tus infraestructuras. Con estas API’s todos estos requerimientos se podrán abordar de una forma simple y transparente.
En el siguiente número de CompartiMOSS desgranaremos las opciones que dispondremos para facilitar el trabajo con ficheros y carpetas en SharePoint/OneDrive como con el Active Directory.
Este sitio web utiliza cookies para que tengas la mejor experiencia de usuario. Si continuas navegando, estás dando tu consentimiento para aceptar las cookies y también nuestra política de cookies (esperemos que no te empaches con tanta cookie 😊)