Compartimoss 20 Nuevas API’s para desarrolladores en Office 365 Parte I

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:

1. Interesante debate sobre la forma de desarrollar para SharePoint.
2. Saber como se comporta SharePoint desplegado en Azure
3. Conocer las novedades que trae la nueva versión de SQL Server 2014

Además de estos artículos para mi hay una serie de artículos que son de obligada lectura:

• Ajuste de la Relevancia en el Motor de Búsqueda de SharePoint 2013 by Gustavo Velez
• Cómo consumir los Servicios REST de SharePoint Online 2013 desde un WorkFlow en SharePoint Designer 2013 by Andres Ortiz
• Buenas prácticas en infraestructura en SharePoint 2013 – Parte II by Miguel Tabera

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:

• Exchange: Permitir el acceso, añadir y modificar elementos tanto al Calendario, Contactos como enviar y consultar nuevo Mail.
• SharePoint: Facilitar el acceso a carpeta y ficheros. Representa un rediseño del almacenamiento y la administración de archivos de la API de SharePoint
• Active Directory: Consulta, alta y modificación  de usuarios en el Active Directory de Azure.

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:

• Obtener el mail:

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

2.- Obtener un mail en particular: para ello tendremos que tener el Identificador del mail que queremos consultar

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:

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.

• Crear un mail

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:

Sobre este objeto realizaremos la siguiente petición:

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”).

• Actualizar un mail

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:

Con el objeto creado se realiza la siguiente petición:

• Eliminar un mail

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.

• Enviar un mail

Mediante la API se pueden enviar mails de dos formas:

1. Una seleccionando el Identificador del mail

2. La otra opción es indicando el parámetro MessageDisposition=SendAndSaveCopy dentro de la petición de Crear un Mail

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.

• Obtener los grupos de Calendario

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.

• Obtener los Calendarios

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.

• Obtener los elementos de un calendario

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.

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.

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:

Contact REST API

Con la Contact REST API puedes consultar, añadir, modificar y eliminar cualquier contacto.

• Consultar los Contactos

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.

• Crear un Contacto

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.

• Actualizar un Contacto

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.

• Eliminar un Contacto

Para eliminar un contacto, enviamos una petición DELETE para la dirección del contacto.

Ejemplo: Utilizas estas API’s en una aplicación ASP NET. MVC

Requisitos Previos

• Visual Studio 2013
• Descargar Office 365 API Tools bien directamente desde esta dirección http://visualstudiogallery.msdn.microsoft.com/7e947621-ef93-4de7-93d3-d796c43ba34f o directamente desde Nuget.

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:

• Office365ServiceInfo: En esta clase disponemos del modelo que se utiliza para obtener la información para cada una de las APIs, para el caso de Exchange tendremos la siguiente información:

ResourceId = «https://outlook.office365.com/»;

ApiEndpoint = «https://outlook.office365.com/ews/odata»;

AccessToken = Office365CommonController.GetAccessToken(ResourceId);

• Office365CommonControler: Se implementa un controlador común para manejar la autenticación y el control de errores sobre las peticiones al Tenant de Office365. Además disponemos de diversos métodos, como por ejemplo, para obtener el token el usuario que esta logado en este momento e incluso para eliminar esta información del navegador (para evitar que nos puedan robar las credenciales y suplantarnos la identidad)

• ExchangeSampleController: Dentro del controlador de Exchange por un lado tendremos una serie de Clases: Calendario, Contactos, Mail para poder mapear el objeto JSON que nos devuelve la API en Clases .NET y poder mostrarlo en la vista. Por otro lado, dentro de este controlador tendremos tres métodos para obtener el Calendario, el Mail y los Contactos. Estos métodos no son más que peticiones HTTP a la API Rest correspondiente.

• Ficheros de Vistas: En estos ficheros están las vistas RAZOR para representar los datos obtenidos en las distintas peticiones a las API’s de Exchange

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:

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.