Поделиться через


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

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

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

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

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

Совет

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

Совет

Вы также можете скачать начальный шаблон, чтобы начать свой путь. Этот шаблон обеспечит правильный набор зависимостей и т. д. Чтобы продолжить, скачайте начальный проект GitHub для mgt-react. Следуйте инструкциям readme, а затем продолжите загрузку данных из Microsoft 365.

Совет

Вы также можете скачать начальный шаблон, чтобы начать свой путь. Этот шаблон обеспечит правильный набор зависимостей и т. д. Чтобы продолжить, скачайте начальный проект GitHub для mgt-react и mgt-chat. Следуйте инструкциям readme, а затем продолжите загрузку данных из Microsoft 365.

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

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

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

Создайте приложение React, выполнив следующую команду. Эта команда создает новое приложение React с помощью TypeScript, что помогает написать более надежный код и избежать ошибок среды выполнения. Если будет предложено установить create-react-app пакет, выберите y для подтверждения.

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

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

cd my-m365-app

Затем установите mgt-reactпакеты , mgt-element и mgt-msal2-provider npm, которые содержат компоненты Microsoft Graph Toolkit React, основные возможности набора средств и поставщик проверки подлинности MSAL2.

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

Затем установите mgt-reactпакеты , mgt-chatmgt-element и mgt-msal2-provider npm, которые содержат компоненты Microsoft Graph Toolkit React, основные возможности набора средств и поставщик проверки подлинности 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

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

npm start

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

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

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

Чтобы создать приложение Microsoft Entra, выполните действия, описанные в статье Создание приложения Microsoft Entra.

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

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

Копирование идентификатора регистрации приложения Microsoft Entra

  1. В Центр администрирования Microsoft Entra перейдите к регистрации приложения.
  2. Убедитесь, что вы находитесь на странице Обзор.
  3. Скопируйте значение свойства Идентификатор приложения (клиента) из раздела Основное.

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

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

  1. В редакторе кода откройте файл src/index.tsx и добавьте в список импортируемых данных:

    import { Providers } from "@microsoft/mgt-element";
    import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
    
  2. После последнего оператора import инициализируйте Microsoft Graph Toolkit с помощью поставщика MSAL.

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

Замените значение clientId свойства значением Application (client) ID свойства, скопированного ранее в обзоре Центр администрирования Microsoft Entra регистрации приложений.

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

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

Добавить кнопку входа

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

  1. Откройте в редакторе кода файл src/App.tsx и добавьте в список операций импорта следующее:

    import { Login } from '@microsoft/mgt-react';
    
  2. В функции замените App содержимое предложения базовой return структурой, включая компонент Microsoft Graph Toolkit <Login /> :

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

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

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;

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

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

  1. Вернитесь в браузер, в котором выполняется ваше приложение React. Теперь должна появиться кнопка Войти .
  2. При нажатии кнопки Войти вам будет предложено войти с помощью учетной записи Майкрософт (можно использовать ту же учетную запись, что и учетная запись, с помощью портал Azure).
  3. При первом использовании этого приложения Microsoft Entra необходимо согласиться на его использование в организации.
  4. После входа вы будете перенаправлены в приложение React. Обратите внимание, что кнопка "Войти" изменена, чтобы отобразить имя пользователя React приложение, в котором отображаются сведения о пользователе, полученные из Microsoft 365 с помощью Microsoft Graph Toolkit.

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

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

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

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

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

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

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

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

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

Необходимо отслеживать состояние входа пользователя, чтобы использовать useIsSignedIn перехватчик, предоставленный mgt-react.

  1. useIsSignedIn Импортируйте перехватчик из mgt-react, добавив его в mgt-react импорт.

    import { Login, useIsSignedIn } from '@microsoft/mgt-react';
    
  2. Используйте перехватчик useIsSignedIn , чтобы включить отслеживание состояния входа пользователя в приложение, добавив его в функцию приложения :

      const [ isSignedIn ] = useIsSignedIn();
    

Этот код определяет логическую isSignedIn константу, с помощью которой можно определить, вошел ли пользователь в приложение в данный момент.

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

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

  1. В редакторе кода откройте файл src/App.tsx и расширьте инструкцию component import с помощью <Agenda /> компонента.

    import { useIsSignedIn, Agenda, Login } from '@microsoft/mgt-react';
    
  2. Расширьте содержимое return предложения дополнительным div компонентом и компонентом Microsoft Graph Toolkit <Agenda /> , который отображается только в том случае, если пользователь вошел в систему.

    <div className="row">
      <div className="column">
        {isSignedIn &&
          <Agenda />}
      </div>
    </div>
    
  3. В редакторе кода откройте файл src/App.css и измените все содержимое файла с помощью следующего кода.

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

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

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;

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

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

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

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

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

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

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

  1. В редакторе кода откройте файл src/App.tsx и расширьте инструкцию component import с помощью компонента и типов Chat .

    import { Chat, NewChat } from '@microsoft/mgt-chat';
    import { Chat as GraphChat } from '@microsoft/microsoft-graph-types';
    import React, { useState, useEffect, useCallback } from 'react';
    
  2. Затем в функции Приложения добавьте необходимый код для обработки взаимодействия пользователя с компонентами чата.

    const [chatId, setChatId] = useState<string>();
    
    const [showNewChat, setShowNewChat] = useState<boolean>(false);
    const onChatCreated = useCallback((chat: GraphChat) => {
      setChatId(chat.id);
      setShowNewChat(false);
    }, []);
    
  3. Затем расширьте содержимое return предложения дополнительным div и набором средств <Chat /> и <NewChat /> компонентов Microsoft Graph.

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

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

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;

Тест, показывающий календарь и чаты пользователя после входа

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

  1. Чтобы просмотреть изменения, обновите браузер по адресу http://localhost:3000.
  2. Нажмите кнопку Войти и войдите с помощью учетной записи Майкрософт.
  3. После подтверждения согласия на использование приложения вы должны увидеть информацию о текущем пользователе и его календаре. Готовое приложение
  1. Чтобы просмотреть изменения, обновите браузер по адресу http://localhost:3000.
  2. Нажмите кнопку Войти и войдите с помощью учетной записи Майкрософт.
  3. После согласия на использование приложения вы увидите сведения о текущем пользователе. Вы также увидите их календарь и возможность создать новый чат и начать взаимодействие с этим пользователем. Готовое приложение

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