Microsoft Graph 工具包提供程序Microsoft Graph Toolkit providers

Microsoft Graph 工具包提供程序为所有组件启用身份验证和 Microsoft Graph 访问。The Microsoft Graph Toolkit providers enable authentication and Microsoft Graph access for all components. 每个提供程序都提供用于获取调用 Microsoft Graph Api 所需的访问令牌的实现。Each provider provides implementation for acquiring the necessary access token for calling the Microsoft Graph APIs.

对于要使用提供程序的组件,必须将该Providers.globalProvider属性设置为要使用的提供程序的值。For the components to use a provider, you must set the Providers.globalProvider property to the value for a provider you'd like to use.

下面的示例演示如何使用 MsalProvider。The following example shows how to use the MsalProvider.

Providers.globalProvider = new MsalProvider({
  clientId: '[CLIENT_ID]'
});

此工具包实现以下提供程序:The toolkit implements the following providers:

您可以随时创建提供程序。You can create a provider at any time. 我们建议您先创建提供程序,然后再使用任何组件。We recommend that you create the provider before you use any of the components. 本节介绍如何初始化提供程序。This section describes how to initialize a provider.

提供程序命名空间Providers namespace

Providers命名空间公开以下属性和函数:The Providers namespace exposes the following properties and functions:

  • globalProvider : IProvider

将此属性设置为要全局使用的提供程序。Set this property to a provider that you want to use globally. 所有组件均使用此属性获取对提供程序的引用。All components use this property to get a reference to the provider. 设置此属性将触发该onProvidersChanged事件。Setting this property will fire the onProvidersChanged event.

  • function onProviderUpdated(callbackFunction)

callbackFunction提供程序发生更改或提供程序的状态更改时,将调用此函数。The callbackFunction function will be called when a provider is changed or when the state of a provider changes. ProvidersChangedState枚举值将传递给函数以指示更新的内容。A ProvidersChangedState enum value will be passed to the function to indicate what updated.

实现您自己的提供程序Implement your own provider

该工具包提供了两种创建新的提供程序的方法:The toolkit provides two ways to create new providers:

  • 通过传入获取SimpleProvider访问令牌的函数来创建新的。Create a new SimpleProvider by passing in a function for getting an access token.
  • 扩展IProvider抽象类。Extend the IProvider abstract class.

有关每个的详细信息,请参阅自定义提供程序For more details about each one, see custom providers.

使用多个提供程序Using multiple providers

在某些情况下,您的应用程序将在不同的环境中运行,并需要不同的提供程序。In some scenarios, your application will run in a different environment and require a different provider. 例如,应用程序可能同时作为 web 应用程序和 Microsoft 团队选项卡运行,您可能需要使用 MsalProvider 和 TeamsProvider。For example, the app might run as both a web application and a Microsoft Teams tab and you might need to use the MsalProvider and the TeamsProvider. 对于此方案,所有提供程序组件都depends-on具有创建回退链的属性,如下面的示例所示。For this scenario, all provider components have the depends-on attribute to create a fallback chain, as shown in the following example.

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

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

在这种情况下,仅当 TeamsProvider 在当前环境中不可用时,才会使用 MsalProvider。In this scenario, the MsalProvider will only be used if the TeamsProvider is not available in the current environment.

若要在代码中实现相同,可以使用提供isAvailable程序上的属性,如下所示。To accomplish the same in code, you can use the isAvailable property on the provider, as shown.

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

对 Microsoft Graph 进行自己的调用Making your own calls to Microsoft Graph

只要您初始化提供程序(如上一节中所述),所有组件都可以访问 Microsoft Graph,而无需进行任何自定义。All components can access Microsoft Graph without any customization required as long as you initialize a provider (as described in the previous section). 若要获取对组件使用的同一 Microsoft Graph SDK 的引用,请首先获取对全局 IProvider 的引用,然后使用该Graph对象,如下所示:To get a reference to the same Microsoft Graph SDK used by the components, first get a reference to the global IProvider and then use the Graph object, as shown:

import { Providers } from '@microsoft/mgt';

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

在某些情况下,您可能需要传递其他权限,具体取决于您要调用的 API。There might be cases were you will need to pass additional permissions, depending on the API you're calling.

import { prepScopes } from '@microsoft/mgt';

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

graph对象是MICROSOFT graph Javascript SDK的一个实例,可以使用它对 microsoft graph 进行任何调用。The graph object is an instance of the Microsoft Graph Javascript SDK and you can use it to make any calls to Microsoft Graph.