Usar o Kit de Ferramentas do Microsoft Graph com o ReactUse the Microsoft Graph Toolkit with React

O Microsoft Graph Toolkit é um conjunto de componentes da Web que simplificam a conexão com o Microsoft Graph e permitem que você se concentre no seu aplicativo.Microsoft Graph Toolkit is a set of web components that simplify connecting to Microsoft Graph and allow you to focus on your application instead. O Microsoft Graph Toolkit está disponível como um conjunto genérico de componentes web distribuídos por meio do @microsoft/mgt pacote npm.Microsoft Graph Toolkit is available as a generic set of web components distributed through the @microsoft/mgt npm package.

Se você estiver criando aplicativos com @microsoft/mgt-react o React, poderá usar o pacote, que envolve os componentes web do Microsoft Graph Toolkit em componentes do React e facilita a passagem de dados complexos.If you're building apps with React, you can use the @microsoft/mgt-react package, which wraps Microsoft Graph Toolkit web components in React components and makes it easier to pass complex data.

Este artigo descreve o processo passo a passo de usar o Kit de Ferramentas do Microsoft Graph para criar um aplicativo React e conectá-lo ao Microsoft 365.This article describes the step-by-step process of using the Microsoft Graph Toolkit to create a React app and connect it to Microsoft 365. Depois de concluir as etapas, você terá um aplicativo React que mostra os próximos compromissos do usuário atualmente assinado do Microsoft 365.After completing the steps, you'll have a React app that shows the upcoming appointments of the currently signed in user from Microsoft 365.

Pré-requisitosPrerequisites

Para seguir as etapas deste artigo, você precisará de um ambiente de desenvolvimento do Microsoft 365 e algumas ferramentas.To follow the steps in this article, you'll need a Microsoft 365 development environment and a few tools. Para obter detalhes, veja como começar.For details, see getting started.

Criar um aplicativo ReactCreate a React app

Crie um novo aplicativo React executando o seguinte comando.Create a new React app by running the following command. Isso criará um novo aplicativo React usando TypeScript, que ajudará você a escrever código mais robusto e evitar erros de tempo de execução.This will create a new React app using TypeScript, which will help you write more robust code and avoid runtime errors.

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

Altere o diretório de trabalho para o aplicativo recém-criado.Change the working directory to the newly created app.

cd my-m365-app

Em seguida, instale o mgt-react pacote npm, que contém os componentes do React do Kit de Ferramentas do Microsoft Graph.Next, install the mgt-react npm package, which contains the Microsoft Graph Toolkit React components.

npm i @microsoft/mgt-react

Instale também mgt-msal-provider mgt-element o pacote npm, que contém o provedor de auth MSAL.Install the mgt-msal-provider and mgt-element npm package as well, which contains the MSAL auth provider.

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

Confirme se você pode executar o aplicativo.Confirm that you can run the app.

npm start

Você deve ser capaz de abrir seu aplicativo no navegador via http://localhost:3000 .You should be able to open your app in the browser via http://localhost:3000.

Criar um aplicativo no Azure Active DirectoryCreate an Azure Active Directory app

O Microsoft Graph, a API que você usa para se conectar ao Microsoft 365, é protegido com o OAuth 2.0.Microsoft Graph, the API that you use to connect to Microsoft 365, is secured with OAuth 2.0. Para conectar seu aplicativo ao Microsoft 365, você precisará criar um aplicativo no Azure Active Directory (Azure AD) e conceder permissões a esse aplicativo para acessar recursos específicos em nome da pessoa que está usando seu aplicativo.In order to connect your app to Microsoft 365, you will need to create an app in Azure Active Directory (Azure AD) and grant this app permissions to access specific resources on behalf of the person using your app.

Siga as etapas no artigo Criar um aplicativo do Azure Active Directory para criar um novo aplicativo do Azure AD.Follow the steps in the Create an Azure Active Directory app article to create a new Azure AD app.

Conectar o aplicativo React ao Microsoft 365Connect React app to Microsoft 365

Agora que você registrou seu aplicativo no Azure Active Directory (Azure AD), poderá conectar o aplicativo React ao Microsoft 365.Now that you have registered your application with Azure Active Directory (Azure AD), you can connect the React app to Microsoft 365. Primeiro, permita que os usuários se inscrevam no aplicativo usando a conta da Microsoft.First, allow users to sign in to the app using their Microsoft account.

Copiar a ID de registro do aplicativo Azure ADCopy the Azure AD application registration ID

  1. No Portal do Azure, vá para o registro do seu aplicativo.In the Azure Portal, go to your application registration.
  2. Verifique se você está na página Visão Geral.Verify that you are on the Overview page.
  3. Na seção Essentials, copie o valor da propriedade de ID do aplicativo (cliente)From the Essentials section, copy the value of the Application (client) ID property

Configurar o provedor de autenticação do Microsoft Graph ToolkitConfigure the Microsoft Graph Toolkit authentication provider

Em seguida, configure o provedor de autenticação que o Microsoft Graph Toolkit deve usar.Next, configure the authentication provider that the Microsoft Graph Toolkit should use. Nesse caso, você usará a MSAL, que é um bom padrão para a criação de aplicativos autônomos.In this case, you'll use MSAL, which is a good default for building standalone applications. Se você usar qualquer um dos pontos de extensibilidade no Microsoft 365, como o Teams ou o SharePoint, você usará outros provedores.If you use any of the extensibility points in Microsoft 365, like Teams or SharePoint, you will use other providers.

  1. No editor de código, abra o src/index.In the code editor, open the src/index. e na lista de importações, adicione:file, and to the list of imports, add:

    import { Providers } from '@microsoft/mgt-element';
    import { MsalProvider } from '@microsoft/mgt-msal-provider';
    
  2. Após a última import instrução, inicialize o Microsoft Graph Toolkit com o provedor MSAL.After the last import statement, initialize the Microsoft Graph Toolkit with MSAL provider.

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

    Substitua o valor da clientId propriedade pelo valor da propriedade que você Application (client) ID copiou anteriormente no Portal do Azure.Replace the value of the clientId property with the value of the Application (client) ID property you copied previously in the Azure Portal.

Com essas alterações, o arquivo src/index.tsx terá a seguinte aparência.With these changes, the src/index.tsx file will look like the following.

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 { MsalProvider } from '@microsoft/mgt-msal-provider';

Providers.globalProvider = new MsalProvider({
  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();

Adicionar o botão EntrarAdd the Sign in button

Adicione o componente React do Kit de Ferramentas do Microsoft Graph de logon, que exibirá o botão Entrar que as pessoas podem usar para entrar com a conta da Microsoft em seu aplicativo.Add the Login Microsoft Graph Toolkit React component, which will display the Sign in button people can use to sign in with their Microsoft account to your app.

  1. No editor de código, abra o arquivo src/App.tsx e adicione à lista de importações:In the code editor, open the src/App.tsx file, and to the list of imports add:

    import { Login } from '@microsoft/mgt-react';
    
  2. Na função, substitua o conteúdo da cláusula pela estrutura básica, incluindo o componente logon do Kit de Ferramentas App return do Microsoft Graph:In the App function, replace the contents of the return clause with the basic structure including the Microsoft Graph Toolkit Login component:

    <div className="App">
      <header>
        <Login />
      </header>
    </div>
    

Com essas alterações, o arquivo src/App.tsx terá a seguinte aparência.With these changes, the src/App.tsx file will look like the following.


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;

Testar a assinatura em seu aplicativoTest signing in to your application

Agora você poderá entrar em seu aplicativo com sua conta da Microsoft.You should now be able to sign in to your application with your Microsoft account.

  1. Volte para o navegador em que seu aplicativo React está sendo executado.Go back to the browser where your React app is running. Agora você deve ver um botão Entrar.You should now see a Sign in button.
  2. Ao clicar no botão Entrar, você será solicitado a entrar com sua conta da Microsoft (você pode usar a mesma conta que a que acessou o Portal do Azure).When you click the Sign in button, you will be prompted to sign in with your Microsoft account (you can use the same account as the one you accessed the Azure Portal with).
  3. Como esta é a primeira vez que você está usando esse aplicativo Azure AD, precisa consentir seu uso em sua organização.Because this is the first time you're using this Azure AD application, you need to consent its use in your organization.
  4. Depois de entrar, você será redirecionado para seu aplicativo React.After signing in, you will be redirected to your React app. Observe que o botão Entrar foi alterado para mostrar o nome do aplicativo React do usuário mostrando as informações do usuário recuperadas do  Microsoft 365 usando o Microsoft Graph Toolkit.Notice that the Sign in button changed to show your user's name React app showing user info retrieved from Microsoft 365 using Microsoft Graph Toolkit.

Carregar dados do Microsoft 365Load data from Microsoft 365

O Microsoft Graph Toolkit não apenas simplifica a autenticação para o Microsoft 365, mas também carrega seus dados.Microsoft Graph Toolkit not only simplifies authentication to Microsoft 365, but also loading its data. Neste exemplo, você mostrará o calendário da pessoa.In this example, you'll show the signed in person's calendar.

Especificar permissões necessárias para seu aplicativoSpecify permissions needed for your application

Antes de carregar dados do Microsoft 365, você precisa especificar a lista de escopos de permissão que seu aplicativo deve ter para acessar os dados do usuário.Before you can load data from Microsoft 365, you need to specify the list of permission scopes your application must be granted to access user's data. Esses escopos diferem dependendo do tipo de informação que você deseja mostrar.These scopes differ depending on what kind of information you want to show. Nesse caso, você precisará de acesso ao calendário das pessoas, bem como acesso básico a informações sobre as pessoas que também são exibidas no calendário.In this case, you will need access to people's calendar as well as basic access to information about people that is also displayed in the calendar. Você pode encontrar os escopos exigidos por cada API na documentação da API do Microsoft Graph.You can find the scopes required by each API in the Microsoft Graph API documentation.

  1. No editor de código, abra o arquivo src/index.tsx e atualize o código de inicialização do provedor.In the code editor, open the src/index.tsx file, and update the provider initialization code.

    Providers.globalProvider = new MsalProvider({
      clientId: 'd7cb93c9-9097-4e38-8f06-7c0088ac3318',
      scopes: ['calendars.read', 'user.read', 'openid', 'profile', 'people.read', 'user.readbasic.all']
    });
    

Mostrar dados do usuário após entrarShow user's data after signing in

Em seguida, estenda o aplicativo para mostrar dados do calendário do usuário.Next, extend the application to show data from the user's calendar. Você só poderá acessar essas informações depois que o usuário entrar.You can access this information only after the user has signed in. Para fazer isso, você precisará controlar o estado de login do usuário e mostrar os dados do calendário depois que o usuário entrar com a conta da Microsoft.To do this, you will need to track the user's sign in state and show the calendar data after the user has signed in with their Microsoft account.

Acompanhar o estado de login do usuárioTrack user's sign in state

Para controlar o estado de login do usuário em seu aplicativo, você usará o React e os ganchos em combinação com manipuladores de useState useEffect eventos do provedor.To track the user's sign in state in your application, you will use the React useState and useEffect hooks in combination with provider event handlers.

  1. No editor de código, abra o arquivo src/App.tsx e estenda a instrução React import existente.In the code editor, open the src/App.tsx file and extend the existing React import statement.

    import React, { useState, useEffect } from 'react';
    
  2. Importe o Provider e os tipos de , ProviderState mgt-element adicionando às importações.Import the Provider and ProviderState types from mgt-element, by adding to imports.

    import { Providers, ProviderState } from '@microsoft/mgt-element';
    
  3. Adicione uma função personalizada chamada que permite rastrear o estado de login do useIsSignedIn usuário em seu aplicativo.Add a custom function named useIsSignedIn that enables tracking the user's sign in state in your application.

    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 função faz duas coisas.This function does two things. Primeiro, usando o useState gancho do React, ele habilita o estado de rastreamento dentro do componente.First, using the React useState hook, it enables tracking state inside your component. Sempre que o estado mudar, o React renderizará o componente.Whenever the state changes, React will re-render your component. Em segundo lugar, usando o gancho react, ele estende o ciclo de vida do componente rastreando as alterações no provedor do Microsoft Graph Toolkit e atualizando o useEffect componente, se necessário.Second, using the React useEffect hook, it extends the component's lifecycle by tracking changes in the Microsoft Graph Toolkit provider and updating the component if necessary.

Carregar o calendário do usuário se o usuário estiver se inscreveuLoad user's calendar if user is signed in

Agora que você rastreia o estado de login do usuário em seu aplicativo, pode mostrar o calendário depois de entrar.Now that you track the user's sign in state in your application, you can show their calendar after they signed in.

  1. No editor de código, abra o arquivo src/App.tsx e, dentro da função App, adicione:In the code editor, open the src/App.tsx file, and inside the App function, add:

    const [isSignedIn] = useIsSignedIn();
    

    Isso define uma constante Boolean, que você pode usar para determinar se o usuário está isSignedIn atualmente londo em seu aplicativo.This defines a Boolean isSignedIn constant, which you can use to determine whether the user is currently signed in to your application.

  2. Estenda o conteúdo da cláusula com um componente adicional e o componente agenda do Kit de Ferramentas return div do Microsoft Graph.Extend the contents of the return clause with an additional div and the Microsoft Graph Toolkit Agenda component.

    <div>
      {isSignedIn &&
        <Agenda />}
    </div>
    

Com essas alterações, o arquivo src/App.tsx deve se parecer com o seguinte.With these changes, the src/App.tsx file should look like the following.

import { Providers, ProviderState } from '@microsoft/mgt';
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;

Teste mostrando o calendário do usuário depois que ele se inscreveuTest showing user's calendar after they signed in

Com essas alterações, depois de entrar em seu aplicativo com sua conta da Microsoft, você deverá ver seu calendário.With these changes, after signing in to your application with your Microsoft account, you should see your calendar.

  1. Para ver as alterações, feche o navegador e abra-o novamente e vá para http://localhost:3000 .To see the changes, close the browser and open it again, and go to http://localhost:3000. Você faz isso porque alterou o valor da propriedade, o que afeta o token de acesso que você scopes solicita do Azure AD.You do this because you changed the value of the scopes property, which affects the access token that you request from Azure AD.
  2. Escolha o botão Entrar e entre usando sua conta da Microsoft.Choose the Sign In button and sign in using your Microsoft account. Observe as adições à lista de permissões solicitadas na solicitação de consentimento.Notice the additions to the list of permissions requested in the consent prompt. Isso porque você incluiu permissões adicionais na scope propriedade.This is because you included additional permissions in the scope property.
  3. Depois de consentir o uso do aplicativo, você deverá ver informações sobre o usuário atual e seu calendário.After consenting to the use of the application, you should see information about the current user and their calendar.

Aplicativo concluído

Próximas etapasNext steps