Microsoft Graph Toolkit 在 SharePoint 中的开发示例 Step by Step

前面一系列关于Microsoft Graph Toolkit的文章，我们介绍了如何使用这些组件，包括配置、自定义样式、模板化等，还介绍了使用mgt-get去调用Microsoft Graph和Providers相关的内容。

本篇内容是针对SharePoint开发人员的，我们将介绍如何使用Microsoft Graph Toolkit，利用之前介绍的内容去开发SPFx解决方案。

从HTML应用程序到SPFx解决方案

之前我们介绍过，如果我们要使用Microsoft Graph Toolkit去创建一个HTML的应用程序，大概有如下步骤：

1. 注册Azure AD应用程序
2. 创建应用程序
3. 向应用程序中添加Microsoft Graph Toolkit
4. 添加MSAL Provider
5. 添加登录组件
6. 添加其他组件

本篇创建SPFx解决方案，我们将参照上面的步骤逐一说明。

一、注册Azure AD应用程序

当我们要调用Microsoft Graph时，通常需要在Microsoft Identity中注册一个应用程序。但是在构建SharePoint解决方案时，有一点小惊喜，我们不需要再去注册了，每一个解决方案包都会自动生成一个唯一标识，用来授予访问Microsoft Graph API的权限。

也就是说，如果要开发SPFx解决方案，我们在这里什么都不需要做。

二、创建应用程序

之前介绍SPFx解决方案开发的时候介绍过，我们将使用Yeoman SharePoint生成器去创建全新的SharePoint解决方案。忘了的参考SharePoint Framework开发环境的配置。

这里我们将使用标准步骤去创建一个web部件项目：

1. 找一个位置创建项目文件夹

md helloworld-mgt

2. 跳转到该文件夹

cd helloworld-mgt

3. 使用Yeoman创建一个新的HelloWorldweb部件

yo @microsoft/sharepoint

4. 命令行中的提示信息选择如下：

• 解决方案名保留默认直接回车
• 选择SharePoint Online only (latest)
• 选择Use the current folder
• 选择N
• 选择Y
• 选择WebPart

5. 接下来是针对web部件的信息：

• Web部件信息填写HelloMGT
• Web部件描述保留默认直接回车
• 框架选择保留默认直接回车

这样Yeoman就开始安装相关的依赖去创建项目了，在此稍候。

成功后会看到如下提示。

执行命令npm install @microsoft/rush-stack-compiler-3.7 --save-dev以确保我们的项目具有TypeScript，如果已经安装了TypeScript则可以忽略。
用VS Code打开该项目，打开tsconfig.json文件，找到第一行的extends属性，修改为如下内容。

"extends": "./node_modules/@microsoft/rush-stack-compiler-3.7/includes/tsconfig-web.json",

接下来我们可以添加Microsoft Graph Toolkit了。

三、向应用程序中添加Microsoft Graph Toolkit

之前介绍过在HTML页面如果想要添加Microsoft Graph Toolkit，我们需要添加如下JavaScript引用代码。

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>

对于SPFx项目这里略有不同，它使用Node.js，因此我们需要通过npm包安装Microsoft Graph Toolkit。

npm install @microsoft/mgt

安装完之后就可以进行添加provider等后续工作了。

四、添加SharePoint Provider

对于HTML页面，我们可以简单地通过如下代码添加一个MSAL provider用于Microsoft Graph的认证和访问。

<mgt-msal-provider client-id="[YOUR-CLIENT-ID]"></mgt-msal-provider>

对于SPFx项目来说，我们需要使用的是SharePoint provider，按如下步骤操作：

1. 打开文件src\webparts\helloMgt\HelloMgtWebPart.ts
2. 在import部分的下面追加import { Providers, SharePointProvider } from ‘@microsoft/mgt’;
3. 在render方法上面添加如下代码

protected async onInit() {
  Providers.globalProvider = new SharePointProvider(this.context);
}

到这里，准备工作就全部做完了，非常简单。

五、添加登录组件

在HTML页面上时，通常情况下都是从匿名状态开始访问，因此我们需要添加登录组件来为用户提供一个登录的方式。
但是在SharePoint的web部件中，本来就是在认证的上下文中的，因此登录组件就没有存在的必要了。

六、添加其他组件

我们可以将其他Microsoft Graph Toolkit的组件添加到我们的web部件。我们要做的仅仅是在render方法中编写我们需要的组件。

public render(): void {
  this.domElement.innerHTML = `
    
    
  `;
}

七、编译解决方案

在使用web部件之前，我们需要声明需要的Microsoft Graph API权限，参照如下步骤：

1. 打开文件config\package-solution.json
2. 将isDomainIsolated的值改为false，并在结尾添加个逗号
3. 紧接着在下面添加

“webApiPermissionRequests”: [
],

这里用来声明需要请求的权限，例如如果我们需要日程mgt-agenda这个组件，那么我们需要Calendars.Read这个权限，那么定义格式为：

"webApiPermissionRequests": [ 
  {
    "resource": "Microsoft Graph", 
    "scope": "Calendars.Read" 
  }
]

遵从最小权限的原则，建议尽量只声明需要的权限。
4. 编译解决方案，执行如下命令

gulp build
gulp bundle
gulp package-solution

5. 编译完成后会在sharepoint/solution文件夹生成一个.sppkg文件
6. 将该文件上传到SharePoint的应用程序目录，检查请求的权限是否正确，然后点击Deploy按钮进行部署。
   
   如上图，SharePoint提示需要到API管理页面去批准待定的权限。
   “Please go to the API Management Page to approve the pending permissions”

八、批准待定的权限

在解决方案包部署时，会自动创建所需的权限请求，批准的步骤如下：

1. 访问SharePoint管理中心 (https://[yourtenant]-admin.sharepoint.com)
2. 在左侧导航栏选择Advanced -> API access
3. 这里可以看到待定的权限请求，跟我们json文件中声明的一致
   
4. 勾选待定的权限，点击Approve按钮，并在弹出的Approve access窗口点击Approve完成批准。
   
   

九、测试Web部件

对于SPFx的解决方案我们需要在工作台测试，即workbench，地址为
https://[yourtenant].sharepoint.com/_layouts/15/workbench.aspx
完整的操作步骤如下：

1. 打开文件config\serve.json
2. 将initialPage的值修改为我们workbench的地址

“initialPage”: “https://[yourtenant].sharepoint.com/_layouts/15/workbench.aspx”,

3. 保存serve.json文件，在命令行执行命令gulp serve
4. 浏览器会打开并访问我们的workbench
5. 添加我们的web部件
6. 如果一切顺利，我们将看到类似下图的效果
   
   在编译web部件之后，我们可以通过执行命令gulp bundle –ship和gulp package-solution –ship来获得生产发布需要的包。
   在重新部署到应用程序目录时，不需要再次批准请求的权限。