Microsoft Graph 工具包提供程序

项目
10/18/2023

借助 Microsoft Graph 工具包提供程序，应用程序只需几行代码即可使用 Microsoft 标识进行身份验证并访问 Microsoft Graph。每个提供程序处理用户身份验证和获取访问令牌以调用 Microsoft Graph API，因此你不必自己编写此代码。

可以使用提供程序本身（无需组件）为应用快速实现身份验证，并通过 JavaScript 客户端 SDK 调用 Microsoft Graph。

使用 Microsoft Graph 工具包组件时，需要提供程序，因为组件使用这些组件来访问 Microsoft Graph。如果已有自己的身份验证并且想要使用这些组件，则可以改用自定义提供程序。

工具包包括以下提供程序。

提供程序	说明
自定义	创建一个自定义提供程序，以使用应用程序的现有身份验证代码启用对 Microsoft Graph 的身份验证和访问。
电子	对 Electron 应用内的组件进行身份验证并提供 Microsoft Graph 访问权限。
MSAL2	使用 MSAL 浏览器登录用户并获取用于 Microsoft Graph 的令牌。
代理	通过后端将所有调用路由到 Microsoft Graph 以允许使用后端身份验证。
SharePoint	对 SharePoint Web 部件中的组件进行身份验证并提供对组件的 Microsoft Graph 访问权限。
TeamsFx	使用 Microsoft Teams 应用程序内的 TeamsFx 提供程序提供对 Microsoft Graph 的 Microsoft Graph 工具包组件访问权限。

初始化提供程序

若要在应用中使用提供程序，需要初始化新的提供程序，然后在 Providers 命名空间中将其设置为全局提供程序。建议在开始使用任何组件之前执行此操作。可以通过以下两种方式之一执行此操作：

选项 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",
});

注意：有关如何注册应用和获取客户端 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 客户端指定自定义主机。这允许调用非 Microsoft Graph Microsoft Entra ID保护的 API。指定自定义主机时，请确保请求访问令牌的范围。

<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 进行自己的调用，可以通过获取对组件使用的相同 Microsoft Graph SDK 的引用来实现。首先，获取对全局 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();

使用多个提供程序

在某些情况下，应用程序将在不同的环境中运行，并且需要针对每个环境使用不同的提供程序。例如，应用可能同时作为 Web 应用程序和 Microsoft Teams 选项卡运行，这意味着你可能需要同时使用 MSAL2 提供程序和 Teams MSAL2 提供程序。对于此方案，所有提供程序组件都具有 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>

在此方案中，仅当应用作为 Web 应用程序运行并且 Teams MSAL2 提供程序在当前环境中不可用时，才会使用 MSAL2 提供程序。

若要在代码中完成相同的操作，可以在 isAvailable 提供程序上使用属性，如下所示。

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

用户登录/注销

如果为应用程序初始化了正确的提供程序，则可以添加工具包的 Login 组件，以便轻松快速地实现用户登录和注销。组件与提供程序一起处理所有身份验证逻辑和登录/注销功能。以下示例使用 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>
<mgt-login></mgt-login>

在想要自己实现此方案（而不是使用工具包的登录组件）的情况下，可以使用提供程序的和 logout 方法执行此操作login。

实现自己的提供程序

在想要使用预先存在的身份验证代码将工具包组件添加到应用程序的情况下，可以创建一个挂钩到身份验证机制的自定义提供程序，而不是使用预定义的提供程序。该工具包提供了两种创建新提供程序的方法：

创建一个新的 SimpleProvider ，它通过传入函数从身份验证代码返回访问令牌。
IProvider扩展抽象类。

有关每个提供程序的更多详细信息，请参阅自定义提供程序。