使用 MSGraphClientV3 连接到 Microsoft Graph

项目
03/21/2023

生成SharePoint 框架解决方案时，可以使用 MSGraphClientV3 轻松连接到 Microsoft Graph。

MSGraphClient 概述

MSGraphClientV3 是 SharePoint 框架 v1.15.0 中引入的新 HTTP 客户端，可简化SharePoint 框架解决方案中的 Microsoft Graph 连接。 MSGraphClientV3 包装了 Microsoft Graph JavaScript 客户端库 v3，为开发人员提供与其他客户端解决方案中使用客户端库时相同的功能。

MSGraphClientV3 替换 SharePoint 框架 v1.6.0 中引入的 MSGraphClient。 MSGraphClient 包装了 Microsoft Graph JavaScript 客户端库 v1。

虽然可以直接在解决方案中使用 Microsoft Graph JavaScript 客户端库，但 MSGraphClientV3 可处理针对 Microsoft Graph 进行身份验证，这使你可以专注于构建解决方案。

在解决方案中使用 MSGraphClient

注意

MSGraphClientV3 仅在使用 SharePoint 框架 v1.15.0 及更高版本生成的项目中可用。虽然本文使用客户端 Web 部件对 MSGraphClientV3 进行了介绍，但也可以在SharePoint 框架扩展中使用它。

注意

MSGraphClientV3 的单一登录目前仅在 SharePoint Online 中可用。你可以利用客户端进行本地开发，但你的用户将被要求在 webpart 中再次登录。

若要在 SharePoint 框架解决方案中使用 MSGraphClientV3，请在主 Web 部件文件中添加以下import子句：
```
import { MSGraphClientV3 } from '@microsoft/sp-http';
```

MSGraphClientV3 通过 Web 部件上下文中提供的 MSGraphClientFactory 公开。若要获取 MSGraphClient 的引用，应在代码中添加：

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // use MSGraphClient here
      });
  }

  // ...
}

引用 MSGraphClientV3 实例后，请使用其 JavaScript 客户端库语法开始与 Microsoft Graph 通信：

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // get information about the current user from the Microsoft Graph
        client
          .api('/me')
          .get((error, response: any, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

使用 Microsoft Graph TypeScript 类型

处理 Microsoft Graph 和 TypeScript 时，可以使用 Microsoft Graph TypeScript 类型，它们有助于更快地捕获代码中的错误。 Microsoft Graph TypeScript 类型以独立包的形式提供。

安装 Microsoft Graph TypeScript 类型：

npm install @microsoft/microsoft-graph-types --save-dev

在项目中安装此包后，将它导入 Web 部件文件中：

import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';

键入从 Microsoft Graph 中检索到的对象，例如：

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.msGraphClientFactory
      .getClient('3')
      .then((client: MSGraphClientV3): void => {
        // get information about the current user from the Microsoft Graph
        client
          .api('/me')
          .get((error: any, user: MicrosoftGraph.User, rawResponse?: any) => {
            // handle the response
        });
      });
  }

  // ...
}

可用的权限范围

默认情况下，服务主体没有访问 Microsoft Graph 所需的显式权限。不过，如果请求获取 Microsoft Graph 的访问令牌，将获取包含 user_impersonation 权限范围的令牌，可用于读取用户信息（即 User.Read.All）。

其他权限范围可由开发人员请求获取，并由租户管理员授予。有关详细信息，请参阅在 SharePoint 框架解决方案中连接到受 Azure AD 保护的 API。

已知问题

带委派身份验证的 Azure AD 角色

请求 Microsoft Graph 的委派权限时，MSGraphClient 当前使用隐式身份验证流。如 Microsoft 标识平台访问令牌中所述，由于长度问题，使用隐式身份验证流时 wids 声明可能不存在。 wids 声明中包含已分配给委派用户的 Azure AD 租户范围角色的列表。

因此，由于 wids 声明不存在，对依赖 Azure AD 角色的 Microsoft Graph 终结点和委派权限的查询可能失败。在撰写本文时，这包括以下终结点：

Office 365 使用情况报告

通过