Использование Microsoft Graph Toolkit с React

Статья
03/26/2023

Microsoft Graph Toolkit — это набор веб-компонентов, которые упрощают подключение к Microsoft Graph и позволяют вам сосредоточиться на своем приложении. Microsoft Graph Toolkit доступен как общий набор веб-компонентов, распространяемых через пакет NPM @microsoft/mgt.

Если вы создаете приложения с помощью React, вы можете использовать пакет @microsoft/mgt-react, который упаковывает веб-компоненты Microsoft Graph Toolkit в компоненты React и упрощает передачу сложных данных.

В этой статье описывается пошаговый процесс использования Microsoft Graph Toolkit для создания приложения React и подключения его к Microsoft 365. После выполнения всех шагов у вас получится приложение React, которое показывает предстоящие встречи пользователя, вошедшего в систему в Microsoft 365.

Совет

Вы также можете следовать этому руководству в виде интерактивного обзора кода. Дополнительные сведения см. в репозитории GitHub с начальным проектом.

Предварительные условия

Чтобы выполнить действия, описанные в этой статье, вам понадобится среда разработки Microsoft 365 и несколько инструментов. Дополнительные сведения см. в разделе Приступая к работе.

Создание приложения React

Создайте приложение React, выполнив следующую команду. Это создаст новое приложение React с использованием TypeScript, что поможет написать более функциональный код и избежать ошибок выполнения.

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

Измените рабочий каталог на только что созданное приложение.

cd my-m365-app

Затем установите пакет NPM mgt-react, который содержит компоненты Microsoft Graph Toolkit для React.

npm i @microsoft/mgt-react

mgt-msal2-provider Также установите пакет и mgt-element npm, который содержит поставщик проверки подлинности MSAL2.

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

Подтвердите, что вы можете запустить приложение.

npm start

У вас должна быть возможность открыть приложение в браузере через http://localhost:3000.

Создание приложения Azure Active Directory

Microsoft Graph — это API, используемый для подключения к Microsoft 365. Он защищен с помощью OAuth 2.0. Чтобы подключить приложение к Microsoft 365, вам потребуется создать приложение в Azure Active Directory (Azure AD) и предоставить этому приложению разрешения на доступ к определенным ресурсам от имени пользователя, использующего ваше приложение.

Выполните действия, описанные в статье Создание приложения Azure Active Directory, чтобы создать новое приложение Azure AD.

Подключение приложения React к Microsoft 365

Теперь, когда вы зарегистрировали свое приложение в Azure Active Directory (Azure AD), вы можете подключить приложение React к Microsoft 365. Для начала разрешите пользователям входить в приложение при помощи учетной записи Майкрософт.

Скопируйте идентификатор регистрации приложения в Azure AD.

На портале Azure перейдите к регистрации приложения.
Убедитесь, что вы находитесь на странице Обзор.
Скопируйте значение свойства Идентификатор приложения (клиента) из раздела Основное.

Настройка поставщика проверки подлинности Microsoft Graph Toolkit

Теперь настройте поставщика проверки подлинности, который должен использовать Microsoft Graph Toolkit. В этом случае будет использоваться MSAL, который по умолчанию подходит для создания автономных приложений. Если вы используете какие-либо точки расширения в Microsoft 365, например Teams или SharePoint, то необходимо будет выбрать других поставщиков.

Примечание.

Если в настоящее время вы используете поставщик MSAL и хотите обновить его до поставщика MSAL2, выполните действия, описанные в статье Поставщик MSAL2 .

В редакторе кода откройте файл src/index.tsx и добавьте в список импортируемых данных:
```
import { Providers } from '@microsoft/mgt-element';
import { Msal2Provider } from '@microsoft/mgt-msal2-provider';
```
После последнего оператора import инициализируйте Microsoft Graph Toolkit с помощью поставщика MSAL.
```
Providers.globalProvider = new Msal2Provider({
  clientId: 'REPLACE_WITH_CLIENTID'
});
```
Замените значение свойства clientId значением свойства Application (client) ID, которое вы ранее скопировали на портале Azure.

С этими изменениями файл src/index.tsx будет выглядеть следующим образом.

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();

Добавьте компонент Microsoft Graph Toolkit для React под названием Вход, отображающий кнопку Войти, которую пользователи смогут использовать для входа в ваше приложение со своей учетной записью Майкрософт.

Откройте в редакторе кода файл src/App.tsx и добавьте в список операций импорта следующее:
```
import { Login } from '@microsoft/mgt-react';
```
В функции App замените содержимое пункта return базовой структурой, включая компонент входа Microsoft Graph Toolkit:
```
<div className="App">
  <header>
    <Login />
  </header>
</div>
```

С этими изменениями файл src/App.tsx будет выглядеть следующим образом.


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;

Тестирование входа в приложение

Теперь вы можете входить в приложение с помощью своей учетной записи Майкрософт.

Вернитесь в браузер, в котором выполняется ваше приложение React. Теперь вы должны видеть кнопку Войти.
При нажатии кнопки Войти вам будет предложено войти в систему с помощью учетной записи Майкрософт. Вы можете использовать ту же учетную запись, с помощью которой заходили на портал Azure.
Так как это приложение Azure AD используется впервые, вам необходимо дать согласие на его использование в вашей организации.
После входа в систему вы будете перенаправлены в приложение React. Обратите внимание, что кнопка Войти изменилась, чтобы отобразить имя пользователя .

Загрузка данных из Microsoft 365

Microsoft Graph Toolkit не только упрощает проверку подлинности при входе в Microsoft 365, но и загружает его данные. В этом примере будет показан календарь пользователя, вошедшего в систему.

Определение разрешений, необходимых для вашего приложения

Прежде чем вы сможете загружать данные из Microsoft 365, необходимо определить список областей разрешений, которые необходимы вашему приложению для получения доступа к данным пользователя. Эти области различаются в зависимости от того, какую информацию вы хотите показать. В этом случае понадобится доступ к календарю пользователей, а также базовый доступ к информации о пользователях, которая также отображается в календаре. Области разрешений, необходимые для каждого API, можно найти в документации API Microsoft Graph.

Откройте в редакторе кода файл src/index.tsx и обновите код инициализации поставщика.

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

Отображение данных пользователя после входа в систему

Теперь дополните приложение, чтобы оно отображало данные из календаря пользователя. Доступ к этой информации можно получить только после того, как пользователь вошел в систему. Для этого необходимо отслеживать состояние входа пользователя и отображать данные календаря после входа пользователя с помощью учетной записи Майкрософт.

Для отслеживания состояния входа пользователя в приложение будет использоваться обработчики React useState и useEffect в сочетании с обработчиками событий провайдера.

Откройте в редакторе кода файл src/App.tsx и дополните существующий оператор React import.
```
import React, { useState, useEffect } from 'react';
```
Импортируйте типы Provider и ProviderState из mgt-element, добавив их в операции импорта.
```
import { Providers, ProviderState } from '@microsoft/mgt-element';
```

Добавьте настраиваемую функцию с именем useIsSignedIn, которая позволяет отслеживать состояние входа пользователя в приложение.

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];
}

Эта функция выполняет два действия. Во-первых, с помощью обработчика React useState она позволяет отслеживать состояние внутри компонента. При каждом изменении состояния React повторно отображает ваш компонент. Во-вторых, с помощью обработчика React useEffect она продлевает жизненный цикл компонента, отслеживая изменения в поставщике Microsoft Graph Toolkit и обновляя компонент при необходимости.

Загрузка календаря пользователя, вошедшего в систему

Теперь, когда отслеживается состояние входа пользователя в приложение, вы можете отображать календарь пользователя после входа в систему.

В редакторе кода откройте файл src/App.tsx и расширьте инструкцию компонента import компонентом Agenda .
```
import { Agenda, Login } from '@microsoft/mgt-react';
```
Затем в функции Приложения добавьте:
```
const [isSignedIn] = useIsSignedIn();
```
Это определяет логическую константу isSignedIn, которую можно использовать для определения, выполнил ли пользователь вход в приложение.
В содержимое пункта return добавьте div, а также компонент расписания Microsoft Graph Toolkit.
```
<div>
  {isSignedIn &&
    <Agenda />}
</div>
```

С этими изменениями файл src/App.tsx будет выглядеть следующим образом.

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;

Тестирование отображения календаря пользователя после входа в систему

С внесением этих изменений вы должны увидеть свой календарь после входа в приложение с учетной записью Майкрософт.

Чтобы увидеть изменения, закройте браузер, откройте его снова и перейдите на http://localhost:3000. Это нужно сделать, потому что вы изменили значение свойства scopes, которое влияет на маркер доступа, запрашиваемый из Azure AD.
Нажмите кнопку Войти и войдите с помощью учетной записи Майкрософт. Обратите внимание на новые пункты списка разрешений в запросе на продолжение. Они появились, так как вы включили в свойство scope дополнительные разрешения.
После подтверждения согласия на использование приложения вы должны увидеть информацию о текущем пользователе и его календаре.

Готовое приложение

Дальнейшие действия

Узнать, что включает Microsoft Graph Toolkit.
Воспользуйтесь компонентами в интерактивной среде.
Задавайте вопросы на сайте Stack Overflow.
Сообщайте об ошибках и оставляйте запросы на создание функций в GitHub.

Использование Microsoft Graph Toolkit с React

Предварительные условия

Создание приложения React

Создание приложения Azure Active Directory

Подключение приложения React к Microsoft 365

Скопируйте идентификатор регистрации приложения в Azure AD.

Настройка поставщика проверки подлинности Microsoft Graph Toolkit

Тестирование входа в приложение

Загрузка данных из Microsoft 365

Определение разрешений, необходимых для вашего приложения

Отображение данных пользователя после входа в систему

Загрузка календаря пользователя, вошедшего в систему

Тестирование отображения календаря пользователя после входа в систему

Дальнейшие действия

Дополнительные ресурсы

Дополнительные ресурсы

Использование Microsoft Graph Toolkit с React

Предварительные условия

Создание приложения React

Создание приложения Azure Active Directory

Подключение приложения React к Microsoft 365

Скопируйте идентификатор регистрации приложения в Azure AD.

Настройка поставщика проверки подлинности Microsoft Graph Toolkit

Добавление кнопки входа

Тестирование входа в приложение

Загрузка данных из Microsoft 365

Определение разрешений, необходимых для вашего приложения

Отображение данных пользователя после входа в систему

Отслеживание состояния входа пользователя в систему

Загрузка календаря пользователя, вошедшего в систему

Тестирование отображения календаря пользователя после входа в систему

Дальнейшие действия

Дополнительные ресурсы

Дополнительные ресурсы