Un vistazo a Microsoft Graph Toolkit - Web Components con Graph

En muchos proyectos nos piden funcionalidades como mostrar las tareas de Planner del usuario, o la agenda del usuario, y para ello utilizamos Microsoft Graph. Para facilitar el acceso a estas informaciones, Microsoft ha creado una serie de componentes que podemos utilizar en nuestras aplicaciones web y que de una forma muy sencilla permite implementar estas funcionalidades.

Lo bueno que tiene Microsoft Graph Toolkit es que lo podemos utilizar en aplicaciones web modernas, WebParts de SharePoint Framework (SPFx), tabs de Teams, etc. Y utilizando cualquier framework, ReactJS, Angular, etc.

¿Cómo empiezo a trabajar con Microsoft Graph Toolkit?

Tenemos 2 formas para poder utilizar Microsoft Graph Toolkit en nuestros desarrollos:

• Cargándolo directamente en nuestra aplicación referenciando un fichero JavaScript:

1<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
2

• Mediante NPM, por lo que lo primero sería agregar el paquete NPM con:

1npm install @microsoft/mgt
2

y luego ya podríamos referenciarlo:

1<script src="node_modules/@microsoft/mgt/dist/es6/components.js"></script>
2

Componentes

• Inicio de sesión: Este componente facilita la autenticación del usuario. Tiene 2 estados:
  • Si el usuario no ha iniciado sesión, el control es un botón sencillo para iniciar el proceso de inicio de sesión.
  • Si el usuario ha iniciado sesión, el control muestra el nombre de usuario de la sesión actual, la imagen de perfil y el correo electrónico. Cuando se hace clic en él, se abre un control flotante con un comando para cerrar la sesión.

Para utilizarlo lo único que debemos hacer es incrustarlo en nuestro html:

1<mgt-login></mgt-login>
2

Si no nos hemos autenticado, nos mostrará el botón para autenticarnos y una vez autenticado, nos mostrará nuestro nombre y nuestra imagen donde podemos pulsar donde nos mostrará nuestro email y un enlace para cerrar la sesión.​

Este componente tiene los siguientes eventos que podemos capturar:

• Contacto: Este componente se utiliza para mostrar datos de una persona. Para poder elegir el contacto que queremos mostrar tenemos 3 opciones distintas

Por ejemplo, si queremos mostrar los datos del usuario que se ha validado utilizaremos:

1<mgt-person person-query="me" show-name show-email></mgt-person>
2

Y nos mostrará los datos del usuario autenticado:

También tiene una serie de propiedades con las que podemos indicar si queremos mostrar el nombre y/o el mail del contacto.

En la siguiente tabla vemos las llamadas que realiza a la API de Graph y los permisos que necesita para funcionar:

• Contactos: Este componente se utiliza para mostrar datos de un grupo de personas. Este componente por defecto muestra los contactos frecuentes del usuario, es decir, realiza la llamada /me/people a la API de Graph, por ejemplo, si añadimos:

1<mgt-people></mgt-people>​
2

Nos mostrará nuestros contactos recientes:

Este control lo podemos personalizar con las siguientes propiedades:

En la siguiente tabla vemos las llamadas que realiza a la API de Graph y los permisos que necesita para funcionar:

• Agenda: Este componente representa los eventos en un calendario de usuario o grupo. De forma predeterminada, el calendario muestra los eventos del usuario que ha iniciado sesión para el día actual, pero se puede modificar para mostrar los datos de otro endpoint que devuelva eventos, por ejemplo, /groups/{id}/calendar/calendarView

Este control lo podemos personalizar con las siguientes propiedades:

En la siguiente tabla vemos las llamadas que realiza a la API de Graph y los permisos que necesita para funcionar:

• Tareas: Con este control podemos visualizar, añadir, editar y eliminar las tareas que tengamos en Planner o Microsoft ToDo, dependiendo del datasource que le indiquemos. Para utilizarlo tendremos que añadir

1<mgt-tasks></mgt-tasks>
2

Y nos mostrará las tareas que tengamos asignadas, por defecto, nos mostrará las que tengamos asignadas en Planner:

Este control lo podemos personalizar con las siguientes propiedades:

En la siguiente tabla vemos las llamadas que realiza a la API de Graph y los permisos que necesita para funcionar

Proveedores

Para poder realizar las llamadas a Microsoft Graph necesitamos un token de acceso. Microsoft Graph Toolkit proporciona una serie de proveedores que facilitan la adquisición del token necesario para realizar las estas llamadas a Microsoft Graph.

Para que los componentes usen un proveedor, se debe establecer la propiedad Providers.globalProvider con el proveedor que necesitamos. Debemos tener en cuenta que todos los componentes que incluyamos utilizarán ese proveedor.

Actualmente existen los siguientes proveedores:

• MsalProvider: Este proveedor utiliza msal.js para obtener el token de acceso, por ejemplo, podemos utilizar este proveedor si estamos desarrollando una aplicación SPA. Cuando utilizamos este proveedor lo primero que tenemos que hacer es registrar nuestra aplicación dentro de Azure AD. En este enlace explican cómo hacerlo https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

Una vez registrada nuestra aplicación debemos inicializar el proveedor, para esto tenemos 2 opciones:

• ​Inicializando desde HTML usando el componente mgt-msal-provider y estableciendo el clientID que obtenemos después de registrar nuestra aplicación en Azure AD. Por ejemplo:​

1<mgt-msal-provider client-id=" <YOUR_CLIENT_ID> "></mgt-msal-provider>
2

• Iniciando desde JavaScript/Typescript de la siguiente manera:

1import {Providers, MsalProvider} from '@microsoft/mgt'import {UserAgentApplication} from "msal";Providers.globalProvider = new MsalProvider(config: MsalConfig);
2

Donde MsalConfig es:

1interface MsalConfig {  clientId: string;  scopes?: string[];  authority?: string;  loginType?: LoginType;  options?: Configuration; }
2

• SharePointProvider: Utilizaremos este proveedor si lo que estamos desarrollando es un WebPart de SharePoint. Para utilizarlo debemos inicializar el proveedor dentro del método onInit.

1import {Providers, SharePointProvider} from '@microsoft/mgt';protected async onInit() {    Providers.globalProvider = new SharePointProvider(this.context);
2

Una vez inicializado podemos añadir nuestro componente en el método render. Debemos tener en cuenta que Microsoft Graph Toolkit requiere Typescript 3.x, por lo que necesitamos estar utilizando como mínimo, la versión 1.8 de SPFx donde se añadió soporte a esta versión de Typescript (https://github.com/SharePoint/sp-dev-docs/wiki/SharePoint-Framework-v1.8-release-notes#support-for-typescript-27-29-and-3x )

• TeamsProvider: Utilizaremos este proveedor si estamos desarrollando una pestaña para Teams. Para utilizarlo lo primero que tenemos que hacer es asegurarnos que tenemos referenciado el SDK de Teams y luego inicializamos el proveedor.​

1<script src="https://unpkg.com/@microsoft/teams-js/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script><script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script><mgt-teams-provider   client-id="<YOUR_CLIENT_ID>"  auth-popup-url="https://<YOUR-DOMAIN>.com/AUTH-PATH"></mgt-teams-provider>
2

También podemos utilizarlo mediante paquetes NPM, para ello necesitamos instalar los paquetes de Microsoft Graph Toolkit y el SDK de Teams.

1npm install @microsoft/mgt @microsoft/teams-js
2

Una vez instalado podremos inicializarlo de la siguiente manera:

1import '@microsoft/teams-js';import {Providers, TeamsProvider} from '@microsoft/mgt'; Providers.globalProvider = new TeamsProvider(config);
2

Donde config es:

1export interface TeamsConfig {  clientId: string;  authPopupUrl: string;  scopes?: string[];  msalOptions?: Configuration;}
2

• Próximamente estará disponible un proveedor para complementos de Office.
• También podemos crear nuestro proveedor personalizado si necesitamos algo más específico. Podemos crearlo de 2 formas:
  • Creando un SimpleProvider que obtenga el token de acceso.
  • Ampliando la clase abstracta IProvider.

Cambiando el estilo

Cada componente posee sus propias propiedades CSS personalizadas que podemos modificar, por ejemplo, para el componente mgt-people podemos modificar las siguientes propiedades.

1mgt-people {  --list-margin: 8px 4px 8px; /* Margin for component */  --avatar-margin: 0 4px 0 0; /* Margin for each person */}
2

Si necesitamos más personalización en los componentes tendremos que hacer plantillas.

Plantillas

Para todos los componentes podemos utilizar plantillas personalizadas para modificar la forma de mostrar la información. Para hacerlo lo que tendremos que hacer es añadir el elemento <template> dentro del componente que queremos modificar. Por ejemplo, para modificar la plantilla en el componente mgt-agenda lo haríamos de la siguiente manera:

1<mgt-agenda>      <template data-type="event">        <div>{{event.subject}}</div>        <div data-for='attendee in event.attendees'>          <mgt-person person-query="{{attendee.emailAddress.name}}">            <template>              <div data-if="person.image">                <img src="{{person.image}}" />              </div>              <div data-else>                {{person.displayName}}              </div>            </template>          </mgt-person>        </div>      </template>    </mgt-agenda>​
2

Cuando creamos plantillas tenemos que tener en cuenta varias cosas:

• Debemos usar llaves dobles ({{expression}}) para expandir una expresión.
• Podemos usar los atributos data-if y data-else y para la representación condicional.
• Podemos usar el atributo data-for para repetir un elemento.
• Podemos usar el atributo data-type para especificar la parte del componente a la que se va a plantilla. Si no se especifica el tipo, la plantilla se aplicará a todo el componente.

Conclusión

Microsoft Graph Toolkit nos proporciona una serie de elementos web reutilizables que podemos utilizar en nuestros desarrollos en distintos escenarios bastante comunes cuando trabajamos con Microsoft Graph. Además, podemos utilizarlo en cualquier framework que estemos utilizando.

Debemos tener en cuenta que es una versión preview y que no es aconsejable que se utilice en entorno de producción. Recientemente se ha liberado la versión 0.2.0, incluyendo un control PeoplePicker y solucionando algunos errores.

Si quieres más información puedes ver la documentación oficial en https://docs.microsoft.com/es-es/graph/toolkit/overview y en el proyecto de GitHub https://github.com/microsoftgraph/microsoft-graph-toolkit

Rubén Ramos Mateo
Technical Architect en Ricoh
ruben_rm@outlook.com
@rubenr79
https://rubenrm.com