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 = `
    <mgt-person person-query="me" show-name show-email></mgt-person>
    <mgt-agenda></mgt-agenda>
  `;
}

七、編譯解決方案

在使用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來獲得生產發佈需要的包。
   在重新部署到應用程序目錄時，不需要再次批准請求的權限。