设置和配置 SharePoint Embedded 环境和 Web 应用项目

• 14 分钟

在本练习中，你将创建一个包含服务器端和客户端组件的项目。 服务器端组件是一个 REST API，它使用 Microsoft Entra ID 进行身份验证，并将使用 Microsoft Graph API 访问 SharePoint Embedded Containers。 客户端组件是一个单页 React 应用，它将调用公开 SharePoint Embedded 容器内容的 REST API。

在本练习结束时，你将获得一个模板项目，用于在以下各节中添加更多功能。

在 Microsoft 365 SharePoint Online 租户中启用 SharePoint Embedded

若要使用 SharePoint Embedded 创建和注册容器类型，必须先在 SharePoint Online 租户上启用它。 必须在定义应用程序的提供程序和使用租户以及将使用 SharePoint Embedded 应用程序的任何使用租户上完成此过程。

在 SharePoint Online 租户上启用 SharePoint Embedded 是单向操作;无法禁用它。 这是为了确保你在使用租户上创建的任何应用将继续正常运行。

在 SharePoint Online 租户上启用 SharePoint Embedded 后，你将能够在提供程序租户中创建容器类型，并在使用租户中注册容器类型。

若要启用 SharePoint Embedded，请导航到 Microsoft 365 管理中心 (https://portal.microsoft.com) 并使用 Microsoft 365 租户管理员帐户 的工作和学校 登录。

选择左侧导航底部的“ 全部显示 ”，然后选择 “管理中心 > SharePoint”。

接下来，在 SharePoint 管理中心的左侧导航栏中选择“设置”。 找到并选择“SharePoint Embedded”。 查看服务条款，然后选择“ 启用” 以在 SharePoint Online 租户上启用它。

创建 Microsoft Entra ID 应用程序

首先创建 Microsoft Entra ID 应用程序。 这将用于进行身份验证并获取调用 Microsoft Graph 和 Microsoft SharePoint API 所需的权限。

打开浏览器并导航到 Microsoft Entra 管理中心， (https://entra.microsoft.com)。 使用对租户具有全局管理员权限的 工作或学校帐户 登录。

选择左侧导航中的 管理 > 应用注册，然后选择 新建注册。

在 “注册应用程序” 页上，按如下所示设置值，然后选择 “注册”:

• 名称：我的 SharePoint Embedded
• 支持的帐户类型：此组织目录中的帐户仅 (Andrew Connell Inc. - 单租户)

然后，Microsoft Entra ID 将显示新应用的详细信息。 创建一个文本文件，以跟踪稍后在本模块中需要的多个值。 将 应用程序 (客户端) ID & Directory (租户) ID 从应用的概述页复制到文本文件中。

配置身份验证

接下来，配置应用的身份验证设置。 在左侧导航中选择 管理 > 身份验证。

选择“ 添加平台 ”，然后选择“ 单页应用程序”。

在“配置单页应用程序”窗格中，将“重定向 URIhttp://localhost:3000”设置为 ，然后选择“配置”。

配置 API 权限

接下来，设置应用所需的权限，以便它可以创建和访问容器类型和容器。

在 “管理 > 清单” 页中，找到 属性 requiredResourceAccess。

设置为00000003-0000-0000-c000-000000000000 的现有资源resourceAppId是 Microsoft Graph。 为 FileStorageContainer.Selected 范围添加以下应用程序 & 委托权限。 现有权限适用于 User.Read 范围。

{
  "resourceAppId": "00000003-0000-0000-c000-000000000000",
  "resourceAccess": [
    {
      "id": "085ca537-6565-41c2-aca7-db852babc212",
      "type": "Scope"
    },
    {
      "id": "40dc41bc-0f7e-42ff-89bd-d9516947e474",
      "type": "Role"
    }
  ]
}

接下来，为 SharePoint 添加 ID 为 00000003-0000-0ff1-ce00-000000000000的新 resourceAppId ，并为 Container.Selected 范围添加以下应用程序 & 委托权限：

{
  "resourceAppId": "00000003-0000-0ff1-ce00-000000000000",
  "resourceAccess": [
    {
      "id": "4d114b1a-3649-4764-9dfb-be1e236ff371",
      "type": "Scope"
    },
    {
      "id": "19766c1b-905b-43af-8756-06526ab42875",
      "type": "Role"
    }
  ]
},

向 Microsoft Entra ID 应用添加自定义权限

接下来，向应用程序添加自定义权限，以便管理员可以提示用户允许应用管理容器。

在“管理>公开 API”页上，选择“应用程序 ID URI”旁边的“设置”链接。 这会将应用的 ID 默认设置为 api://<app-id>。

接下来，选择 “添加作用域” 以添加应用的新权限。 使用以下设置创建新作用域，然后选择 “添加作用域”:

• 范围名称： Container.Manage
• 谁可以同意? 仅限管理员
• 管理员 (& 用户) 同意标题： 管理 SharePoint Embedded 容器。
• 管理员 (& 用户) 同意说明： 应用程序可以调用此应用程序的 API 来管理 SharePoint 嵌入式存储容器。
• 状态: 已启用

在 Web API 中，你将添加代码，以确保已向应用程序授予此权限。

向管理员授予对新权限的同意

某些权限需要管理员同意。 从 “API 权限” 页中，滚动到页面底部，然后选择链接“ 企业应用程序”。

在 “权限 ”页上，选择“ 为 Contoso 授予管理员同意 ”，然后选择 “接受 向管理员授予管理员同意”的提示： “FileStorageContainer.Selected for Microsoft Graph”和 “Container.Selected for SharePoint”。 这两对表示应用程序 & 两个权限中每个权限的委托选项。

创建客户端密码

若要使应用使用具有 Microsoft Entra ID 的 OAuth2 客户端凭据流进行身份验证，它需要客户端 ID 和客户端密码。

在左侧导航中选择 管理 > 证书和密码。

在 “证书 & 机密 ”页上，选择“ 客户端机密 ”选项卡，然后选择“ 新建客户端密码”。 设置说明并选择过期持续时间，然后选择“ 添加”。

创建机密后，会显示一次机密，因此请确保将其作为客户端密码复制到本地文本文件中，以供稍后在本模块中使用。 如果不复制此值，则将不得不创建新密码，因为永远无法查看以前创建的密码。

创建容器类型

最后一步是创建新的容器类型。 可以使用 SharePoint Online PowerShell 模块完成此操作。 请确保通过安装...

Install-Module "Microsoft.Online.SharePoint.PowerShell"

...或者升级之前安装的版本，以确保你拥有最新版本...

Update-Module "Microsoft.Online.SharePoint.PowerShell"

获得最新版本后，连接到 SharePoint Online 网站并创建新的容器类型：

更新以下 PowerShell 脚本中的以下值，然后执行脚本：

• {{SPO_ADMIN_URL}}：这是 SharePoint Online 管理中心的 URL。 可以使用租户管理员帐户的工作和学校登录到 Microsoft 365 门户 (https://portal.microsoft.com)，选择左侧导航底部的“全部显示”，然后选择“管理中心 > SharePoint”来获取此权限。 复制 SharePoint 管理中心的 URL 并使用此值。 例如，如果租户 ID 为 Contoso123，则管理员 URL 将为 https://contoso123-admin.sharepoint.com。
• {{CONTAINER_TYPE_NAME}}：为新的容器类型选择一个名称。 例如，使用 MyFirstSpeContainerType。
• {{AZURE_ENTRA_APP_ID}}： 将此设置为 Microsoft Entra ID 应用 ID 的值，也称为之前创建的“客户端 ID”。 此值应位于本地文本文件中。

Import-Module "Microsoft.Online.SharePoint.PowerShell"
Connect-SPOService -Url "https://{{SPO_ADMIN_URL}}"
New-SPOContainerType -TrialContainerType
                     -ContainerTypeName "{{CONTAINER_TYPE_NAME}}"
                     -OwningApplicationId "{{AZURE_ENTRA_APP_ID}}"

PowerShell 脚本将显示新容器类型的详细信息，例如：

Container Type ID:
===============================================================================
ContainerTypeId     : 1e59a44b-b77e-051e-3cba-dbf83007b520
ContainerTypeName   : MyFirstSpeContainerType
OwningApplicationId : 520e6e65-1143-4c87-a7d3-baf242915dbb
Classification      : Trial
AzureSubscriptionId : 00000000-0000-0000-0000-000000000000
ResourceGroup       :
Region              :

ContainerTypeId复制本地文本文件供以后使用。

在使用租户中注册容器类型

最后，作为最后一步的一部分，需要在提供程序租户) 、使用者租户 () 中注册 当前定义的 容器类型 (。 这适用于单租户和多租户应用程序，并确保只有指定的应用程序有权访问其租户中的容器。

如果未完成此步骤，SharePoint Embedded 应用程序在尝试使用容器执行任何操作时，将收到 拒绝访问 错误。

使用 SharePoint Online REST API 注册容器类型。 SharePoint Online REST API 要求应用程序使用证书而不是客户端密码进行身份验证。

创建自签名证书

首先，使用 PowerShell 的 New-SelfSignedCertificate cmdlet 创建新的自签名证书。 更新以下 PowerShell 脚本中的以下值，然后执行脚本：

• {{CERT NAME}}：证书的名称。 这可以是你喜欢的任何内容。
• {{CERT_PATH}}： .cer 文件位置的完全限定路径，例如 c：\mycert.cer。

$cert = New-SelfSignedCertificate -Subject "CN={{CERT_NAME}}" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "{{CERT_PATH}}" -Force

# Private key to Base64
$privateKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$privateKeyBytes = $privateKey.Key.Export([System.Security.Cryptography.CngKeyBlobFormat]::Pkcs8PrivateBlob)
$privateKeyBase64 = [System.Convert]::ToBase64String($privateKeyBytes, [System.Base64FormattingOptions]::InsertLineBreaks)
$privateKeyString = @"
-----BEGIN PRIVATE KEY-----
$privateKeyBase64
-----END PRIVATE KEY-----
"@

# Print private key to output
Write-Host $privateKeyString

将 Base64 格式（也称为 PEM 格式）的私钥值保存到与生成的 *.cer 文件同名的新 *.key 文件中。

在 “管理 > 证书 & 机密 ”页上，选择“ 证书”，然后选择“ 上传证书”。 选择 “.cer ”文件，然后选择“ 添加”。

上传证书后，复制 Microsoft Entra ID 门户的“证书 & 机密”页上显示的指纹：

在使用者租户中注册容器类型

接下来，使用 SharePoint REST /_api/v2.1/storageContainerTypes/{{ContainerTypeId}}/applicationPermissions 终结点将容器类型注册到使用者的租户。 SharePoint Embedded 团队提供了一个 Postman 集合，其中包含许多调用不同 SharePoint Online & Microsoft Graph 终结点的示例，从而使这一点变得简单。

在 SharePoint Embedded Samples 存储库中，找到 Postman 集合，获取其原始 URL，并将其作为新集合导入 Postman：

请注意，集合概述包含大量文档。 一个重要部分介绍如何创建 Postman 环境文件以简化必要的值设置。 我已经创建了一个，只需填充值：

• ClientID：Microsoft Entra ID 应用程序的应用程序或客户端 ID。
• ClientSecret：Microsoft Entra ID 应用程序的客户端密码。
• ConsumingTenantId：要面向的使用者租户的 Microsoft 365 租户的 ID。
• TenantName：租户的名称。 这是 SharePoint Online 网站的子域部分。
• RootSiteUrl：租户的根 URL。
• ContainerTypeID：在提供程序租户中创建的容器类型的 GUID。
• CertThumbprint：成功将证书上传到 Microsoft Entra ID 应用程序后显示的证书 Microsoft Entra ID 的指纹。
• CertPrivateKey：证书的私钥。 这是 PEM 格式的密钥。

设置 Postman 集合和环境后，在“应用程序>容器”文件夹中运行 Register ContainerType 请求。 请求完成后，你将在本模块的其余部分中创建的应用将能够管理和访问 Microsoft 365 租户中的存储容器。

创建 Web 应用以访问 SharePoint Embedded Containers

通过提供程序和使用者租户中的 SharePoint Embedded 设置，包括创建和注册容器类型，下一步是创建应用程序。 此应用程序将包含两个项目：

• 用于生成和呈现前端 React SPA 应用的 Web 项目
• 一个服务器端 API，用于托管需要机密客户端的方法，该客户端将执行无法从客户端应用执行的操作。

首先，创建项目的前端部分：

创建前端应用程序

在命令行中，导航到要在其中创建应用程序的文件夹，并执行以下命令：

npx create-react-app my-first-spe-app --template typescript

接下来，安装 npm 包，以便使用 Microsoft Entra ID 实现 SPA 用户界面和身份验证。 在命令行中，移动到由上一个命令创建的 my-first-spe-app 文件夹，并执行以下命令：

npm install @azure/msal-browser @fluentui/react-components @fluentui/react-icons @microsoft/mgt-react @microsoft/mgt-element @microsoft/mgt-msal2-provider -SE

此命令将安装以下 npm 包：

• @azure/msal-browser：用于使用 Microsoft Entra ID 进行身份验证。
• @microsoft/mgt-element、 @microsoft/mgt-react & @microsoft/mgt-msal2-provider：包含 React UI 组件的 Microsoft Graph 工具包。
• @fluentui/react-components & @fluentui/react-icons：Fluent UI v9 库中的 UI 组件。

创建后端应用程序

接下来，为 API 服务器创建并添加必要的基架。 首先运行以下命令以安装更多 npm 包：

npm install restify @azure/msal-node @microsoft/microsoft-graph-client isomorphic-fetch jsonwebtoken jwks-rsa -SE

npm install @types/restify @types/jsonwebtoken @types/isomorphic-fetch -DE

此命令将安装 npm 包：

• restify & @types/restify：基于 Node.js API 服务器和 TypeScript 的关联类型声明。
• @azure/msal-node：用于使用 Microsoft Entra ID 进行身份验证。
• @microsoft/microsoft-graph-client：Microsoft Graph JavaScript SDK。
• 同构提取：将浏览器 fetch API 添加为全局的 Polyfill，以便其 API 在客户端 & 服务器之间保持一致。
• jsonwebtoken：JSON Web 令牌的实现。
• jwks-rsa：用于从 JWKS) 终结点 (JSON Web 密钥集检索签名密钥的库。

为服务器端项目添加 TypeScript 编译器配置：

• 创建一个新文件 ./server/tsconfig.json 项目，并向其添加以下代码。 这将为此项目的服务器端 API 部分配置 TypeScript 编译器。

  {
    "$schema": "http://json.schemastore.org/tsconfig",
    "compilerOptions": {
      "target": "ES2015",
      "module": "commonjs",
      "lib": [
        "es5",
        "es6",
        "dom",
        "es2015.collection"
      ],
      "esModuleInterop": true,
      "moduleResolution": "node",
      "strict": true
    }
  }
  

接下来，将服务器端 API 的占位符添加到此项目。

• 创建一个新文件 ./server/index.ts，并向其添加以下代码：

  import * as restify from "restify";
  
  const server = restify.createServer();
  server.use(restify.plugins.bodyParser());
  
  server.listen(process.env.port || process.env.PORT || 3001, () => {
    console.log(`\nAPI server started, ${server.name} listening to ${server.url}`);
  });
  
  // add CORS support
  server.pre((req, res, next) => {
    res.header('Access-Control-Allow-Origin', req.header('origin'));
    res.header('Access-Control-Allow-Headers', req.header('Access-Control-Request-Headers'));
    res.header('Access-Control-Allow-Credentials', 'true');
  
    if (req.method === 'OPTIONS') {
      return res.send(204);
    }
  
    next();
  });
  

这会创建新的 Restify 服务器，将其配置为侦听端口 3001 上的请求，并在服务器上启用 CORS。

添加项目全局设置和常量

接下来，添加几个常量以存储部署设置

• 创建一个新文件 ./.env 来存储 API 服务器的设置。 在文件中添加以下内容：

  API_ENTRA_APP_CLIENT_ID=
  API_ENTRA_APP_CLIENT_SECRET=
  API_ENTRA_APP_AUTHORITY=
  
  CONTAINER_TYPE_ID=
  

• 创建一个新文件 ./src/common/constants.ts 来存储客户端应用的设置。 在文件中添加以下内容：

  export const CLIENT_ENTRA_APP_CLIENT_ID = '';
  export const CLIENT_ENTRA_APP_AUTHORITY = '';
  
  export const API_SERVER_URL = '';
  
  export const CONTAINER_TYPE_ID = '';
  

使用以下指南更新这两个文件中的值：

• API_ENTRA_APP_CLIENT_ID：这是之前创建的 Microsoft Entra ID 应用程序的应用程序 (客户端) ID。
• API_ENTRA_APP_CLIENT_SECRET：这是之前创建的 Microsoft Entra ID 应用程序的应用程序 (客户端) 机密。
• API_ENTRA_APP_AUTHORITY：这是 Microsoft Entra ID 应用程序的授权。 使用 https://login.microsoftonline.com/{{MS-ENTRA-TENANT-ID}}/。 租户 ID 是以前创建应用程序的 Microsoft Entra ID 租户的 ID。
• API_SERVER_URL：这是服务器端 API 服务器的 URL。 使用 http://localhost:3001。
• CLIENT_ENTRA_APP_CLIENT_ID：这是之前创建的 Microsoft Entra ID 应用程序的应用程序 (客户端) ID。

最后，添加一个新文件 ./src/common/scopes.ts，以存储 OAuth2 范围列表， (权限) ，我们将在客户端应用程序中使用：

// microsoft graph scopes
export const GRAPH_USER_READ = 'User.Read';
export const GRAPH_USER_READ_ALL = 'User.Read.All';
export const GRAPH_FILES_READ_WRITE_ALL = 'Files.ReadWrite.All';
export const GRAPH_SITES_READ_ALL = 'Sites.Read.All';
export const GRAPH_OPENID_CONNECT_BASIC = ["openid", "profile", "offline_access"];

// SharePoint Embedded scopes
export const SPEMBEDDED_CONTAINER_MANAGE= 'Container.Manage';
export const SPEMBEDDED_FILESTORAGECONTAINER_SELECTED= 'FileStorageContainer.Selected';

为 API 服务器创建此文件的警察。 将复制的文件保存到项目中的以下位置： ./server/common/scopes.ts。

配置项目生成

现在，让我们对项目进行一些更改，以简化生成和测试。

更新脚本以简化项目的生成：

• 打开命令提示符，将当前文件夹设置为项目的根目录，并运行以下命令以安装开发中使用的几个 npm 包：

  npm install env-cmd npm-run-all -DE
  

• 找到并打开 ./package.json 文件，并将 scripts 节更新为以下内容：

  "scripts": {
    "build:backend": "tsc -p ./server/tsconfig.json",
    "start": "run-s build:backend start:apps",
    "start:apps": "run-p start:frontend start:backend",
    "start:frontend": "npm run start-cre",
    "start:backend": "env-cmd --silent -f .env node ./server/index.js",
    "start-cre": "react-scripts start",
    "build-cre": "react-scripts build",
    "test-cre": "react-scripts test",
    "eject-cre": "react-scripts eject"
  },
  

以下列表说明了脚本的用途：

• 所有默认 create-react-app (CRE) 脚本都已更新为在其名称中包含 -cre 后缀，以指示它们与 create-react-app 相关联。
• 启动脚本使用 npm-run-all npm 包中的 run-s 方法按顺序运行两个脚本：
  1. 它首先运行 生成 脚本，将整个项目从 TypeScript 转译为 JavaScript。
  2. 然后，它会运行脚本 start：apps。
• start：apps 脚本使用 npm-run-all npm 包中的 run-p 方法并行运行 start：frontend & start：backend 脚本。
• start：backend 脚本使用 env-cmd npm 包将 ./.env 文件中的环境变量注入 API 服务器进程。

此时，你有一个模板项目，你将使用该项目在以下部分中添加更多功能。

摘要

在本练习中，你创建了一个包含服务器端和客户端组件的项目。 服务器端组件是一个 REST API，它使用 Microsoft Entra ID 进行身份验证，并将使用 Microsoft Graph API 访问 SharePoint Embedded Containers。 客户端组件是一个单页 React 应用，它将调用公开 SharePoint Embedded 容器内容的 REST API。

知识检查

1.

SharePoint Embedded 允许开发人员执行哪些操作？

创建图形设计应用程序

创建视频编辑应用程序

使用 SharePoint 的功能创建以文件和文档为中心的应用程序

创建音乐制作应用程序

2.

OAuth v2.0 模型中的两种权限类型是什么？

读写

应用+用户 (委托) 和 App-Only (应用程序)

公共和专用

客户端和服务器

3.

OAuth 2.0 中代理流的用途是什么？

允许应用程序执行独立于用户的任务

限制应用程序对某些资源的访问

允许用户代表应用程序执行任务

允许应用程序代表用户执行任务，而无需登录每个操作

在检查工作前，必须回答所有问题。