Como cada trimestre, ya está disponible el nuevo número de la revista digital CompartiMOSS. En este número he tenido la oportunidad de participar por partida doble: por un lado, con la publicación de un artículo sobre las nuevas API’s disponibles en Office 365 y, por otro lado, con la realización de una entrevista (algo que me sonroja un poco). Además de mi participación personal, este número es especial por otro motivo: la colaboración que realiza Encamina con CompartiMOSS para albergar la infraestructura de la revista en Azure. Por si estos motivos no fueran suficientes, este número está lleno de artículos de gran calidad, como por ejemplo:
En este post, os dejo el artículo que he escrito para la revista. ¡Espero que os guste!
Tal y como comentamos en el anterior número de CompartiMOSS, estas nuevas API’s de Office 365 tienen como finalidad facilitarnos nuestros desarrollos para la plataforma de productividad de Microsoft en la nube. Y de la misma forma que se ha desarrollado API REST en SharePoint, se van a implementar servicios REST para acercar Office365 a nuestros desarrollos.
Desgranando las API’s de Ficheros SharePoint
La API REST de Ficheros representa un rediseño del almacenamiento de archivos y gestión de ficheros en SharePoint. La API de Archivos permite acceder y manipular tanto el contenido de los documentos de Office como los documentos almacenados en mensajes de correo electrónico, calendario, contactos y datos de SharePoint.
La API de ficheros tiene como principal utilidad establecer una forma simple y sencilla de acceder a los ficheros y carpetas independientemente de la plataforma donde este utilizada. Esta API contiene acciones sobre dos elementos ficheros y carpetas, para facilitar su uso han establecido 3 entidades: FileSystemItem, File y Folder.
La definición de las entidades es la siguiente:
| Nombre | Tipo | Descripción | Creación | Update | Null |
| Id | Guid | Id del Item | No | No | No |
| Etag | String | ETag del item | No | No | No |
| Name | String | Nombre del item | Requerido | Si | No |
| Url | String | Path Absoluto | No | No | No |
| TimeLastModified | Fecha/Hora | Hora de Modificado | No | No | No |
| CreatedBy | Usuario | Usuario | No | No | No |
| TimeCreated | Fecha/Hora | Fecha de Creación | No | No | No |
| LastModifiedBy | Usuario | Usuario que ha modificado | No | No | No |
| Size | Entero | Número de bits del documento | No | No | No |
| Nombre | Tipo | Descripción | Creación | Update | Null |
| Children | Collección de FileSystemItem | Ficheros y carpetas que están incluidas dentro de esta carpeta | No | Si | si |
| ChildrenCount | Entero | Número de ficheros que tiene esa carpeta | No | No | No |
Tenemos las siguientes endpoints disponibles:
| GET ../_api/files |
| GET ../_api/files(<file_path>)/download |
La devolución de esta petición es el propio fichero.
| GET ../_api/files(<file_path>) |
| GET ../_api/files(<file_path>)/<property_name> |
| { ‘__metadata’: { ‘type’:’MS.FileServices.File’ }, Name : ‘<FileName>’ } |
Realizaremos la siguiente petición:
| POST../_api/files |
Para crear un fichero con contenido tendremos que enviar en el cuerpo de la solicitud enviaremos un vector de bits y realizar la siguiente petición:
| POST ../_api/files/Add(string name, boolean overwrite) |
Si ha ido todo de forma correcta la API nos devuelve las propiedades del fichero recién creado.
| DELETE ../_api/files(<file_path>) |
Operaciones con carpetas
Disponemos de las siguientes opciones:
| GET ../_api/files(<folder_path>) |
| GET ../_api/files(<folder_path>)/<property_name> |
| GET ../_api/files(<folder_path)>/SubCarpeta |
| POST../_api/files |
| DELETE ../_api/files(<folder_path>) |
| POST ../_api/files(<file_path>)/MoveTo(<file_path>, overwrite=true) |
| POST ../_api/files(<file_path>)/CopyTo(<file_path>, overwrite=true) |
Nota: Para las opciones Mover un fichero y Copiar un fichero, la biblioteca destino no puede ser distinta que la biblioteca donde está el fichero.
Operaciones en la Consulta
Tanto en las operaciones de ficheros como en las carpetas podemos añadir diversos parámetros en la consulta a realizar como son indicar el número de ítems que nos devuelve la consulta, como establecer el orden en el que se devuelve la petición. Para ello realizaremos las peticiones de la siguiente forma:
| GET ../_api/files?$orderby=<orderbyfield> |
| GET ../_api/files?&top=<row_limit> |
Desgranando la API Graph de AzureActive Directory
La API Graph de Azure Active Directory proporciona acceso programático a Azure AD a través de los extremos de la API de REST. Las aplicaciones pueden usar la API Graph para hacer operaciones de creación, lectura, actualización y eliminación (CRUD) en objetos y datos de directorio. Por ejemplo, la API Graph permite realizar las siguientes operaciones comunes en un objeto de usuario:
Operaciones con usuarios
Para la creación de un usuario realizaremos la siguiente petición POST:
| https://graph.windows.net/mytenantdomain/users?api-version=2013-04-05 |
Donde tendremos que sustituir mytenantdomain por el nombre de nuestro dominio. En esa petición tendremos que enviar en el cuerpo de la solicitud un formato JSON como el siguiente:
| { «accountEnabled»: true, «displayName»: «Adrian Díaz», «mailNickname»: «adiaz», «passwordProfile»: { «password» : «xxxxx», «forceChangePasswordNextLogin»: false }, «userPrincipalName»: «adiaz@encamina.com» } |
| https://graph.windows.net/mytenantdomain/users?api-version=2013-04-05 https://graph.windows.net/mytenantdomain/users/<objectId>?api-version=2013-04-05 https://graph.windows.net/mytenantdomain/users/<userPrincipalName>?api-version=2013-04-05 |
Nota: El URI sin una especificación de usuario devolverá todos los usuarios en el directorio. Para obtener un usuario específico, especifica la propiedad objectId o userPrincipalName del usuario en el URI de solicitud
| PATCH https://graph.windows.net/mytenantdomain/users/<objectId>?api-version=2013-04-05 PATCH https://graph.windows.net/mytenantdomain/users/<userPrincipalName>?api-version=2013-04-05 |
En el cuerpo de la solicitud enviaremos un JSON con las propiedades que deseamos modificar. Por ejemplo para modificar el departamento y la ubicación del usuario seria de la siguiente forma:
| { «department»:»Development», «usageLocation»:»ES» } |
| DELETE https://graph.windows.net/mytenantdomain/users/<objectId>?api-version=2013-04-05 DELETE https://graph.windows.net/mytenantdomain/users/<userPrincipalName>?api-version=2013-04-05 |
Si la operación ha ido correctamente la API REST nos devolverá un código de estado 204 Sin Contenido
| GET https://graph.windows.net/mytenantdomain/users/<objectId||userPrincipalName>/$links/directReports?api-version=2013-04-05 |
Para recuperar las personas que dependen directamente de un contacto, especifica «contacts» como el conjunto de recursos. También puedes especificar «directoryObjects» como el conjunto de recursos en el URI de solicitud; por ejemplo, https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/5e624f44-d38d-4943-b07c-2bad078f52ff/directReports?api-version=2013-04-05. Solo se puede usar objectId cuando el conjunto de recursos es «contacts» o «directoryObjects».
| PATCH https://graph.windows.net/mytenantdomain/users/<objectId>?api-version=2013-04-05 PATCH https://graph.windows.net/mytenantdomain/users/<userPrincipalName>?api-version=2013-04-05 |
Dentro del cuerpo de la solicitud de la petición tendremos que enviar un JSON donde tenga una propiedad «passwordProfile». Esta propiedad debe de tener un valor válido que contiene una contraseña que cumple la directiva de complejidad de contraseñas del inquilino.
| { «passwordProfile»: { «password»:»Test123456″, «forceChangePasswordNextLogin»:false } } |
Nota: En todas las peticiones hay que enviar dentro de la cabecera la Autentificación, que no es más que un token de portador emitido por el Control de acceso de Azure. Este token se genera en cuanto la aplicación que estamos implementando se autentifique contra el Active Directory.
Ejemplo: Utilizar estas API’s en una aplicación Windows 8.1
Requisitos Previos
Manos a la obra
Una vez tenemos instalada las Office 365 API Tools, abrimos Visual Studio, creamos un proyecto Aplicaciones de la Tienda-> Aplicaciones Windows-> Aplicación Vacía. 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 6 servicios: Calendar, Contacts, Mail, My Files, Sites y Users/Groupst. Inicialmente, la columna Permisos a la derecha de cada servicio estará vacía. En nuestro ejemplo vamos a seleccionar primero My Files y posteriormente Users/Groups. 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 carpetas: Common y Office365. Además de una serie de archivos XAML donde están las pantallas para poder comprobar la potencia de estas APIs.
Si analizamos los ficheros que se han añadido:
public static async Task<Office365ServiceInfo> GetActiveDirectoryServiceInfoAsync()
Devuelve información sobre el servicio de Active Directory, incluida su token de acceso. En caso de error, este método se mostrará un mensaje de error al usuario, y devolverá una instancia de Office365ServiceInfo cuya propiedad HasValidAccessToken se establece en «false».
En el caso de SharePoint tendremos el siguiente método:
public static async Task<Office365ServiceInfo> GetSharePointOneDriveServiceInfoAsync()
Este método devuelve información sobre el servicio de SharePoint, incluyendo su token de acceso en caché. Para cada SharePoint, el ID de recurso y la API será diferente para cada inquilino. En caso de error, al igual que en el servicio de Active Directory se muestra un mensaje de error y devolverá una instancia de Office365ServiceInfo instancia cuya propiedad HasValidAccessToken se establece en «false».
Una vez analizado el código, en la página principal de nuestra aplicación (MainPage.xaml) tendremos que añadir la funcionalidad para poder ir a las ventanas que nos ha descargado las herramientas tools de Office 365.
En primer lugar modificaremos el XAML de MainPage.xam añadiendo el siguiente código dentro del GRID que hay por defecto:
| <TextBlock Grid.Row=»0″ x:Name=»pageTitle» Text=»Demo Office 365″ IsHitTestVisible=»false» TextWrapping=»NoWrap» VerticalAlignment=»Bottom» Margin=»50,0,30,40″/> <StackPanel Grid.Row=»1″> <TextBlock TextWrapping=»Wrap» Margin=»30,30,30,50″ FontSize=»20″ HorizontalAlignment=»Center»> APIS Office 365 by CompartIMOSS </TextBlock> <Grid Margin=»30,0,10,30″> <Grid.ColumnDefinitions> <ColumnDefinition Width=»*» /> <ColumnDefinition Width=»*» /> <ColumnDefinition Width=»*» /> </Grid.ColumnDefinitions> <StackPanel Grid.Column=»0″ Margin=»20,20,20,20″> <Button x:Name=»buttonPeople» FontSize=»30″ Click=»ButtonPeople_OnClick»>People</Button> <TextBlock TextWrapping=»Wrap» Margin=»0,30,0,0″ FontSize=»20″ Text=»Obtenermos los contactos del Active Directory.» /> </StackPanel> <StackPanel Grid.Column=»1″ Margin=»20,20,20,20″> <Button x:Name=»buttonDocuments» FontSize=»30″ Click=»ButtonDocuments_OnClick»>Documents</Button> <TextBlock TextWrapping=»Wrap» Margin=»0,30,0,0″ FontSize=»20″ Text=»Obtenemos los ficheros de SharePoint.» /> </StackPanel> </Grid> </StackPanel> |
A continuación implementamos la funcionalidad de los dos botones. La funcionalidad de estos botones es muy simple, navegará a la opción de la API seleccionada.
| private void ButtonPeople_OnClick(object sender, RoutedEventArgs e) { this.Frame.Navigate(typeof(ActiveDirectorySamplePage)); }
private void ButtonDocuments_OnClick(object sender, RoutedEventArgs e) { this.Frame.Navigate(typeof(SharePointSamplePage)); }
|
Una vez añadido estas modificaciones, compilamos y si todo ha ido bien visualizaremos la siguiente pantalla:
Al pulsar sobre cada opción: People o Documents, se mostrarán las distintas vistas añadidas donde visualizamos la información solicitada a la API correspondiente. Una vez pulsamos sobre cualquier opción, en primer lugar, nos pedirá autenticación sobre Office365 para lo cual se muestra una pantalla de login como la siguiente:
Una vez autentificado visualizaremos los datos solicitados a la API correspondiente.
Conclusión
Office 365 es un producto clave dentro de la estrategia que está trazando Satya Nadella para hacer competencia a Google y Apple. Dentro de esta estrategia Microsoft está haciendo especial hincapié en el acceso desde cualquier dispositivo y en la productividad. Y en estos dos puntos estas nuevas API’s tienen gran importancia, primero porque Office 365 es la principal herramienta de productividad y segundo porque están implementando herramientas para poder hacer uso de Office 365 desde cualquier plataforma/dispositivo. Otro de las grandes ventajas que llevan estas API’s es que facilitan entornos híbridos. El poder hacer uso de esta API en nuestros desarrollos pueden facilitar a las empresas a migrar determinados servicios al Cloud.
Referencias:
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 😊)