La nueva API de Office 365 Unificada


Buenas tardes a todos,

Esta semana desde Microsoft se lanzó la noticia de la aparición de una nueva API de Office 365 unificada, que busca facilitar y estandarizar todas las operaciones que se pueden realizar contra los servicios de Office 365 a través de su API, además de añadir nuevas opciones y servicios a la misma. Ayer tuve la oportunidad de echar un vistazo a esta API unificada y me pareció que mejora mucho la versión anterior y particularmente me gusta más esta línea que la que llevaba hasta ahora.

Hoy os voy a contar en qué consisten todas estas mejoras y enseñaros un ejemplo de cómo trabajar con ella que podréis comparar con un ejemplo que publiqué hace un tiempo sobre el uso de la API de Office 365 que hasta ahora teníamos vigente. Esta versión de API unificada está aún en Preview, por lo que aún pueden haber mejoras o modificaciones, no obstante lo que veremos hoy es la filosofía de la misma.

Antes de entrar de lleno os voy a dejar una recopilación de enlaces que creo que son fundamentales para entender la nueva API Unificada.

http://dev.office.com/unifiedAPIs

https://msdn.microsoft.com/office/office365/HowTo/office-365-unified-api-overview#msg_how_learn_unified_api

https://msdn.microsoft.com/en-us/office/office365/howto/get-started-with-office-365-unified-api

https://msdn.microsoft.com/en-us/office/office365/howto/office-365-unified-api-reference

http://www.vrdmn.com/2015/05/using-office-365-unified-api-in-aspnet.html

¿En qué consiste esta API de Office 365 Unificada?

La nueva API de Office 365 Unificada pretende seguir ofreciendo a los desarrolladores la oportunidad de utilizar los servicios de la suite de productividad de Office 365, pero de forma unificada y a través de una API REST, que nos permite hacer todas las operaciones de una forma mucho más sencilla y alineada con el “standard” de las API de servicios web hoy en día.

Además añaden acceso a nuevos servicios dentro de Office 365, quedando ahora el mapa de entidades de la siguiente forma:

O365_unified_API_entities

Con la API tradicional para usar algunas de las entidades disponibles teníamos siempre que realizar las siguientes acciones:

  • Usar el servicio discovery para encontrar los endpoints
  • Determinar la URL de los servicios a los que la app se quería conectar
  • Obtener y manejar el token de cada servicio y hacer la petición a cada uno de ellos directamente

Desde ahora, por medio de esta nueva API unificada, evitaremos estas operaciones para sustituirlas por una simple API REST. Además no es necesario descubrir y navegar a cada uno de los diferentes endpoints para cada servicio ya que todos comparten uno mismo, con lo que comparten también el sistema de autenticación y autorización. Estos nos permite además fácilmente consumir desde cualquier herramienta o lenguaje de programación esta API.

¿Cómo podemos usar la API?

Vamos a ver ahora algunas de las URLs que tenemos disponible en la API REST unificada para acceder a las distintas entidades de Office 365.

La Url de referencia al servicio la tenemos en la siguiente dirección https://graph.microsoft.com/{version}. A partir de aquí, voy a dejar distintos ejemplo de cómo podemos usar esta referencia para acceder a las distintas entidades.

Acceder a One Drive
https://graph.microsoft.com/{version}/me/files
Accediendo al servicio de Exchange OnLine
https://graph.microsoft.com/{version}/me/Messages
Accediendo a los usuarios de mi tenant
https://graph.microsoft.com/{version}/{myOrganization}/users
Accediendo a los grupos de Office 365
https://graph.microsoft.com/{version}/{myOrganization}/groups
Aplicaciones registradas en Azure AD
https://graph.microsoft.com/{version}/{myOrganization}/applications

Obviamente estas son solo algunas de las URLs principales de los servicios. En el enlace a la referencia de la API podemos ver todas las opciones y todas las oportunidades que tenemos disponibles y os animo a que naveguéis por ahí para ver todo lo que se puede hacer, que como veréis es mucho.

Ejemplo de uso de la nueva API de Office 365 Unificada

Para terminar con el artículo, vamos a ver un ejemplo de código de cómo podemos usar en una aplicación MVC esta nueva API REST.

Para poder usar la API REST unificada de Office 365, tenemos en primer lugar que registrar nuestra App en Azure Active Directory tal y como se comentaba en la entrada que os enlazo a continuación:

Registrando una aplicación en Azure Active Directory

Lo único que tenemos que hacer diferente a cuando íbamos a usar la versión anterior es a la hora de establecer los permisos para la app que estamos registrando. En esta ocasión deberemos añadir los permisos para la nueva API unificada, como se ve en la imagen siguiente, tenemos esta opción disponible.

unifiedAPI

Una vez que ya hemos registrado adecuadamente nuestra app, podemos pasar al código de la aplicación. En la demo que vamos a ver, voy a leer los archivos y directorios de mi One Drive, tal y como hice en el ejemplo con la API anterior. He creado una aplicación MVC y todo el código por simplicidad en el ejemplo, lo he puesto en la misma acción del controlador, aunque si accedéis al último enlace de los que indiqué arriba, podréis ver como se podría organizar el código a través de varias acciones en una aplicación MVC. Vamos a ver el código y luego lo explicaré destacando los puntos más importantes del mismo:

public async Task<ActionResult> Files(string  code)
{
       string authCode = Request.Params["code"];

       // The url in our app that Azure should redirect to after successful signin
       string redirectUri = Url.Action("Files", "Home", null, Request.Url.Scheme);

       var authContext = new AuthenticationContext("https://login.microsoftonline.com/common");

       if(authCode == null)
       {

           // Generate the parameterized URL for Azure signin
           Uri authUri = authContext.GetAuthorizationRequestURL("https://graph.microsoft.com/", ConfigurationManager.AppSettings["ida:ClientID"],
               new Uri(redirectUri), UserIdentifier.AnyUser, null);

           // Redirect the browser to the Azure signin page
           return Redirect(authUri.ToString());
       }

       ClientCredential creds = new ClientCredential(
           ConfigurationManager.AppSettings["ida:ClientID"],
           ConfigurationManager.AppSettings["ida:Password"]);

       // Get the token
       var authResult = await authContext.AcquireTokenByAuthorizationCodeAsync(
           authCode, new Uri(redirectUri), creds, "https://graph.microsoft.com/");

       // Save the token
       string accesstoken = authResult.AccessToken;

       // Make request
       using (var client = new HttpClient())
       {
           string endpointUri, resourceId;

           using (var request = new HttpRequestMessage(HttpMethod.Get,
             "https://graph.microsoft.com/beta/me/files"))
           {
               request.Headers.Add("Authorization", "Bearer " + accesstoken);

               using (var response = await client.SendAsync(request))
               {
                   List<OneDriveFile> modelList = new List<OneDriveFile>();

                   var content = await response.Content.ReadAsStringAsync();
                   foreach (var item in JObject.Parse(content)["value"])
                   {
                       OneDriveFile newFile = new OneDriveFile
                       {
                          Name = item["name"].ToString(),
                          Size = double.Parse(item["size"].ToString())
                       };

                       modelList.Add(newFile);
                   }

                   ViewBag.files = modelList;

                }
            }
       }

       return View();
}

Vamos a destacar tres aspectos fundamentales de este código:

  • Lo primero que haremos en nuestro código es comprobar si nos hemos autenticado contra Azure Directory, tal y como hacíamos con la API tradicional, y en el caso de que no lo esté nos redirigirá a la página correspondiente para autenticarnos, para todo el proceso de autenticación y autorización se va a usar como hacíamos anteriormente la librería ADAL que tenemos en Nuget. (Líneas 10 a 19)
  • El siguiente paso, es capturar el token de acceso para obtener autorización al hacer las peticiones REST. (Líneas 26 a 30)
  • En el último paso usaremos un cliente Http que nos proporciona C# para hacer llamadas a la API y procesar las respuestas. (Líneas 33 a 62)

Las diferencias con respecto al uso de la versión anterior de la API para Office 365 basada en el servicio discovery la podemos ver con la entrada que publiqué sobre este tema. Nos obstante son obvias, por la facilidad con la que ahora podemos acceder a la API de Office, sin tener que hacer todos los pasos para simplemente acceder al servicio que eran necesarios. Esta es la entrada que os comentaba.

Usando la API de Office 365

Y nada más por hoy, como siempre espero que os resulte interesante, a mi esta nueva versión unificada me ha gustado mucho. Os recomiendo echar un vistazo por todos los enlaces que os he comentado, y ver las oportunidades que nos ofrece esta API, como dije al principio me parecen muy interesantes.

Un saludo a todos.

Anuncios

3 comentarios en “La nueva API de Office 365 Unificada

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s