通过网站脚本调用 PnP 预配引擎

2023-09-13

注意

此文章使用发布于 2021 年 1 月的最新版本 PnP PowerShell。因为 Azure Functions 运行 Windows PowerShell Core，你需在你的 Azure Function 中使用这个版本的 PnP PowerShell。有关此版本的 PnP PowerShell 的详细信息，请参阅 https://pnp.github.io/powershell。

借助网站设计，可以有效地标准化网站集的外观。不过，有些操作无法通过网站设计完成，如向每个页面添加页脚。可以使用 PnP 预配引擎来创建模板，将应用程序自定义工具预配到网站。然后，此应用程序自定义工具可以更新页面设计，例如，在每个页面上注册页脚。

本文将介绍如何创建将 PnP 预配模板应用到网站的网站设计。此模板将添加用于呈现页脚的应用自定义工具。

若要执行本文中的步骤，请使用以下组件：

网站设计和网站脚本
Power Automate
Azure 队列存储
Azure 函数
SharePoint 框架 (SPFx) 解决方案
PnP 网站模板
PnP PowerShell 脚本
Azure AD 应用注册

创建网站和应用网站设计后，将使用这些组件触发 PnP 预配代码。

注意

PnP 预配框架 & PnP 预配引擎是开放源代码解决方案，其活动社区为其提供支持。没有用于 Microsoft 开放源代码工具支持的 SLA。

设置对租户的仅限应用访问权限

在本教程中，我们将使用客户端 ID 和证书进行身份验证。

在你的电脑上用 PnP PowerShell 创建一个新的自签名的证书：
```
Register-PnPAzureADApp -ApplicationName "PnPFlowDemo" -Tenant "contoso.onmicrosoft.com" -DeviceLogin -Out .
```
用你的租户替代 contoso.onmicrosoft.com。

请仔细遵循步骤。

此命令的结果是，一个新的 Microsoft Azure AD Application 将被注册，将设置正确的访问权限，你将提供在你的租户处使用此应用的许可。注意，为此你需要 Azure AD 的写入权限。
复制 cmdlet 返回的值，因为你之后会需要 pfx 文件和 AzureAppld 值。

创建 Azure 队列存储

此部分将介绍如何使用 Azure 队列存储，接收 Power Automate 发送的消息。每当队列存储中有消息显示时，就会触发 Azure 函数，以运行 PowerShell 脚本。

若要设置 Azure 队列存储，请执行以下操作：

转到 Azure 门户并登录。
选择 + 创建资源。
从 Azure Marketplace 列表中选择“存储”，再在“特别推荐”列中，选择“存储帐户 - Blob、文件、表、队列”。
输入必填字段的值。依次选择“固定到仪表板”和“创建”。创建存储帐户可能需要几分钟时间才能完成。
打开存储帐户，并转到“队列”。
选择屏幕顶部的“+ 队列”。
输入“pnpprovisioningqueu”作为名称，或输入自己的值（请务必遵循命名标准）。记录队列名称（将需要在创建 Azure 函数时使用此值）。
转到“访问密钥”，并记录“存储帐户名称”和“key1 密钥值”。将需要在创建流时使用这些值。

创建流

注意

下面使用 的请求 触发器现在是 高级触发器 ，因此需要额外的许可。

若要在队列中添加消息，需要创建流。

转到 Power Automate 网站并登录，再选择页面顶部的“从空白创建”。
选择“搜索数百个连接器和触发器”，以选择触发器。
搜索 “请求”，然后选择“ 请求 - 收到 HTTP 请求时[高级]”。

输入以下 JSON 作为请求正文：

{
    "type": "object",
    "properties": {
        "webUrl": {
            "type": "string"
        },
        "parameters": {
            "type": "object",
            "properties": {
                "event": {
                    "type": "string"
                },
                "product": {
                    "type": "string"
                }
            }
        }
    }
}

依次选择“+ 新步骤”和“添加操作”。
搜索“Azure 队列”，再选择“Azure 队列 - 将消息放入队列”。
输入连接的描述性名称。
输入在上一部分中复制的存储帐户名称。
输入存储共享密钥，即存储帐户的“Key1 密钥值”字段值。
选择“创建”。
选择“pnpprovisioningqueue”作为队列名称。
在请求正文中，指定了“webUrl”传入参数。若要在队列中放入此字段值，请单击“消息”字段，再从动态内容选取器中选择“webUrl”。
选择“保存流”。这会生成将在下一步中复制的 URL。
选择流中的第一步（“当收到 HTTP 请求时”），并复制 URL。
保存流。

流应如下所示：

“当收到 HTTP 请求时”流的屏幕截图，其中显示 URL、请求正文、“队列名称”和“消息”字段

测试流

若要测试流，必须发出 POST 请求。可以通过 PowerShell 执行此操作，如下面的示例所示。

$uri = "[the URI you copied in step 14 when creating the flow]"
$body = "{webUrl:'somesiteurl'}"
Invoke-RestMethod -Uri $uri -Method Post -ContentType "application/json" -Body $body

转到流的主屏幕时，将看到运行历史记录。如果流运行正常，它将显示“Succeeded”。现在，转到刚刚在 Azure 中创建的队列，再选择“刷新”。应看到一项，指明已正确调用流。

预配 SPFx 解决方案

在此部分中，将使用现有 SPFx 解决方案区域页脚应用自定义工具。按照示例存储库中自述文件内的步骤操作，生成和预配解决方案。

创建 PnP 预配模板

将以下预配模板 XML 复制到新文件中，并将文件另存为 FlowDemoTemplate.xml。

<?xml version="1.0"?>
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2017/05/ProvisioningSchema">
  <pnp:Preferences Generator="OfficeDevPnP.Core, Version=2.20.1711.0, Culture=neutral, PublicKeyToken=3751622786b357c2" />
  <pnp:Templates ID="CONTAINER-FLOWDEMO">
    <pnp:ProvisioningTemplate ID="TEMPLATE-FLOWDEMO" Version="1" BaseSiteTemplate="GROUP#0" Scope="RootSite">
      <pnp:CustomActions>
        <pnp:WebCustomActions>
          <pnp:CustomAction Name="spfx-react-app-customizer" Description="Custom action for Application Customizer" Location="ClientSideExtension.ApplicationCustomizer" Title="spfx-react-app-customizer" Sequence="0" Rights="" RegistrationType="None" ClientSideComponentId="67fd1d01-84e8-4fbf-85bd-4b80768c6080" ClientSideComponentProperties="{&quot;SourceTermSetName&quot;:&quot;Regions&quot;}" />
        </pnp:WebCustomActions>
      </pnp:CustomActions>
    </pnp:ProvisioningTemplate>
  </pnp:Templates>
</pnp:Provisioning>

注意

预配模板将自定义操作添加到解决方案。 ClientSideComponentId 与之前预配的区域页脚应用自定义工具相关联。如果使用自己的 SPFx 解决方案运行此演示，请更改 XML 中的 ClientSideComponentId 和（可选）ClientSideComponentProperties 属性值。

创建 Azure 函数

转到“Azure 门户”。
选择 + 创建资源。
搜索“函数应用”，并新建函数应用。在“存储”字段中，依次选择“使用现有”和之前创建的存储帐户。按要求设置其他值，但是确保选择 PowerShell Core 为运行时，并选择 7.0 为版本
创建时。导航至你的新 Function APP
选择应用文件
在下拉菜单中，选择 requirements.psd1然后如下所示添加一个新项
```
# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/Az'.
    'Az' = '5.*'
    # For the latest supported version, go to 'https://www.powershellgallery.com/packages/PnP.PowerShell'.
    'PnP.PowerShell' = '1.*'
}
```
保存文件。注意，如果你不想使用 Azure PowerShell Cmdlets，你可以将那个项从文件中删除。 requirements.psd1 文件确保特定的 PowerShell 模块将会对所有函数可用。 Azure Function 的第一次执行时这些模块将会下载并可用。你也可以在此版本中使用通配符引用。请参阅有关此文件的详细信息。
新建新的 Azure Functions Functions>添加:
创建一个新的 Azure 存储队列触发器函数：
将函数命名为“InvokePnPSiteTemplate”。
输入之前创建的队列的名称。
选择“添加”。新页面打开，你可以在上面修改函数。

注意

存储帐户必须与 Azure 函数应用所在的区域相同，因为相互通信的资源应共同位于同一区域中。这是 Azure Functions 的必要条件。

完成 Azure 函数

转到 Function APP 的主屏幕并选择左边菜单的“高级工具”，然后点击“转到”。新选项卡将会打开。
从顶部的 “Debug Console” 菜单选择 “PowerShell”。
导航到 site\wwwroot\InvokePnPSiteTemplate (或 site\wwwroot[函数的名称])
拖放之前创建的 FlowDemoTemplate.xml 文件到页面里。这会将文件上传到文件夹。
拖放之前生成的 cert.pfx 文件到页面里。这会将文件上传到文件夹。
导航回到函数并选择 “Code + Test” 来编辑函数。

将 PowerShell 脚本替换为以下代码：

param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and insertion time to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Connect-PnPOnline -ClientId [insertyourAzureAppIdhere] -CertificatePath D:\home\site\wwwroot\InvokePnPSiteTemplate\cert.pfx -Tenant 'contoso.onmicrosoft.com' -Url $QueueItem
Write-Output "Connected to site"
Invoke-PnPSiteTemplate -Path D:\home\site\wwwroot\InvokePnPSiteTemplate\FlowDemoTemplate.xml

用Register-PnPAzureApp cmdlet 为 AzureAppId 返回的值代替 [insertyourAppIdHere]。

将 "contoso.onmicrosoft.com" 替换为租户详细信息。

创建网站设计

打开 PowerShell 并用 Connect-PnPOnline 连接到你的租户。

Connect-PnPOnline -Url https://[yourtenant]-admin.sharepoint.com

现在可以获取现有网站设计。

Get-PnPSiteDesign

若要创建网站设计，首先需要创建网站脚本。网站设计是引用一个或多个网站脚本的容器。

将以下 JSON 代码复制到剪贴板并进行修改。将 url 属性设置为创建流时复制的值。此 URL 如下所示：

https://prod-27.westus.logic.azure.com:443/workflows/ef7434cf0d704dd48ef5fb6...oke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun

{
    "$schema": "schema.json",
    "actions": [
    {
            "verb": "triggerFlow",
            "url": "[paste the workflow trigger URL here]",
            "name": "Apply Template",
            "parameters": {
                "event":"",
                "product":""
            }
    }
    ],
    "bindata": {},
    "version": 1
}

再次选择 JSON 并将它复制到剪贴板。

打开 PowerShell 并输入以下代码，将脚本复制到变量中并创建网站脚本：

$script = Get-Clipboard -Raw
Add-PnPSiteScript -Title "Apply PnP Site Template" -Content $script
Get-PnPSiteScript

将会看到包含一个或多个网站脚本的列表，包括刚刚创建的网站脚本。选择所创建的网站脚本的 ID，并将它复制到剪贴板。

使用以下命令创建网站设计：

Add-PnPSiteDesign -Title "Site with footer" -SiteScriptIds [Paste the ID of the Site Script here] -WebTemplate TeamSite

验证结果

创建 Azure 队列存储后，创建了应用 ID（已设置仅限应用访问）、Azure 函数和网站设计。然后，通过网站设计触发 Power Automate。

若要测试结果，请新建一个网站。在 SharePoint 租户中，依次选择“SharePoint”>“创建网站”>“团队网站”。新建的网站设计应显示为设计选项。请注意，网站设计在网站创建后应用。如果正确配置了它，流将获得触发。可以查看流的运行历史记录，以验证它是否正常运行。请注意，页脚可能不会立即显示；如果没有看到页脚，请稍等一下，重载网站以再次检查一下。

通过