Usar o Microsoft Graph Toolkit com o 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 em seu aplicativo. O Microsoft Graph Toolkit está disponível como um conjunto genérico de componentes da Web distribuídos por meio do @microsoft/mgt-components pacote npm.

Este artigo descreve o processo passo a passo de uso do Microsoft Graph Toolkit para criar um aplicativo React e conectá-lo ao Microsoft 365. Depois de concluir as etapas, você terá um aplicativo React que mostra os próximos compromissos do usuário conectado no momento do Microsoft 365.

Pré-requisitos

Para seguir as etapas deste artigo, você precisa de um ambiente de desenvolvimento do Microsoft 365 e de algumas ferramentas. Para obter detalhes, consulte Introdução.

Criar um aplicativo React

Crie um novo aplicativo React executando o comando a seguir. Esse comando cria um novo aplicativo React usando TypeScript, o que ajuda a escrever um código mais robusto e evitar erros de runtime. Se for solicitado a instalar o create-react-app pacote, selecione y para confirmar.

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

Altere o diretório de trabalho para o aplicativo recém-criado.

cd my-m365-app

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

npm i @microsoft/mgt-react@next.mgt-chat @microsoft/mgt-chat@next.mgt-chat @microsoft/mgt-element@next.mgt-chat @microsoft/mgt-msal2-provider@next.mgt-chat

Confirme se você pode executar o aplicativo.

npm start

Você deve ser capaz de abrir seu aplicativo no navegador por meio http://localhost:3000do .

Criar um aplicativo do Microsoft Entra

O Microsoft Graph, a API que você usa para se conectar ao Microsoft 365, é protegida com o OAuth 2.0. Para conectar seu aplicativo ao Microsoft 365, você precisará criar um aplicativo no Microsoft Entra ID e conceder a esse aplicativo permissão para acessar recursos específicos em nome da pessoa que usa seu aplicativo.

Siga as etapas no artigo Criar um aplicativo do Microsoft Entra para criar um novo aplicativo do Microsoft Entra.

Conectar o aplicativo React ao Microsoft 365

Agora que seu aplicativo está registrado no Microsoft Entra ID, você pode conectar o aplicativo React ao Microsoft 365. Primeiro, permita que os usuários entrem no aplicativo usando a conta da Microsoft.

Copie a ID de registro do aplicativo do Microsoft Entra

1. No centro de administração do Microsoft Entra, vá para o registro do aplicativo.
2. Verifique se você está na página Visão geral .
3. Na seção Essentials, copie o valor da propriedade ID do aplicativo (cliente)

Configurar o provedor de autenticação do Microsoft Graph Toolkit

Em seguida, configure o provedor de autenticação que o Microsoft Graph Toolkit deve usar. Nesse caso, usamos MSAL2, que é um bom padrão para a criação de aplicativos autônomos. Se você usar qualquer um dos pontos de extensibilidade no Microsoft 365, como Teams ou SharePoint, use outros provedores.

1. No editor de código, abra o arquivo src/index.tsx e, à lista de importações, adicione:

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

2. Após a última import instrução, inicialize o Microsoft Graph Toolkit com provedor MSAL.

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

Substitua o valor da clientId propriedade pelo valor da Application (client) ID propriedade que você copiou anteriormente na visão geral do registro do aplicativo no centro de administração do Microsoft Entra.

Com essas alterações, o arquivo src/index.tsx se parece com o seguinte.

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';

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

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

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

Adicionar o botão de entrada

Adicione o componente React do Microsoft Graph Toolkit de logon para permitir que os usuários entrem com a conta Microsoft no seu aplicativo.

1. No editor de código, abra o arquivo src/App.tsx e adicione à lista de importações:

   import { Login } from '@microsoft/mgt-react';
   

2. App Na função, substitua o return conteúdo da cláusula pela estrutura básica, incluindo o componente Microsoft Graph Toolkit<Login />:

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

Com essas alterações, o arquivo src/App.tsx terá a seguinte aparência.

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

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

export default App;

Teste a entrada em seu aplicativo

Agora você deve ser capaz de entrar em seu aplicativo com sua conta Microsoft.

1. Voltar para o navegador onde seu aplicativo React está sendo executado. Agora você deve ver um botão Entrar .
2. Ao selecionar o botão Entrar, você é solicitado a entrar com sua conta Microsoft (você pode usar a mesma conta com a qual acessou o portal do Azure).
3. Na primeira vez que você estiver usando este aplicativo Microsoft Entra, você precisa consentir seu uso em sua organização.
4. Depois de entrar, você será redirecionado para seu aplicativo React. Observe que o botão Entrar mudou para mostrar o nome do usuário

Carregar dados do Microsoft 365

O Microsoft Graph Toolkit não apenas simplifica a autenticação no Microsoft 365, mas também carrega seus dados. Neste exemplo, o calendário da pessoa conectada é exibido.

Especifique as permissões necessárias para seu aplicativo

Antes de carregar dados do Microsoft 365, você precisa especificar a lista de escopos de permissão que seu aplicativo deve receber para acessar os dados do usuário. Esses escopos diferem dependendo do tipo de informação que você deseja mostrar. Nesse caso, você precisa de acesso ao calendário de pessoas e acesso básico às informações sobre pessoas que também são exibidas no calendário. Você pode encontrar os escopos exigidos por cada API na documentação da API do Graph Microsoft.

1. No editor de códigos, abra o arquivo src/index.tsx e atualize o código de inicialização do provedor.

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

Mostrar os dados do calendário do usuário após entrar

Em seguida, estenda o aplicativo para mostrar dados do calendário do usuário. Você poderá acessar essas informações somente depois que o usuário estiver conectado. Você precisa acompanhar o estado de entrada do usuário e mostrar os dados de calendário depois que o usuário estiver conectado com sua conta Microsoft.

Acompanhar o estado de entrada do usuário

Você precisa rastrear o estado de login do usuário para usar o useIsSignedIn gancho fornecido por mgt-react.

1. Importe o useIsSignedIn gancho de mgt-react, adicionando-o mgt-react às importações.

   import { Login, useIsSignedIn } from '@microsoft/mgt-react';
   

2. Use o gancho useIsSignedIn para habilitar o acompanhamento do estado de entrada do usuário em seu aplicativo adicionando-o na função App :

     const [ isSignedIn ] = useIsSignedIn();
   

Esse código define uma constante booleana isSignedIn , que você pode usar para determinar se o usuário está atualmente conectado ao seu aplicativo.

Carregar calendário do usuário se o usuário estiver conectado

Agora que você rastreia o estado de entrada do usuário em seu aplicativo, pode mostrar o calendário depois que ele entrar.

1. No editor de código, abra o arquivo src/App.tsx e estenda a instrução component import com o <Agenda /> componente.

   import { useIsSignedIn, Agenda, Login } from '@microsoft/mgt-react';
   

2. Estenda o return conteúdo da cláusula com um componente extra div e o Microsoft Graph Toolkit <Agenda /> que só é renderizado se o usuário estiver conectado.

   <div className="row">
     <div className="column">
       {isSignedIn &&
         <Agenda />}
     </div>
   </div>
   

3. No editor de códigos, abra o arquivo src/App.css e altere todo o conteúdo do arquivo com o código a seguir.

   .row {
     display: flex;
     flex-flow: wrap;
   }
   
   .column {
     flex: 0 0 50%;
   }
   

Com essas alterações, o arquivo src/App.tsx deve ter a seguinte aparência.

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

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

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

export default App;

import { useIsSignedIn, Agenda, Login } from '@microsoft/mgt-react';
import { Chat, NewChat } from '@microsoft/mgt-chat';
import { Chat as GraphChat } from '@microsoft/microsoft-graph-types';
import React, { useState, useEffect, useCallback } from 'react';
import './App.css';

function App() {
  const [isSignedIn] = useIsSignedIn();
  const [chatId, setChatId] = useState<string>();

  const [showNewChat, setShowNewChat] = useState<boolean>(false);
  const onChatCreated = useCallback((chat: GraphChat) => {
    setChatId(chat.id);
    setShowNewChat(false);
  }, []);

  return (
    <div className="App">
      <header>
        <Login />
      </header>
      <div className="row">
        <div className="column">
          {isSignedIn &&
            <Agenda />}
        </div>
        <div className="column">
          {isSignedIn && (
            <>
              <button onClick={() => setShowNewChat(true)}>New Chat</button>
              {showNewChat && (
                <NewChat
                  onChatCreated={onChatCreated}
                  onCancelClicked={() => setShowNewChat(false)}
                  mode="auto"
                />
              )}

              {chatId && <Chat chatId={chatId} />}
            </>
          )}
        </div>
      </div>
    </div>
  );
}

export default App;

Teste mostrando o calendário e os chats de um usuário depois que ele fizer login

Com essas alterações, depois de entrar no aplicativo com sua conta Microsoft, você deverá ver seu calendário.

Próximas etapas

• Veja o que há no Microsoft Graph Toolkit.
• Experimente os componentes do playground.
• Faça uma pergunta no Stack Overflow.
• Relate bugs ou deixe uma solicitação de recurso no GitHub.