使用 Microsoft Graph 构建 SharePoint 框架应用程序

项目
Developer (初级)
41 分钟可完成

本教程指导你构建一个SharePoint客户端 Web 部件，该部件使用 Microsoft Graph API 检索用户的日历信息。

提示

如果只想下载已完成的教程，可以下载或克隆GitHub存储库。

先决条件

在开始本教程之前，应在开发计算机上安装以下工具。

有关开发要求的详细信息，SharePoint 框架设置开发SharePoint 框架环境。

还应具有 Microsoft 工作或学校帐户，具有对同一组织中全局管理员帐户的访问权限。如果你没有 Microsoft 帐户，你可以注册 Microsoft 365 计划，获取免费的 Microsoft 365 订阅。

你的Microsoft 365租户应设置为进行SharePoint 框架开发，并创建一个应用程序目录和测试网站，然后再开始本教程。

备注

本教程是使用上述工具的以下版本编写的。本指南中的步骤可能与其他版本一起运行，但该版本尚未经过测试。

Node.js 14.15.0
Yeoman 4.1.0
Gulp 4.0.2
Yeoman SharePoint生成器 1.12.1

反馈

Please provide any feedback on this tutorial in the GitHub repository.

创建 SPFX web 部件

剩余 40 分钟

在本教程中，你将创建一个 SharePoint 客户端 Web 部件，该部件将使用 Microsoft Graph 获取用户本周的日历，并允许用户将事件添加到其日历。

创建 Web 部件项目

在要创建项目的空 (中) CLI 命令打开命令行接口。运行以下命令以启动 Yeoman SharePoint生成器。
```
yo @microsoft/sharepoint
```
响应提示，如下所示。
- 解决方案名称是什么？ graph-tutorial
- 你想要为你的组件设定哪些基准包？ SharePoint Online only (latest)
- 要将文件存放在哪里? Use the current folder
- 是否要允许租户管理员选择能够立即将解决方案部署到所有站点的选项，而无需运行任何站点中的部署或添加应用程序功能? Yes
- 解决方案中的组件是否需要访问唯一且不与租户中其他组件共享的 Web API 的权限? No
- 要创建哪种类型的客户端组件? WebPart
- Web 部件名称是什么? GraphTutorial
- Web 部件说明是什么? GraphTutorial description
- 要使用哪种框架? No JavaScript framework

安装依赖项

在继续之前，请安装一些你稍后将使用的其他 NPM 包。

Microsoft Graph TypeScript 定义来为 Microsoft Graph智能感知。
Microsoft Graph Toolkit为 Web 部件提供 UI 组件。
date-fns ，用于处理日期的有用函数。

npm install @microsoft/microsoft-graph-types@1.36.0 --save-dev
npm install @microsoft/mgt@2.1.0 date-fns @2.21.1

配置权限

剩余 35 分钟

此SharePoint 框架无需在应用程序中注册应用程序Azure AD获取访问令牌以访问 Microsoft Graph。它处理登录用户的身份验证，SharePoint Web 部件获取用户令牌。 Web 部件需要指示Graph权限范围，租户管理员可以在安装过程中批准这些权限。

配置权限

打开 ./config/package-solution.json。

将以下代码添加到 solution 属性。

"webApiPermissionRequests": [
  {
    "resource": "Microsoft Graph",
    "scope": "Calendars.ReadWrite"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "User.ReadBasic.All"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "Contacts.Read"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "People.Read"
  }
]

该Calendars.ReadWrite权限允许 Web 部件检索用户的日历，并添加使用 Microsoft Graph。其他权限由 Microsoft Graph Toolkit用于呈现有关事件参与者和组织者的信息。

可选：测试令牌获取

备注

此页上的其余步骤是可选的。如果你希望让 Microsoft Graph编码，可以继续查看获取日历视图。

让我们将一些临时代码添加到 Web 部件以测试令牌获取。

打开 ./src/webparts/graphTutorial/GraphTu一lWebPart.tsimport，在文件顶部添加以下语句。
```
import { AadTokenProvider } from '@microsoft/sp-http';
```

将现有的 render 函数替换为以下内容。

public render(): void {
  this.context.aadTokenProviderFactory
    .getTokenProvider()
    .then((provider: AadTokenProvider)=> {
    provider
      .getToken('https://graph.microsoft.com')
      .then((token: string) => {
        this.domElement.innerHTML = `
        <div class="${ styles.graphTutorial }">
          <div class="${ styles.container }">
            <div class="${ styles.row }">
              <div class="${ styles.column }">
                <span class="${ styles.title }">Welcome to SharePoint!</span>
                <p><code style="word-break: break-all;">${ token }</code></p>
              </div>
            </div>
          </div>
        </div>`;
      });
    });
}

部署 Web 部件

在 CLI 中运行以下两个命令以生成和打包 Web 部件。
```
gulp bundle --ship
gulp package-solution --ship
```
打开浏览器并转到租户的 SharePoint 应用程序目录。选择 左侧SharePoint 应用"菜单项。
Upload ./sharepoint/solution/graph-tutorial.sppkg 文件。
在"是否信任..."提示中，确认该提示列出了你在 package-solution.json Graph设置的 4 个 Microsoft 权限。选择 "使此解决方案对组织的所有网站都可用"， 然后选择"部署 "。
使用租户SharePoint转到管理中心。
在左侧菜单中，选择" 高级"，然后选择 "API 访问"。
Select each of the pending requests from the graph-tutorial-client-side-solution package and choose Approve.

测试 Web 部件。

转到要SharePoint Web 部件的网站。创建一个新页面以测试 Web 部件。
使用 Web 部件选取器查找 GraphTutorial Web 部件并将其添加到页面。
访问令牌将打印在欢迎使用 令牌SharePoint！ 消息。你可以复制此令牌，并分析它，以确认 https://jwt.ms/ 它包含 Web 部件所需的权限范围。

获取日历视图

剩余 25 分钟

The SharePoint 框架 provides the MSGraphClient for making calls to Microsoft Graph. 此类包装 Microsoft Graph JavaScript 客户端库，向当前登录的用户预先进行身份验证。

因为它包装了现有的 JavaScript 库，所以其用法相同，并且完全兼容 Microsoft Graph TypeScript 定义。

获取用户的日历

打开 ./src/webparts/graphTutorial/GraphTutorialWebPart.ts， 在文件顶部添加以下 import 语句。

import { MSGraphClient } from '@microsoft/sp-http';
import * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
import { startOfWeek, endOfWeek, setDay, set } from 'date-fns';

将以下函数添加到 GraphTu一lWebPart 类以呈现错误。

private renderGraphError(error: any): void {
  const viewContainer = this.domElement.querySelector('#calendarView');

  // Basic error display
  viewContainer.innerHTML = `
  <h2 class="${ styles.title }">Error</h2>
  <code style="word-break: break-all;">${JSON.stringify(error, null, 2)}</code>`;
}

添加以下函数以打印用户日历中的事件。

private renderCalendarView(events: MicrosoftGraph.Event[]) : void {
  const viewContainer = this.domElement.querySelector('#calendarView');
  let html = '';

  // Temporary: print events as a list
  for(const event of events) {
    html += `
      <p class="${ styles.description }">Subject: ${event.subject}</p>
      <p class="${ styles.description }">Organizer: ${event.organizer.emailAddress.name}</p>
      <p class="${ styles.description }">Start: ${event.start.dateTime}</p>
      <p class="${ styles.description }">End: ${event.end.dateTime}</p>
      `;
  }

  viewContainer.innerHTML = html;
}

将现有的 render 函数替换为以下内容。

public render(): void {
  this.context.msGraphClientFactory
    .getClient()
    .then((graphClient: MSGraphClient)=> {
      // Get current date
      const now = new Date();
      // Get the start and end of the week based on current date
      const weekStart = startOfWeek(now);
      const weekEnd = endOfWeek(now);

      graphClient
        .api(`/me/calendarView?startDateTime=${weekStart.toISOString()}&endDateTime=${weekEnd.toISOString()}`)
        .select('subject,organizer,start,end,location,attendees')
        .orderby('start/dateTime')
        .top(25)
        .get((error: any, events: any) => {
          this.domElement.innerHTML = `
          <div class="${ styles.graphTutorial }">
            <div class="${ styles.container }">
              <div class="${ styles.row }">
                <div class="${ styles.column }">
                  <div id="calendarView" />
                </div>
              </div>
            </div>
          </div>`;

          if (error) {
            this.renderGraphError(error);
          } else {
            this.renderCalendarView(events.value);
          }
        });
    });
}

请注意此代码执行哪些功能。

它使用 this.context.msGraphClientFactory.getClient 获取经过身份验证的 MSGraphClient 对象。
它调用 /me/calendarView 终结点，将和查询参数设置为本周的开始 startDateTime endDateTime 和结束。
它 select 用于限制返回的字段，仅请求应用程序使用的字段。
它 orderby 使用按事件的开始时间对事件进行排序。
它 top 使用将结果限制为 25 个事件。

部署 Web 部件

在 CLI 中运行以下两个命令以生成和打包 Web 部件。
```
gulp bundle --ship
gulp package-solution --ship
```
打开浏览器并转到租户的 SharePoint 应用程序目录。选择 左侧SharePoint 应用"菜单项。
Upload ./sharepoint/solution/graph-tutorial.sppkg 文件。
在 "是否信任..." 提示中，确认该提示列出了在"Graph on"文件中设置的 4package-solution.js 权限。选择 "使此解决方案对组织的所有网站都可用"， 然后选择"部署 "。
如果尚未批准 Web Graph权限，则现在执行这一操作。
1. 使用租户SharePoint转到管理中心。
2. 在左侧菜单中，选择"高级"， 然后选择 "API 访问"。
3. Select each of the pending requests from the graph-tutorial-client-side-solution package and choose Approve.

测试 Web 部件

转到要SharePoint Web 部件的网站。创建一个新页面以测试 Web 部件。
使用 Web 部件选取器查找 GraphTutorial Web 部件并将其添加到页面。
在 Web 部件中打印本周的事件列表。

添加 Microsoft Graph 工具包

剩余 15 分钟

在此部分中，你将使用Microsoft Graph Toolkit将简单的事件列表替换为丰富的 UI。

该工具包提供一个"议程"组件，它非常适合呈现我们的事件列表。

更新 Web 部件

打开 ./src/webparts/graphTutorial/GraphTutorialWebPart.module.scss。将条目中的 background-color 属性的值更改为 .row $ms-color-white 。
```
.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-white;
  padding: 20px;
}
```
在条目中添加以下 .graphTutorial 条目。
```
#addSocialBtn {
  margin-bottom: 1em;
}
```
打开 ./src/webparts/graphTutorial/GraphTu一lWebPart.ts， 在文件顶部 import 添加以下语句。
```
import { Providers, SharePointProvider, MgtAgenda } from '@microsoft/mgt';
```

将以下函数添加到 GraphTu一lWebPart 类以初始化工具包。

protected async onInit() {
  // Set the toolkit's global auth provider to
  // SharePoint provider, allowing it to use the Graph
  // access token
  Providers.globalProvider =
    new SharePointProvider(this.context);
}

将现有的 renderCalendarView 函数替换为以下内容。

private renderCalendarView(events: MicrosoftGraph.Event[]) : void {
  const viewContainer = this.domElement.querySelector('#calendarView');

  // Create an agenda component from the toolkit
  let agenda = new MgtAgenda();
  // Set the events
  agenda.events = events;
  // Group events by day
  agenda.groupByDay = true;

  viewContainer.appendChild(agenda);
}

这会将基本列表替换为工具包中的 "议程 "组件。

生成、打包和重新上载 Web 部件，然后刷新测试它的页面。

备用方法

此时，您具有代码：

使用 MSGraphClient 从 Microsoft Graph 获取用户本周的日历视图。
将这些事件从 Microsoft 组织添加到议程 Graph Toolkit。

通过此方法，你可以完全控制 Graph API 调用，并且可以在呈现需要之前对事件执行任何处理。但是，如果这不是必需的，则可以通过让议程组件执行你的工作来简化。

所有 Microsoft Graph Toolkit 组件都能够对 Microsoft 应用执行所有相关 API Graph。例如，通过将议程组件添加到Web 部件，而不是设置任何属性，Web 部件将使用其默认设置获取当天的事件。让我们看一下如何获得与本周事件 (当前事件相同的) 。

将现有 render 方法替换为以下内容。

public render(): void {
  // Get current date
  const now = new Date();
  // Get the start of the week based on current date
  const weekStart = startOfWeek(now);

  this.domElement.innerHTML = `
  <div class="${ styles.graphTutorial }">
    <div class="${ styles.container }">
      <div class="${ styles.row }">
        <div class="${ styles.column }">
          <button class="${ styles.button }" id="${ styles.addSocialBtn }">
            <span class="${ styles.label }">Add team social</span>
          </button>
          <mgt-agenda
            date="${weekStart.toISOString()}"
            days="7"
            group-by-day></mgt-agenda>
        </div>
      </div>
    </div>
  </div>`;

  this.domElement.querySelector(`#${styles.addSocialBtn}`)
    .addEventListener('click', this.addSocialToCalendar.bind(this));
}

现在，无需在中调用 render API，只需将元素 mgt-agenda 直接添加到 HTML 中。通过设置为每周开始，并设置为 7，组件将进行与上一版本相同的 date days API render 调用。

将以下空函数添加到 GraphTu一lWebPart 类。
```
private async addSocialToCalendar() {}
```
备注

我们还向 Web 部件添加了" 添加团队社交"按钮，并添加了 addSocialToCalendar 方法作为事件侦听器。你将在下一节中实现隐藏代码。现在，我们只想编译代码。
生成、打包和重新上载 Web 部件，然后刷新测试它的页面。视图应该与上一个测试相同。

使用工具包与进行 API 调用

此时，你可能想知道为什么在工具包为用户完成此操作时遇到 使用 MSGraphClient 的问题。该工具包旨在呈现从 Microsoft 查询的结果Graph，如事件列表。但是，在某些情况下，需要自己调用 API。

任何不是请求的 API GET 调用。例如，在日历上创建新事件或更新用户的电话号码。
API 调用，获取旨在"在后台"使用且未直接呈现的数据。

创建新事件

剩余 5 分钟

在此部分中，你将更新 Web 部件，以允许用户将事件添加到团队每周社交小时的日历中。在此方案中，团队每周的社交小时是星期五下午 4 点。

打开 ./src/webparts/graphTu一l/GraphTu一lWebPart.ts， 将现有 addSocialToCalendar() 方法替换为以下内容。

private async addSocialToCalendar() {
  const graphClient = await this.context.msGraphClientFactory.getClient();

  // Get current date
  const now = new Date();

  // Set start time to next Friday
  // at 4 PM
  const socialHourStart = set(
    setDay(now, 5),
    {
      hours: 16,
      minutes: 0,
      seconds:0,
      milliseconds: 0
    });

  // Create a new event
  const socialHour: MicrosoftGraph.Event = {
    subject: 'Team Social Hour',
    body: {
      contentType: 'text',
      content: 'Come join the rest of the team for our end-of-week social hour.'
    },
    location: {
      displayName: 'Break room'
    },
    start: {
      dateTime: socialHourStart.toISOString(),
      timeZone: 'UTC'
    },
    end: {
      dateTime: set(socialHourStart, { hours: 17 }).toISOString(),
      timeZone: 'UTC'
    }
  };

  try {
    // POST /me/events
    await graphClient
      .api('/me/events')
      .post(socialHour);

    // Refresh the view
    this.render();
  } catch (error) {
    this.renderGraphError(error);
  }
}

考虑此代码执行哪些功能。

它确定下一个星期五，并构造当天下午4 点的日期。
它构建一个新的 MicrosoftGraph.Event 对象，将开始设置为 Date 的值，将结束设置为一小时后结束。
它使用 MSGraphClient 将新事件 POST 到 /me/events 终结点。
它将重新呈现 Web 部件，以便使用新事件更新视图。

生成、打包和重新上载 Web 部件，然后刷新测试它的页面。
单击" 添加团队社交" 按钮。刷新页面后，向下滚动到星期五并查找新事件。

使用 Microsoft Graph 构建 SharePoint 框架应用程序

先决条件

反馈

创建 SPFX web 部件

创建 Web 部件项目

安装依赖项

配置权限

配置权限

可选：测试令牌获取

部署 Web 部件

测试 Web 部件。

获取日历视图

获取用户的日历

部署 Web 部件

测试 Web 部件

添加 Microsoft Graph 工具包

更新 Web 部件

备用方法

使用工具包与进行 API 调用

创建新事件

恭喜！

反馈