Aufrufen des PnP-Bereitstellungsmoduls über ein Websiteskript

  • Artikel

Hinweis

Dieser Beitrag verwendet die neueste Version von PnP PowerShell, die im Januar 2021 veröffentlicht wird. Da Azure Functions PowerShell Core ausführen, müssen Sie diese Version von PNP PowerShell in Ihrer Azure-Funktion verwenden. Weitere Informationen zu dieser Version von PNP PowerShell finden Sie unter https://pnp.github.io/powershell.

Websitedesigns sind eine hervorragende Möglichkeit, das Aussehen und Verhalten Ihrer Websitesammlungen zu standardisieren. Bestimmte Dinge lassen sich mit Websitedesigns jedoch nicht umsetzen. Beispielsweise ist es nicht möglich, jeder Seite eine Fußzeile hinzuzufügen. Mit dem PnP-Bereitstellungsmodul können Sie eine Vorlage erstellen, mit der Sie einen Application Customizer für eine Website bereitstellen können. Dieser Application Customizer kann dann Ihr Seitendesign aktualisieren, um beispielsweise eine Fußzeile auf jeder Seite zu registrieren.

In diesem Artikel wird beschrieben, wie Sie ein Websitedesign erstellen können, das eine PnP-Bereitstellungsvorlage auf eine Website anwendet. Die Vorlage wird einen Application Customizer hinzufügen, der eine Fußzeile rendert.

In der Anleitung in diesem Artikel verwenden wir die folgenden Komponenten:

  • Ein Websitedesign und ein Websiteskript
  • Power Automate
  • Azure Queue-Speicher
  • Azure Functions
  • Eine SharePoint-Framework-Lösung (SPFx-Lösung)
  • Eine PnP-Sitevorlage
  • Ein PnP-PowerShell-Skript
  • Eine Azure AD-App-Registrierung

Mithilfe dieser Komponenten wird der PnP-Bereitstellungscode ausgelöst, sobald Sie die Website erstellt und das Websitedesign angewendet haben.

Hinweis

Das PnP-Bereitstellungsframework & PnP-Bereitstellungsmodul sind Open-Source-Lösungen mit aktiver Community, die unterstützung dafür bereitstellt. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Einrichten von App-exklusivem Zugriff auf Ihren Mandanten

In diesem Tutorial verwenden wir die Authentifizierung mit einer Client-ID und einem Zertifikat.

  1. Erstellen Sie ein neues selbstsigniertes Zertifikat mit PNP PowerShell auf Ihrem Computer:

    Register-PnPAzureADApp -ApplicationName "PnPFlowDemo" -Tenant "contoso.onmicrosoft.com" -DeviceLogin -Out .

    Ersetzen Sie contoso.onmicrosoft.com mit Ihrem Mandanten.

    Führen Sie die beschriebenen Schritte sorgfältig aus.

    Als Ergebnis des Befehls wird eine neue Azure AD-Anwendung registriert, Berechtigungen werden ordnungsgemäß festgelegt sein, und Sie werden der Verwendung dieser Anwendung in Ihrem Mandanten zugestimmt haben. Beachten Sie, dass Sie dafür Schreibzugriff auf Azure AD benötigen.

  2. Kopieren Sie die Werte, die das Cmdlet zurückgibt, da Sie die PFX-Datei und den AzureAppId-Wert später benötigen werden.

Erstellen des Azure Queue-Speichers

In diesem Szenario verwenden wir Azure Queue Storage als Empfänger für Power Automate-Nachrichten. Wann immer eine Nachricht im Queue-Speicher angezeigt wird, wird eine Azure-Funktion ausgelöst, die ein PowerShell-Skript ausführt.

So richten Sie den Azure Queue-Speicher ein

  1. Rufen Sie das Azure-Portal auf, und melden Sie sich an.
  2. Wählen Sie + Ressource erstellen.
  3. Wählen Sie aus den Azure Marketplace-Angeboten die Option Storage aus. Klicken Sie in der Spalte „Empfohlen“ auf Speicherkonto – Blob, Datei, Tabelle, Warteschlange.
  4. Tragen Sie Werte in die Pflichtfelder ein. Klicken Sie auf Pin to dashboard und anschließend auf Erstellen. Es kann einige Minuten dauern, bis das Speicherkonto erstellt wird.
  5. Öffnen Sie das Speicherkonto, und klicken Sie auf Warteschlangen.
  6. Klicken Sie oben im Bildschirm auf + Warteschlange.
  7. Geben Sie als Namen pnpprovisioningqueue oder einen eigenen Wert ein. Beachten Sie dabei auf jeden Fall die Namenskonvention. Notieren Sie sich den Namen der Warteschlange; Sie benötigen diesen Wert, wenn Sie die Azure-Funktion erstellen.
  8. Klicken Sie auf Zugriffsschlüssel, und notieren Sie sich die Werte für Speicherkontoname sowie key1 Key value. Sie benötigen diese Werte, wenn Sie den Flow erstellen.

Erstellen des Flows

Hinweis

Der unten verwendete Anforderungstrigger ist jetzt Premium und erfordert daher eine zusätzliche Lizenzierung.

Damit Nachrichten in die Warteschlange gestellt werden können, müssen Sie zunächst einen Flow erstellen.

  1. Gehen Sie zur Power Automate-Website, melden Sie sich an, und wählen Sie oben auf der Seite Aus leerem erstellen aus.

  2. Klicken Sie auf Hunderte von Connectors und Triggern durchsuchen, um einen Trigger auszuwählen.

  3. Suchen Sie nach Anforderung, und wählen Sie Anforderung – Beim Empfang einer HTTP-Anforderung [Premium] aus.

  4. Geben Sie den folgenden JSON-Code als Anforderungstext ein:

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

  5. Klicken Sie auf + Neuer Schritt und anschließend auf Aktion hinzufügen.

  6. Suchen Sie nach Azure-Warteschlangen, und wählen Sie Azure-Warteschlangen - Nachricht in einer Warteschlange ablegen aus.

  7. Geben Sie einen aussagekräftigen Namen für die Verbindung ein.

  8. Geben Sie den Namen des Speicherkontos ein, den Sie sich im vorherigen Abschnitt notiert haben.

  9. Geben Sie den freigegebenen Speicherschlüssel ein, also den Wert aus dem Feld Key1 key value in Ihrem Speicherkonto.

  10. Klicken Sie auf Erstellen.

  11. Geben Sie pnpprovisioningqueue als Namen für die Warteschlange ein.

  12. Im Anforderungstext haben Sie einen Eingangsparameter webUrl angegeben. Der Wert dieses Felds soll in die Warteschlange gestellt werden. Klicken Sie dazu in das Feld Nachricht, und wählen Sie aus der dynamischen Inhaltsauswahl die Option webUrl aus.

  13. Klicken Sie auf Flow speichern. Es wird eine URL generiert. Diese URL notieren Sie sich im nächsten Schritt.

  14. Klicken Sie auf den ersten Schritt in Ihrem Flow („Beim Empfang einer HTTP-Anforderung“), und notieren Sie sich die URL.

  15. Speichern Sie Ihren Flow.

Ihr Flow sollte in etwa wie folgt aussehen:

Screenshot eines Flows mit dem Namen „Beim Empfang einer HTTP-Anforderung“, mit den Feldern „URL“, „Anforderungstext“, „Warteschlangenname“ und „Nachricht“

Testen des Flows

Zum Testen Ihres Flows müssen Sie eine POST-Anforderung senden. Das können Sie über die PowerShell tun, wie im Beispiel unten demonstriert:

$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

Wenn Sie zum Hauptbildschirm des Flows wechseln, sehen Sie einen Ausführungsverlauf. Wurde Ihr Flow korrekt ausgeführt, wird Succeeded angezeigt. Navigieren Sie nun zu der Warteschlange, die Sie soeben in Azure erstellt haben, und klicken Sie auf Aktualisieren. Sie sollten nun einen Eintrag sehen. Ist das der Fall, wurde der Flow korrekt aufgerufen.

Bereitstellen der SPFx-Lösung

In diesem Abschnitt verwenden Sie eine vorhandene SPFx-Lösung, den Regions Footer Application Customizer. Befolgen Sie die Anleitung in der Datei Readme im Beispielrepository, um die Lösung zu erstellen und bereitzustellen.

Erstellen einer PnP-Bereitstellungsvorlage

Kopieren Sie die folgende XML-Bereitstellungsvorlage in eine neue Datei, und speichern Sie die Datei als „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>

Hinweis

Die Bereitstellungsvorlage fügt einer Lösung eine benutzerdefinierte Aktion hinzu. Dabei ist ClientSideComponentId mit dem Regions Footer Application Customizer verknüpft, den Sie zuvor bereitgestellt haben. Wenn Sie diese Demo mit einer eigenen SPFx-Lösung ausführen, müssen Sie im XML-Code den Wert von ClientSideComponentId und optional auch die Attributwerte von ClientSideComponentProperties ändern.

Erstellen der Azure-Funktion

  1. Rufen Sie das Azure-Portal auf.

  2. Wählen Sie + Ressource erstellen.

  3. Suchen Sie nach Funktionen-App, und erstellen Sie eine neue Funktionen-App. Wählen Sie im Feld Speicher die Option Use existing aus. Wählen Sie dann das Speicherkonto aus, das Sie zuvor erstellt haben. Legen Sie die anderen Werte wie erforderlich fest, aber stellen Sie sicher, dass Sie PowerShell Core als Runtime auswählen, und wählen Sie 7.0 als Version aus.

    Screenshot des Azure-Portals mit hervorgehobenen Feldern für Runtime-Stack und Version

  4. Wechseln Sie nach der Erstellung zur neuen Function-App.

  5. Wählen Sie App-Dateien aus.

    Screenshot der Function-App mit hervorgehobenem Eintrag

  6. Wählen Sie im Dropdownmenü requirements.psd1 aus, und fügen Sie einen neuen Eintrag wie folgt hinzu:

    # 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.*'
}

    Speichern Sie die Datei. Wenn Sie nicht vorhaben, die Azure PowerShell-Cmdlets zu verwenden, können Sie diesen Eintrag aus dieser Datei entfernen. Über die Datei "requirements.psd1" wird sichergestellt, dass bestimmte PowerShell-Module für alle Funktionen zur Verfügung stehen. Bei der ersten Ausführung der Azure-Funktion werden diese Module heruntergeladen und verfügbar gemacht. Sie können auch Platzhalterbezüge für die Version verwenden. Weitere Informationen zu dieser Datei.

  7. Erstellen Sie eine neue Azure-Funktion Funktionen>Hinzufügen:

    Screenshot des Azure-Portals mit hervorgehobener Option „Neue Funktion“

  8. Erstellen Sie eine neue Azure Store-Warteschlangen-Triggerfunktion:

    Screenshot des Azure-Portals mit neuer hervorgehobener Funktion „Warteschlange ausgelöst“

  9. Geben Sie der Funktion den Namen InvokePnPSiteTemplate.

  10. Geben Sie den Namen der Warteschlange ein, die Sie zuvor erstellt haben.

  11. Wählen Sie Hinzufügen aus. Eine neue Seite wird geöffnet, auf der Sie die Funktion ändern können.

Hinweis

Das Speicherkonto muss sich in der gleichen Region befinden wie die Azure Function App, da die Ressourcen, die miteinander kommunizieren, in der gleichen Region liegen sollten. Dies ist eine Voraussetzung für Azure Functions.

Fertigstellen der Azure-Funktion

  1. Wechseln Sie zum Hauptbildschirm der Function-App, wählen Sie im linken Menü Erweiterte Tools aus, und klicken Sie dann auf Los. Eine neue Registerkarte wird geöffnet.

  2. Wählen Sie oben im Menü Debug-Konsole die Option PowerShell aus.

  3. Navigieren Sie zu site\wwwroot\InvokePnPSiteTemplate (oder site\wwwroot[Name Ihrer Funktion])

  4. Ziehen Sie die zuvor erstellte Datei FlowDemoTemplate.xml auf die Seite. Dadurch wird die Datei in den Ordner hochgeladen.

  5. Ziehen Sie die zuvor generierte Datei cert.pfx auf die Seite. Dadurch wird die Datei in den Ordner hochgeladen.

  6. Kehren Sie zur Funktion zurück, und wählen Sie Code + Test aus, um die Funktion zu bearbeiten.

  7. Ersetzen Sie das PowerShell-Skript durch Folgendes:

    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

    Ersetzen Sie [insertyourAppIdHere] durch den Wert, den das Register-PnPAzureApp-Cmdlet für AzureAppId zurückgibt.

    Ersetzen Sie „contoso.onmicrosoft.com“ mit den Details Ihres Mandanten.

Erstellen des Sitedesigns

Öffnen Sie PowerShell, und stellen Sie eine Verbindung mit Ihrem Mandanten über Connect-PnPOnline her.

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

Nun können Sie die vorhandenen Websitedesigns abrufen.

Get-PnPSiteDesign

Bevor Sie ein Websitedesign erstellen können, müssen Sie zuerst ein Websiteskript erstellen. Ein Websitedesign ist ein Container, der ein oder mehrere Websiteskripts referenziert.

  1. Kopieren Sie den folgenden JSON-Code in die Zwischenablage, und ändern Sie ihn. Geben Sie für die Eigenschaft url den Wert ein, den Sie sich bei der Erstellung des Flows notiert haben. Die URL sieht in etwa wie folgt aus:

    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
}

  2. Markieren Sie den JSON-Code erneut, und kopieren Sie ihn nochmals in die Zwischenablage.

  3. Öffnen Sie PowerShell, und geben Sie Folgendes ein, um das Skript in eine Variable zu kopieren und das Websiteskript zu erstellen:

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

  4. Es wird eine Liste mit einem oder mehreren Skripts angezeigt, einschließlich des soeben erstellten Websiteskripts. Markieren Sie die ID des Websiteskripts, das Sie soeben erstellt haben, und kopieren Sie sie in die Zwischenablage.

  5. Erstellen Sie mithilfe des folgenden Befehls das Websitedesign:

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

Überprüfen der Ergebnisse

Nachdem Sie Ihren Azure Queue-Speicher erstellt haben, haben Sie eine App-ID für App-exklusiven Zugriff, die Azure-Funktion und das Websitedesign erstellt. Anschließend haben Sie über das Websitedesign den Power Automate-Flow ausgelöst.

Um die Ergebnisse zu testen, müssen Sie nun eine neue Website erstellen. Klicken Sie in Ihrem SharePoint-Mandanten auf SharePoint>Website erstellen>Teamwebsite. Ihr neues Websitedesign sollte als Designoption angezeigt werden. Dabei ist zu beachten, dass das Websitedesign nach der Erstellung der Website angewendet wird. Wenn Sie es ordnungsgemäß konfiguriert haben, wird Ihr Flow ausgelöst. Ob der Flow korrekt ausgeführt wurde, können Sie in seinem Ausführungsverlauf überprüfen. Die Fußzeile wird möglicherweise nicht sofort angezeigt. Falls sie nicht angezeigt wird: Warten Sie eine Minute, und laden Sie Ihre Website neu, um es nochmals zu versuchen.