Поставщики microsoft Graph Toolkit
Поставщики 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
класса.
Дополнительные сведения о каждом из них см. в разделе Настраиваемые поставщики.
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по