Поставщики microsoft Graph Toolkit

Статья
03/26/2023

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

Поставщики можно использовать самостоятельно, без компонентов, чтобы быстро реализовать проверку подлинности для приложения и выполнять вызовы к Microsoft Graph через клиентский пакет SDK для JavaScript.

Поставщики необходимы при использовании компонентов Microsoft Graph Toolkit, так как компоненты используют их для доступа к Microsoft Graph. Если у вас уже есть собственная проверка подлинности и вы хотите использовать компоненты, можно использовать настраиваемый поставщик .

Набор средств включает следующие поставщики.

Поставщики	Описание
Custom	Создает настраиваемый поставщик для включения проверки подлинности и доступа к Microsoft Graph с помощью существующего кода проверки подлинности приложения.
Электрон	Выполняет проверку подлинности и предоставляет Microsoft Graph доступ к компонентам в приложениях Electron.
MSAL2	Использует MSAL-browser для входа пользователей и получения маркеров для использования с Microsoft Graph.
Прокси-сервер	Позволяет использовать проверку подлинности на внутреннем сервере с помощью маршрутизации всех вызовов Microsoft Graph через внутренний сервер.
SharePoint	Проверяет подлинность и предоставляет Microsoft Graph доступ к компонентам в веб-частях SharePoint.
TeamsFx	Используйте поставщик TeamsFx в приложениях Microsoft Teams, чтобы предоставить компонентам Microsoft Graph Toolkit доступ к Microsoft Graph.

Инициализация поставщика

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

Вариант 1. Использование компонента поставщика

Версию компонента поставщика можно использовать непосредственно в HTML-коде. В фоновом режиме новый поставщик инициализируется и устанавливается в качестве глобального поставщика. В следующем примере показано, как использовать поставщик MSAL2.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>

Вариант 2. Инициализация в коде

Инициализация поставщика в коде JavaScript позволяет предоставить дополнительные возможности. Для этого создайте новый экземпляр поставщика и задайте для свойства значение Providers.globalProvider поставщика, который вы хотите использовать. В следующем примере показано, как использовать поставщик MSAL2.

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: "YOUR_CLIENT_ID",
});

Примечание: Дополнительные сведения о регистрации приложения и получении идентификатора клиента см. в разделе Создание приложения Microsoft Entra.

Области разрешений

Рекомендуется добавить все области разрешений, необходимые приложению, в scopes атрибут или свойство при инициализации поставщика (это не относится к поставщику SharePoint). Это необязательно, но улучшит взаимодействие с пользователем, предоставляя пользователю единый экран согласия с агрегированным списком разрешений, запрашиваемых всеми компонентами приложения, а не показывая отдельные экраны для каждого компонента. В следующих примерах показано, как это сделать с помощью поставщика MSAL2.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider
  client-id="YOUR_CLIENT_ID"
  scopes="user.read,people.read"
></mgt-msal2-provider>

При инициализации поставщика в коде укажите области разрешений в массиве в свойстве scopes .

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID'
  scopes:['user.read','people.read']
});

Список областей разрешений, необходимых каждому компоненту, можно найти в разделе Разрешения Microsoft Graph на странице документации по каждому компоненту.

Пользовательские узлы

Вы можете указать пользовательские узлы для клиента Microsoft Graph. Это позволяет вызывать API-интерфейсы, защищенные Microsoft Entra ID не microsoft Graph. При указании пользовательских узлов убедитесь, что вы запрашиваете область для маркера доступа.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider 
  client-id="YOUR_CLIENT_ID"
  custom-hosts="myapi.com,anotherapi.com"
></mgt-msal2-provider>

При инициализации поставщика в коде укажите имена узлов в массиве в свойстве customHosts .

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID',
  customHosts: ['myapi.com','anotherapi.com']
});

Примечание. Это имена узлов, а не URI.

Чтобы вызвать пользовательские API, запросите этот API область.

<mgt-get resource="https://myapi.com/v1.0/api" scopes="api://CUSTOM_API_GUID/SCOPE">
  ...
</mgt-get>

Или с помощью Javascript или Typescript:

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("https://myapi.com/v1.0/api")
  .middlewareOptions(prepScopes("api://CUSTOM_API_GUID/SCOPE"))
  .get();
...

Состояние поставщика

Поставщик отслеживает состояние проверки подлинности пользователя и передает его компонентам. Например, когда пользователь успешно войдет в систему, ProviderState объект обновляется до SignedIn, что сигнализирует компонентам о том, что теперь они могут совершать вызовы к Microsoft Graph. Как показано, перечисление ProviderState определяет три состояния.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn,
}

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

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  //your code here
}

Вы также можете использовать Providers.onProviderUpdated метод для получения уведомлений при изменении состояния поставщика.

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

const providerStateChanged = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    // user is now signed in
  }
};

// register a callback for when the state changes
Providers.onProviderUpdated(providerStateChanged);

// remove callback if necessary
Providers.removeProviderUpdatedListener(providerStateChanged);

Получение маркера доступа

Каждый поставщик предоставляет функцию с именем getAccessToken , которая может получить текущий маркер доступа или получить новый маркер доступа для предоставленных областей. В следующем примере показано, как получить новый маркер доступа с User.Read область разрешений.

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  const token = await Providers.globalProvider.getAccessToken({
    scopes: ["User.Read"],
  });
}

Собственные вызовы к Microsoft Graph

Все компоненты могут получить доступ к Microsoft Graph без необходимости настройки при условии инициализации поставщика (как описано в предыдущих разделах). Если вы хотите выполнить собственные вызовы к Microsoft Graph, вы можете сделать это, получив ссылку на тот же пакет SDK Microsoft Graph, который используется компонентами. Сначала получите ссылку на глобальный IProvider , а затем используйте объект , graph как показано ниже.

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

let provider = Providers.globalProvider;
if (provider) {
  let graphClient = provider.graph.client;
  let userDetails = await graphClient.api("me").get();
}

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

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("me")
  .middlewareOptions(prepScopes("user.read", "calendar.read"))
  .get();

Использование нескольких поставщиков

В некоторых сценариях приложение будет выполняться в разных средах и требовать разных поставщиков для каждого из них. Например, приложение может работать как веб-приложение, так и как вкладка Microsoft Teams. Это означает, что вам может потребоваться использовать как поставщик MSAL2, так и поставщик MSAL2 Teams. В этом сценарии все компоненты поставщика имеют depends-on атрибут для создания резервной цепочки, как показано в следующем примере.

<mgt-teams-msal2-provider
  client-id="[CLIENT-ID]"
  auth-popup-url="auth.html"
></mgt-teams-msal2-provider>

<mgt-msal2-provider
  client-id="[CLIENT-ID]"
  depends-on="mgt-teams-provider"
></mgt-msal2-provider>

В этом сценарии поставщик MSAL2 будет использоваться только в том случае, если приложение выполняется как веб-приложение, а поставщик MSAL2 Teams недоступен в текущей среде.

Чтобы выполнить то же самое в коде isAvailable , можно использовать свойство поставщика, как показано ниже.

if (TeamsProvider.isAvailable) {
  Providers.globalProvider = new TeamsProvider(teamsConfig);
} else {
  Providers.globalProvider = new Msal2Provider(msalConfig);
}

Вход и выход пользователя

Если у вас есть правильные поставщики, инициализированные для приложения, вы можете добавить компонент Входа набора средств, чтобы легко и быстро реализовать вход и выход пользователя. Компонент работает с поставщиком для обработки всех функций логики проверки подлинности и входа и выхода. В следующем примере используется поставщик MSAL2 и компонент Login.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>
<mgt-login></mgt-login>

В сценариях, где вы хотите реализовать это самостоятельно, а не с помощью компонента входа набора средств, это можно сделать с помощью login методов и logout поставщика.

Реализация собственного поставщика

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

Создайте новый SimpleProvider объект, который возвращает маркер доступа из кода проверки подлинности путем передачи функции.
Расширение абстрактного IProvider класса.

Дополнительные сведения о каждом из них см. в разделе Настраиваемые поставщики.