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

在本练习中，你将创建一个包含服务器端和客户端组件的项目。 服务器端组件是一个 REST API，它通过 Microsoft Entra ID 进行身份验证，并将使用 Microsoft 图形 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 的现有资源resourceAppIdMicrosoft 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 嵌入式容器。
• 管理员 (&用户) 同意说明：应用程序可以调用此应用程序的 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 图形 API 访问 SharePoint Embedded Containers。 客户端组件是一个单页React应用程序，它将调用公开 SharePoint Embedded 容器内容的 REST API。