Uso del kit de herramientas de Microsoft Graph con React

Artículo
03/26/2023

Microsoft Graph Toolkit es un conjunto de componentes web que simplifican la conexión a Microsoft Graph y le permiten centrarse en la aplicación en su lugar. Microsoft Graph Toolkit está disponible como un conjunto genérico de componentes web distribuidos a través del @microsoft/mgt paquete npm.

Si va a crear aplicaciones con React, puede usar el @microsoft/mgt-react paquete, que encapsula los componentes web del Kit de herramientas de Microsoft Graph en React componentes y facilita el paso de datos complejos.

En este artículo se describe el proceso paso a paso del uso del kit de herramientas de Microsoft Graph para crear una aplicación React y conectarla a Microsoft 365. Después de completar los pasos, tendrá una aplicación React que muestra las próximas citas del usuario que ha iniciado sesión actualmente desde Microsoft 365.

Sugerencia

También puede seguir este tutorial como un paseo interactivo por el código. Para obtener más información, consulte el repositorio de GitHub con el proyecto de inicio.

Requisitos previos

Para seguir los pasos de este artículo, necesitará un entorno de desarrollo de Microsoft 365 y algunas herramientas. Para obtener más información, consulte Introducción.

Creación de una aplicación de React

Cree una nueva aplicación React mediante la ejecución del siguiente comando. Esto creará una nueva aplicación de React con TypeScript, lo que le ayudará a escribir código más sólido y evitar errores en tiempo de ejecución.

npx create-react-app my-m365-app --template typescript --use-npm

Cambie el directorio de trabajo a la aplicación recién creada.

cd my-m365-app

A continuación, instale el mgt-react paquete npm, que contiene los componentes del kit de herramientas de Microsoft Graph React.

npm i @microsoft/mgt-react

Instale también el mgt-msal2-provider paquete y mgt-element npm, que contiene el proveedor de autenticación de MSAL2.

npm i @microsoft/mgt-element @microsoft/mgt-msal2-provider

Confirme que puede ejecutar la aplicación.

npm start

Debería poder abrir la aplicación en el explorador a través de http://localhost:3000.

Crear una aplicación de Azure Active Directory

Microsoft Graph, la API que usa para conectarse a Microsoft 365, está protegida con OAuth 2.0. Para conectar la aplicación a Microsoft 365, deberá crear una aplicación en Azure Active Directory (Azure AD) y conceder a esta aplicación permisos para acceder a recursos específicos en nombre de la persona que usa la aplicación.

Siga los pasos del artículo Creación de una aplicación de Azure Active Directory para crear una nueva aplicación de Azure AD.

Conexión de React aplicación a Microsoft 365

Ahora que ha registrado la aplicación con Azure Active Directory (Azure AD), puede conectar la aplicación React a Microsoft 365. En primer lugar, permitir que los usuarios inicien sesión en la aplicación con su cuenta Microsoft.

Copia del identificador de registro de aplicación de Azure AD

En Azure Portal, vaya al registro de la aplicación.
Compruebe que se encuentra en la página Información general .
En la sección Essentials, copie el valor de la propiedad Application (client) ID

Configuración del proveedor de autenticación de Microsoft Graph Toolkit

A continuación, configure el proveedor de autenticación que debe usar Microsoft Graph Toolkit. En este caso, usará MSAL, que es un buen valor predeterminado para compilar aplicaciones independientes. Si usa cualquiera de los puntos de extensibilidad de Microsoft 365, como Teams o SharePoint, usará otros proveedores.

Nota:

Si actualmente usa el proveedor MSAL y desea actualizar al proveedor de MSAL2, siga los pasos del artículo Proveedor MSAL2 .

En el editor de código, abra el archivo src/index.tsx y, en la lista de importaciones, agregue:

import { Providers } from '@microsoft/mgt-element';
import { Msal2Provider } from '@microsoft/mgt-msal2-provider';

Después de la última import instrucción, inicialice Microsoft Graph Toolkit con el proveedor MSAL.
```
Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID'
});
```
Reemplace el valor de la clientId propiedad por el valor de la Application (client) ID propiedad que copió anteriormente en Azure Portal.

Con estos cambios, el archivo src/index.tsx tendrá un aspecto similar al siguiente.

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import './index.css';
import * as serviceWorker from './serviceWorker';

import { Providers } from '@microsoft/mgt-element';
import { Msal2Provider } from '@microsoft/mgt-msal2-provider';

Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID'
});

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

Agregue el componente De inicio de sesión de Microsoft Graph Toolkit React, que mostrará el botón Iniciar sesión que los usuarios pueden usar para iniciar sesión con su cuenta microsoft en la aplicación.

En el editor de código, abra el archivo src/App.tsx y, a la lista de importaciones, agregue:
```
import { Login } from '@microsoft/mgt-react';
```
En la App función , reemplace el contenido de la return cláusula por la estructura básica, incluido el componente de inicio de sesión del kit de herramientas de Microsoft Graph:
```
<div className="App">
  <header>
    <Login />
  </header>
</div>
```

Con estos cambios, el archivo src/App.tsx tendrá un aspecto similar al siguiente.


import { Login } from '@microsoft/mgt-react';
import React from 'react';
import './App.css';

function App() {
  return (
    <div className="App">
      <header>
        <Login />
      </header>
    </div>
  );
}

export default App;

Prueba del inicio de sesión en la aplicación

Ahora debería poder iniciar sesión en la aplicación con su cuenta Microsoft.

Volver al explorador donde se ejecuta la aplicación de React. Ahora debería ver un botón Iniciar sesión .
Al hacer clic en el botón Iniciar sesión , se le pedirá que inicie sesión con su cuenta Microsoft (puede usar la misma cuenta con la que accedió a Azure Portal).
Dado que es la primera vez que usa esta aplicación de Azure AD, debe dar su consentimiento para su uso en su organización.
Después de iniciar sesión, se le redirigirá a la aplicación de React. Observe que el botón Iniciar sesión ha cambiado para mostrar el nombre del usuario .

Carga de datos desde Microsoft 365

Microsoft Graph Toolkit no solo simplifica la autenticación en Microsoft 365, sino que también carga sus datos. En este ejemplo, mostrará el calendario de la persona que ha iniciado sesión.

Especificar los permisos necesarios para la aplicación

Para poder cargar datos de Microsoft 365, debe especificar la lista de ámbitos de permisos que se deben conceder a la aplicación para acceder a los datos del usuario. Estos ámbitos varían en función del tipo de información que quiera mostrar. En este caso, necesitarás acceso al calendario de las personas, así como acceso básico a información sobre personas que también se muestra en el calendario. Puede encontrar los ámbitos necesarios para cada API en la documentación de Microsoft Graph API.

En el editor de código, abra el archivo src/index.tsx y actualice el código de inicialización del proveedor.

Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID',
  scopes: ['calendars.read', 'user.read', 'openid', 'profile', 'people.read', 'user.readbasic.all']
});

Mostrar los datos del usuario después de iniciar sesión

A continuación, extienda la aplicación para mostrar los datos del calendario del usuario. Solo puede acceder a esta información después de que el usuario haya iniciado sesión. Para ello, deberá realizar un seguimiento del estado de inicio de sesión del usuario y mostrar los datos del calendario una vez que el usuario haya iniciado sesión con su cuenta Microsoft.

Para realizar un seguimiento del estado de inicio de sesión del usuario en la aplicación, usará los React useState y useEffect los enlaces en combinación con los controladores de eventos del proveedor.

En el editor de código, abra el archivo src/App.tsx y extienda la instrucción React import existente.
```
import React, { useState, useEffect } from 'react';
```
Importe los Provider tipos y ProviderState de mgt-element, agregando a las importaciones.
```
import { Providers, ProviderState } from '@microsoft/mgt-element';
```

Agregue una función personalizada denominada useIsSignedIn que permita realizar un seguimiento del estado de inicio de sesión del usuario en la aplicación.

function useIsSignedIn(): [boolean] {
  const [isSignedIn, setIsSignedIn] = useState(false);

  useEffect(() => {
    const updateState = () => {
      const provider = Providers.globalProvider;
      setIsSignedIn(provider && provider.state === ProviderState.SignedIn);
    };

    Providers.onProviderUpdated(updateState);
    updateState();

    return () => {
      Providers.removeProviderUpdatedListener(updateState);
    }
  }, []);

  return [isSignedIn];
}

Esta función hace dos cosas. En primer lugar, al usar el enlace de ReactuseState, se habilita el estado de seguimiento dentro del componente. Cada vez que cambie el estado, React volverá a representar el componente. En segundo lugar, con el enlace de ReactuseEffect, amplía el ciclo de vida del componente mediante el seguimiento de los cambios en el proveedor de Microsoft Graph Toolkit y la actualización del componente si es necesario.

Carga del calendario del usuario si el usuario ha iniciado sesión

Ahora que realiza un seguimiento del estado de inicio de sesión del usuario en la aplicación, puede mostrar su calendario después de iniciar sesión.

En el editor de código, abra el archivo src/App.tsx y extienda la instrucción de componente import con el componente Agenda .
```
import { Agenda, Login } from '@microsoft/mgt-react';
```
A continuación, dentro de la función App , agregue:
```
const [isSignedIn] = useIsSignedIn();
```
Esto define una constante booleana isSignedIn , que puede usar para determinar si el usuario ha iniciado sesión actualmente en la aplicación.
Amplíe el contenido de la return cláusula con un componente adicional div y la agenda del kit de herramientas de Microsoft Graph.
```
<div>
  {isSignedIn &&
    <Agenda />}
</div>
```

Con estos cambios, el archivo src/App.tsx debe tener un aspecto similar al siguiente.

import { Providers, ProviderState } from '@microsoft/mgt-element';
import { Agenda, Login } from '@microsoft/mgt-react';
import React, { useState, useEffect } from 'react';
import './App.css';

function useIsSignedIn(): [boolean] {
  const [isSignedIn, setIsSignedIn] = useState(false);

  useEffect(() => {
    const updateState = () => {
      const provider = Providers.globalProvider;
      setIsSignedIn(provider && provider.state === ProviderState.SignedIn);
    };

    Providers.onProviderUpdated(updateState);
    updateState();

    return () => {
      Providers.removeProviderUpdatedListener(updateState);
    }
  }, []);

  return [isSignedIn];
}

function App() {
  const [isSignedIn] = useIsSignedIn();

  return (
    <div className="App">
      <header>
        <Login />
      </header>
      <div>
        {isSignedIn &&
          <Agenda />}
      </div>
    </div>
  );
}

export default App;

Prueba que muestra el calendario del usuario después de iniciar sesión

Con estos cambios, después de iniciar sesión en la aplicación con su cuenta Microsoft, debería ver el calendario.

Para ver los cambios, cierre el explorador y ábralo de nuevo y vaya a http://localhost:3000. Esto se debe a que ha cambiado el valor de la scopes propiedad, lo que afecta al token de acceso que se solicita desde Azure AD.
Elija el botón Iniciar sesión e inicie sesión con su cuenta Microsoft. Observe las adiciones a la lista de permisos solicitados en la solicitud de consentimiento. Esto se debe a que ha incluido permisos adicionales en la scope propiedad .
Después de dar su consentimiento al uso de la aplicación, debería ver información sobre el usuario actual y su calendario.

Aplicación finalizada

Pasos siguientes

Consulte lo que se encuentra en el Kit de herramientas de Microsoft Graph.
Pruebe los componentes del área de juegos.
Formule una pregunta en Stack Overflow.
Informe de errores o deje una solicitud de característica en GitHub.

Uso del kit de herramientas de Microsoft Graph con React

Requisitos previos

Creación de una aplicación de React

Crear una aplicación de Azure Active Directory

Conexión de React aplicación a Microsoft 365

Copia del identificador de registro de aplicación de Azure AD

Configuración del proveedor de autenticación de Microsoft Graph Toolkit

Prueba del inicio de sesión en la aplicación

Carga de datos desde Microsoft 365

Especificar los permisos necesarios para la aplicación

Mostrar los datos del usuario después de iniciar sesión

Carga del calendario del usuario si el usuario ha iniciado sesión

Prueba que muestra el calendario del usuario después de iniciar sesión

Pasos siguientes

Recursos adicionales

Recursos adicionales

Uso del kit de herramientas de Microsoft Graph con React

Requisitos previos

Creación de una aplicación de React

Crear una aplicación de Azure Active Directory

Conexión de React aplicación a Microsoft 365

Copia del identificador de registro de aplicación de Azure AD

Configuración del proveedor de autenticación de Microsoft Graph Toolkit

Agregar el botón Iniciar sesión

Prueba del inicio de sesión en la aplicación

Carga de datos desde Microsoft 365

Especificar los permisos necesarios para la aplicación

Mostrar los datos del usuario después de iniciar sesión

Seguimiento del estado de inicio de sesión del usuario

Carga del calendario del usuario si el usuario ha iniciado sesión

Prueba que muestra el calendario del usuario después de iniciar sesión

Pasos siguientes

Recursos adicionales

Recursos adicionales