Use o Kit de Ferramentas do Microsoft Graph com React

Artigo
04/01/2024

O Microsoft Graph Toolkit é um conjunto de componentes da Web que simplifica a conexão com o Microsoft Graph e permite que você se concentre em seu aplicativo. O Microsoft Graph Toolkit está disponível como um conjunto genérico de componentes web distribuídos por meio do @microsoft/mgt-components pacote npm.

Se você estiver criando aplicativos com React, poderá usar o @microsoft/mgt-react pacote, que envolve componentes Web do Microsoft Graph Toolkit em React componentes e facilita a passagem de dados complexos. Para usar os mgt-chat componentes e mgt-new-chat , instale o pacote separado @microsoft/mgt-chat .

Este artigo descreve o processo passo a passo de usar o 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 atualmente do Microsoft 365.

Dica

Você também pode seguir este tutorial como um tour de código interativo. Para obter detalhes, confira o repositório GitHub com o projeto inicial.

Dica

Você também pode baixar um modelo inicial para iniciar sua jornada. Este modelo garantirá o conjunto certo de dependências, etc. Para continuar, baixe o projeto inicial do GitHub para mgt-react. Siga as instruções README e continue com dados de carregamento do Microsoft 365

Dica

Você também pode baixar um modelo inicial para iniciar sua jornada. Este modelo garantirá o conjunto certo de dependências, etc. Para continuar, baixe o projeto inicial do GitHub para mgt-react e mgt-chat. Siga as instruções README e continue com dados de carregamento do Microsoft 365

Pré-requisitos

Para seguir as etapas deste artigo, você precisa de um ambiente de desenvolvimento do Microsoft 365 e algumas ferramentas. Para obter detalhes, confira 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 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

Em seguida, instale os mgt-reactpacotes , mgt-element e mgt-msal2-provider npm, que contêm os componentes do Microsoft Graph Toolkit React, os principais recursos do Kit de Ferramentas e o provedor de autenticação MSAL2.

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

Em seguida, instale os mgt-reactpacotes , mgt-chatmgt-element e mgt-msal2-provider npm, que contêm os componentes do Microsoft Graph Toolkit React, os principais recursos do Kit de Ferramentas e o provedor de autenticação MSAL2.

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 de http://localhost:3000.

Criar um aplicativo Microsoft Entra

O Microsoft Graph, a API que você usa para se conectar ao Microsoft 365, está protegido 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 Microsoft Entra para criar um novo aplicativo Microsoft Entra.

Conectar React aplicativo ao Microsoft 365

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

Copiar a ID de registro do aplicativo Microsoft Entra

No centro de administração do Microsoft Entra, acesse o registro do aplicativo.
Verifique se você está na página Visão geral .
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 Kit de Ferramentas do Microsoft Graph deve usar. Nesse caso, usamos o MSAL2, que é um bom padrão para criar aplicativos autônomos. Se você usar qualquer um dos pontos de extensibilidade no Microsoft 365, como Teams ou SharePoint, use outros provedores.

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

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

Após a última import instrução, inicialize o Kit de Ferramentas do Microsoft Graph com o provedor MSAL.
```
Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID'
});
```

Substitua o valor da clientId propriedade pelo valor da Application (client) ID propriedade copiada anteriormente na visão geral de registro do aplicativo 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();

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

No editor de código, abra o arquivo src/App.tsx e, na lista de importações, adicione:
```
import { Login } from '@microsoft/mgt-react';
```
App Na função, substitua o conteúdo da return cláusula pela estrutura básica, incluindo o componente do Kit de Ferramentas <Login /> do Microsoft Graph:
```
<div className="app">
  <header>
    <Login />
  </header>
</div>
```

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

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;

Testar a entrada no aplicativo

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

Voltar para o navegador em que seu aplicativo React está em execução. Agora você deve ver um botão Entrar .
Ao selecionar o botão Entrar, você será solicitado a entrar com sua conta Microsoft (você pode usar a mesma conta que a que acessou o portal do Azure).
Na primeira vez que você estiver usando esse aplicativo Microsoft Entra, você precisa consentir seu uso em sua organização.
Depois de entrar, você será redirecionado para seu aplicativo React. Observe que o botão Entrar foi alterado 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 conectado é exibido.

Especificar 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 acessar o calendário das pessoas e o acesso básico a 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 do Microsoft API do Graph.

No editor de código, 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 dados de calendário do usuário após entrar

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

Você precisa controlar o estado conectado do usuário para usar o useIsSignedIn gancho fornecido por mgt-react.

Importe o useIsSignedIn gancho de mgt-react, adicionando-o às mgt-react importações.
```
import { Login, useIsSignedIn } from '@microsoft/mgt-react';
```
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 booliana isSignedIn , que você pode usar para determinar se o usuário está conectado ao seu aplicativo no momento.

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

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

No editor de código, abra o arquivo src/App.tsx e estenda a instrução de componente import com o <Agenda /> componente.
```
import { useIsSignedIn, Agenda, Login } from '@microsoft/mgt-react';
```
Estenda o conteúdo da return cláusula com um componente extra div e o Kit de Ferramentas <Agenda /> do Microsoft Graph que só renderiza se o usuário estiver conectado.
```
<div className="row">
  <div className="column">
    {isSignedIn &&
      <Agenda />}
  </div>
</div>
```
No editor de código, 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 se parecer com o seguinte.

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;

Mostrar a conversa de chat de um usuário

Em seguida, estenda o aplicativo para mostrar uma conversa das conversas do usuário 1:1 e do grupo. Você só pode acessar essas informações depois que o usuário entrar.

Atualizar as permissões necessárias para seu aplicativo

Ao adicionar os componentes de chat ao seu aplicativo, você precisa atualizar a lista de escopos solicitados para incluir as permissões necessárias para acessar dados de chat. Você pode encontrar os escopos exigidos por cada API na documentação do Microsoft API do Graph.

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

import { allChatScopes } from '@microsoft/mgt-chat';

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

Carregar uma conversa de chat de um usuário se o usuário estiver conectado

No editor de código, abra o arquivo src/App.tsx e estenda a instrução de componente import com o componente e os tipos do Chat .

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

Em seguida, dentro da função App , adicione o código necessário para lidar com as interações do usuário com os componentes do chat.

const [chatId, setChatId] = useState<string>();

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

Em seguida, estenda o conteúdo da return cláusula com um extra div e o Kit de Ferramentas <Chat /> do Microsoft Graph e <NewChat /> componentes.

<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>

Com essas alterações, o arquivo src/App.tsx deve se parecer com o seguinte.

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 eles entraram

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

Para ver as alterações, atualize seu navegador em http://localhost:3000.
Escolha o botão Entrar e entre usando sua conta Microsoft.
Depois de consentir com o uso do aplicativo, você deverá ver informações sobre o usuário atual e seu calendário.

Para ver as alterações, atualize seu navegador em http://localhost:3000.
Escolha o botão Entrar e entre usando sua conta Microsoft.
Depois de consentir com o uso do aplicativo, você deverá ver informações sobre o usuário atual. Você também vê o calendário deles e a capacidade de criar um novo chat e começar a interagir com esse usuário.

Próximas etapas

Confira o que está no Kit de Ferramentas do Microsoft Graph.
Experimente os componentes do playground.
Faça uma pergunta no Stack Overflow.
Relate bugs ou deixe uma solicitação de recurso no GitHub.

Use o Kit de Ferramentas do Microsoft Graph com React

Pré-requisitos

Criar um aplicativo React

Criar um aplicativo Microsoft Entra

Conectar React aplicativo ao Microsoft 365

Copiar a ID de registro do aplicativo Microsoft Entra

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

Testar a entrada no aplicativo

Carregar dados do Microsoft 365

Especificar permissões necessárias para seu aplicativo

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

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

Mostrar a conversa de chat de um usuário

Atualizar as permissões necessárias para seu aplicativo

Carregar uma conversa de chat de um usuário se o usuário estiver conectado

Teste mostrando o calendário e os chats de um usuário depois que eles entraram

Próximas etapas

Comentários

Comentários

Recursos adicionais

Use o Kit de Ferramentas do Microsoft Graph com React

Pré-requisitos

Criar um aplicativo React

Criar um aplicativo Microsoft Entra

Conectar React aplicativo ao Microsoft 365

Copiar a ID de registro do aplicativo Microsoft Entra

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

Adicionar o botão de entrada

Testar a entrada no aplicativo

Carregar dados do Microsoft 365

Especificar permissões necessárias para seu aplicativo

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

Controlar o estado de entrada do usuário

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

Mostrar a conversa de chat de um usuário

Atualizar as permissões necessárias para seu aplicativo

Carregar uma conversa de chat de um usuário se o usuário estiver conectado

Teste mostrando o calendário e os chats de um usuário depois que eles entraram

Próximas etapas

Comentários

Comentários

Recursos adicionais