Realizar llamadas al motor de aprovisionamiento de PnP desde un script de sitioCalling the PnP provisioning engine from a site script

Los diseños de sitio ofrecen una forma excelente de estandarizar la apariencia de las colecciones de sitios.Site designs offer a great way to standardize the look and feel of your site collections. A pesar de ello, existen ciertas cosas que no puede hacer con los diseños de sitio, como agregar un pie de página a todas las páginas.However, you can't do some things with site designs, like add a footer to every page. Puede usar el motor de aprovisionamiento de PnP para crear una plantilla y usarla para aprovisionar un personalizador de aplicación a un sitio.You can use the PnP provisioning engine to create a template that you can use to provision an Application Customizer to a site. Después, este personalizador de aplicación podrá actualizar el diseño de página, por ejemplo, para registrar un pie de página en cada página.This Application Customizer can then update your page design, for example to register a footer on every page.

En este artículo se describe cómo crear un diseño de sitio que aplique una plantilla de aprovisionamiento de PnP a un sitio.This article describes how to create a site design that applies a PnP provisioning template to a site. La plantilla agregará un personalizador de aplicación para representar un pie de página.The template will add an Application Customizer to render a footer.

En los pasos de este artículo se usan los componentes siguientes:The steps in this article use the following components:

  • Un diseño de sitio y un script de sitioA site design and a site script
  • Microsoft FlowMicrosoft Flow
  • Azure Queue StorageAzure Queue storage
  • Azure FunctionsAzure Functions
  • Una solución de SharePoint Framework (SPFx)A SharePoint Framework (SPFx) solution
  • Una plantilla de aprovisionamiento de PnPA PnP provisioning template
  • Un script de PnP PowerShellA PnP PowerShell script
  • Un identificador de aplicación y un secreto de aplicación con derechos de administración en el espacio empresarialAn app ID and app secret with administrative rights on your tenant

Usará estos componentes para desencadenar el código de aprovisionamiento de PnP después de crear el sitio y aplicar el diseño del sitio.You'll use these components to trigger the PnP provisioning code after you create the site and apply the site design.

Configurar el acceso solo de aplicación en el espacio empresarialSet up app-only access to your tenant

Para configurar el acceso de solo aplicaciones, debe tener dos páginas diferentes en el espacio empresarial: una en el sitio normal y otra en el sitio de administración de SharePoint.To set up app-only access, you need to have two different pages on your tenant—one on the regular site, and the other on your SharePoint administration site.

  1. Vaya a la siguiente dirección URL en su espacio empresarial: https://[yourtenant].sharepoint.com/_layouts/15/appregnew.aspx (puede ir a cualquier sitio, pero por ahora seleccione el sitio raíz).Go to following URL in your tenant: https://[yourtenant].sharepoint.com/_layouts/15/appregnew.aspx (you can go to any site, but for now pick the root site).

  2. Junto a los campos Id. de cliente y Secreto de cliente, elija el botón **Generar **.Next to the Client Id and Client Secret fields, choose the Generate button.

  3. Escriba un título para la aplicación (por ejemplo, Aprovisionamiento de sitio).Enter a title for your app, such as Site Provisioning.

  4. En el cuadro Dominio de aplicación, escriba localhost.In the App Domain box, enter localhost.

  5. En el campo URI de redirección, escriba https://localhost.In the Redirect URI box, enter https://localhost.

    Creación de una página de la aplicación en la que se muestran los campos Id. de cliente, Secreto de cliente, Título, Dominio de aplicación y URI de redirección

  6. Seleccione Crear.Choose Create.

  7. Copie los valores de Id. de cliente y Secreto de cliente, ya que los necesitará más adelante.Copy the values for Client Id and Client Secret because you will need them later.


Después, confíe en la aplicación para que tenga el acceso adecuado a su espacio empresarial:Next, trust the app, so that it has the appropriate access to your tenant:

  1. Vaya a https://[yourtenant]-admin.sharepoint.com/_layouts/appinv.aspx (observe que la dirección URL incluye -admin).Go to https://[yourtenant]-admin.sharepoint.com/_layouts/appinv.aspx (notice the -admin in the URL).

  2. En el campo Id. de la aplicación, pegue el Id. de cliente que ha copiado y seleccione Búsqueda.In the App Id field, paste the Client ID that you copied, and choose Lookup.

  3. En el campo XML de solicitud de permiso, pegue el siguiente código XML:In the Permission Request XML field, paste the following XML:

    <AppPermissionRequests AllowAppOnlyPolicy="true" >
        <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
    </AppPermissionRequests>
    
  4. Seleccione Crear.Choose Create.

  5. Para confirmar que quiere confiar en esta aplicación, seleccione Confiar.To confirm that you want to trust this app, choose Trust It.

Creación de Azure Queue StorageCreate the Azure Queue storage

En esta sección, usará Azure Queue Storage para recibir mensajes de Microsoft Flow.In this section, you will use Azure Queue storage to receive messages from Microsoft Flow. Cada vez que se muestra un mensaje en Queue Storage, se desencadena una función de Azure para ejecutar un script de PowerShell.Every time a message shows up in the Queue storage, an Azure function is triggered to run a PowerShell script.

Para configurar Azure Queue Storage:To set up the Azure Queue storage:

  1. Vaya a Azure Portal e inicie sesión.Go to the Azure portal and sign in.
  2. Elija + Crear un recurso.Choose + Create a resource.
  3. En la lista de Azure Marketplace seleccione Almacenamiento y en la columna Destacados seleccione Cuenta de almacenamiento: blob, archivo, tabla, cola.From the Azure Marketplace listings, select Storage, and in the Featured column, choose Storage account - blob, file, table, queue.
  4. Rellene los campos obligatorios.Provide values for the required fields. Seleccione Anclar al panely Crear.Select Pin to dashboard, and choose Create. La cuenta de almacenamiento podría tardar unos minutos en crearse.It can take a few minutes for the storage account to be created.
  5. Abra la cuenta de almacenamiento y vaya a Colas.Open the storage account and go to Queues.
  6. Seleccione + Cola en la parte superior de la pantalla.Choose + Queue at the top of the screen.
  7. Escriba pnpprovisioningqueue como nombre o bien escriba el valor que prefiera, pero asegúrese de que siga la nomenclatura estándar.Enter pnpprovisioningqueue for the name, or enter your own value; be sure to follow the naming standard. Anote el nombre de la cola, ya que necesitará este valor cuando cree la función de Azure.Make note of the queue name; you will need this value when you create the Azure Function.
  8. Vaya a Claves de acceso y anote el Nombre de la cuenta de almacenamiento y el valor de clave Key1.Go to Access Keys and note the Storage Account Name and the key1 Key value. Necesitará estos valores cuando cree el flujo.You will need these values when you create the flow.

Creación del flujoCreate the flow

Para colocar un mensaje en la cola, deberá crear un flujo.To put a message in the queue, you need to create a flow.

  1. Vaya al sitio de Microsoft Flow, inicie sesión y seleccione Crear desde cero en la parte superior de la página.Go to the Microsoft Flow site, sign in, and choose Create from Blank at the top of the page.

  2. Seleccione Buscar entre cientos de conectores y desencadenadores para elegir el desencadenador.Choose Search hundreds of connectors and triggers to select your trigger.

  3. Busque Solicitud y seleccione Solicitud: cuando se recibe una solicitud HTTP.Search for Request, and select Request - When a HTTP Request is received.

  4. Escriba el siguiente código JSON como el cuerpo de la solicitud:Enter the following JSON as your request body:

    {
        "type": "object",
        "properties": {
            "webUrl": {
                "type": "string"
            },
            "parameters": {
                "type": "object",
                "properties": {
                    "event": {
                        "type": "string"
                    },
                    "product": {
                        "type": "string"
                    }
                }
            }
        }
    }
    
  5. Seleccione + Nuevo paso y haga clic en Agregar una acción.Select + New Step and choose Add an action.

  6. Busque Colas de Azure y seleccione Colas de Azure: colocar un mensaje en una cola.Search for Azure Queues and select Azure Queues - Put a message on a queue.

  7. Escriba un nombre descriptivo para la conexión.Enter a descriptive name for the connection.

  8. Escriba el nombre de la cuenta de almacenamiento que ha copiado en la sección anterior.Enter the storage account name that you copied in the previous section.

  9. Escriba la clave compartida de almacenamiento, que es el valor indicado en el campo de valor de clave Key1 de la cuenta de almacenamiento.Enter the storage shared key, which is the value of the Key1 key value field of your storage account.

  10. Seleccione Crear.Choose Create.

  11. Seleccione pnpprovisioningqueue como el nombre de la cola.Select pnpprovisioningqueue for the queue name.

  12. En el cuerpo de la solicitud, ha especificado un parámetro de entrada denominado webUrl.In the request body, you specified an incoming parameter called webUrl. Para colocar el valor de ese campo en la cola, haga clic en el campo Mensaje y seleccione webUrl en el selector de contenido dinámico.To put the value of that field in the queue, click in the message field and select webUrl from the Dynamic Content picker.

  13. Seleccione Guardar flujo.Choose Save Flow. De este modo, se generará la dirección URL que copiará en el paso siguiente.This will generate the URL that you will copy in the next step.

  14. Seleccione el primer paso del flujo ("Cuando se recibe una solicitud HTTP") y copie la dirección URL.Choose the first step in your flow ('When an HTTP request is received') and copy the URL.

  15. Guarde el flujo.Save your flow.

El flujo debería ser similar al siguiente.Your flow should look like the following.

Captura de pantalla de un flujo denominado "Cuando se recibe una solicitud HTTP", en el que se muestran los campos Dirección URL, Cuerpo de la solicitud, Nombre de la cola y Mensaje

Probar el flujoTest the flow

Para probar el flujo, debe realizar una solicitud POST.To test your flow, you have to make a POST request. Puede hacerlo con PowerShell, como se muestra en el ejemplo siguiente.You can do this via PowerShell, as shown in the following example.

$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

Cuando vaya a la pantalla principal del flujo, verá el historial de ejecución.When you go to the main screen of your flow, you will see a run history. Si el flujo ha funcionado correctamente, aparecerá Succeeded.If your flow worked correctly, it will show Succeeded. Ahora, vaya a la cola que ha creado en Azure y seleccione Actualizar.Now go to the queue you just created in Azure and choose Refresh. Debería ver una entrada donde se indica que se ha invocado correctamente el flujo.You should see an entry that shows that you correctly invoked the flow.

Aprovisionar la solución SPFxProvision the SPFx solution

En esta sección, usará una solución SPFx existente, el personalizador de aplicación de pies de página de regiones.In this section, you'll use an existing SPFx solution, the Regions Footer Application Customizer. Siga los pasos del archivo Léame del repositorio de ejemplos para compilar y aprovisionar la solución.Follow the steps in the Readme file in the sample repo to build and provision the solution.

Crear una plantilla de aprovisionamiento de PnPCreate a PnP provisioning template

Copie el siguiente código XML de plantilla de aprovisionamiento en un archivo nuevo y guárdelo como FlowDemoTemplate.xml.Copy the following provisioning template XML to a new file and save the file as 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>

Nota

La plantilla de aprovisionamiento agrega una acción personalizada a una solución.The provisioning template adds a custom action to a solution. ClientSideComponentId se asocia al personalizador de aplicación de pies de página de regiones que ha aprovisionado anteriormente.The ClientSideComponentId is associated with the Regions Footer Application Customizer that you provisioned earlier. Si ejecuta esta demostración con su propia solución SPFx, cambie en el código XML el valor de atributo ClientSideComponentId y, de forma opcional, ClientSideComponentProperties.If you run this demo with your own SPFx solution, change the ClientSideComponentId and optionally the ClientSideComponentProperties attribute values in the XML.

Crear la función de AzureCreate the Azure Function

  1. Vaya a Azure Portal.Go to the Azure Portal.

  2. Elija + Crear un recurso.Choose + Create a resource.

  3. Busque Function App y cree una aplicación de función.Search for Function App and create a new function app. En el campo Almacenamiento, seleccione Usar existente y elija la cuenta de almacenamiento que ha creado anteriormente.In the Storage field, select Use existing, and select the storage account that you created earlier. Establezca el resto de los valores según sea necesario.Set the other values as required.

  4. Actualmente las Function apps están creadas con V2 runtime que no es compatible con las funciones de PowerShell.Currently Function apps a created with the V2 runtime which does not support PowerShell functions. Cambie el runtime de la Function app a V1 seleccionando Características de la plataforma, Configuración de la Function app y cambie el runtime de ~2 a ~1.Change the runtime of the function app to V1 by navigating selecting Platform features, Function app settings and change the Runtime version from ~2 to ~1.

  5. Cree una nueva función: Funciones > Nueva función.Create a new function: Functions > New function.

    Captura de pantalla de Azure Portal con la opción Nueva función resaltada

  6. Activa el soporte de idiomas experimental:Turn on experimental language support:

    Captura de pantalla de Azure Portal con el botón Compatibilidad de lenguaje experimental resaltado

  7. Crear una nueva función Desencadenador de cola basada en PowerShell:Create a new Queue Triggered function based upon PowerShell:

    Captura de pantalla de Azure Portal con la nueva opción Desencadenador de cola resaltada

  8. Asigne a la función el nombre ApplyPnPProvisioningTemplate.Name the function ApplyPnPProvisioningTemplate.

  9. Escriba el nombre de la cola que ha creado anteriormente.Enter the name of the queue you created earlier.

  10. Seleccione Crear.Choose Create. Se abrirá un editor en el que podrá escribir cmdlets de PowerShell.An editor where you can enter PowerShell cmdlets will open.

Ahora, cargará el módulo de PnP PowerShell para que pueda usarlo en la función de Azure.Next, you'll upload the PnP PowerShell module so that you can use it in the Azure Function.

Cargar el módulo de PnP PowerShell para la función de AzureUpload the PnP PowerShell module for your Azure Function

Debe descargar el módulo de PnP PowerShell para poder cargarlo para la función de Azure.You'll need to download the PnP PowerShell module so that you can upload it for your Azure Function.

  1. Cree una carpeta temporal en el equipo.Create a temporary folder on your computer.
  2. Inicie PowerShell y escriba lo siguiente:Launch PowerShell and enter the following:
    Save-Module -Name SharePointPnPPowerShellOnline -Path [pathtoyourfolder]
    

Los archivos del módulo de PowerShell se descargarán en una carpeta dentro de la carpeta que ha creado.The PowerShell module files will download to a folder within the folder that you created.

Después, cargue los archivos para que la función Azure pueda usar el módulo.Next, upload the files so that your Azure Function can use the module.

  1. Vaya a la página principal de la instancia de Function App y seleccione Características de la plataforma.Go to the main page of your Function App and select Platform Features.

    Captura de pantalla de Function App con la opción Características de la plataforma resaltada

  2. Seleccione Herramientas avanzadas (Kudu).Select Advanced tools (Kudu).

    Captura de pantalla de Herramientas de desarrollo con la opción Herramientas avanzadas (Kudu) resaltada

  3. En la página principal de Kudu, seleccione Consola de depuración y elija CMD o PowerShell.On the main Kudu page, select Debug Console and pick either CMD or PowerShell.

  4. Seleccione el Explorador de archivos en la parte superior de la página y vaya a site\wwwroot\[nombreDeSuFunciónDeAzure].Choose the file explorer on the upper part of the page, and go to site\wwwroot\[nameofyourazurefunction].

  5. Cree una carpeta denominada Módulos.Create a new folder named modules.

    Captura de pantalla con la opción Nueva carpeta resaltada

  6. En la carpeta Módulos, cree otra carpeta denominada SharePointPnPPowerShellOnline y navegue hasta ella.In the modules folder, create another folder called SharePointPnPPowerShellOnline and go to that folder.

  7. En el Explorador de archivos del equipo, vaya a la carpeta en la que ha descargado los archivos del módulo de PnP PowerShell.In File Explorer on your computer, go to the folder where you downloaded the PnP PowerShell module files. Abra la carpeta SharePointPnPPowerShellOnline\2.20.1711.0 (tenga en cuenta que el número de versión puede ser distinto).Open the SharePointPnPPowerShellOnline\2.20.1711.0 folder (notice that the version number might be different).

  8. Arrastre y suelte todos los archivos de esta carpeta en la carpeta de Kudu para cargarlos.Drag and drop all the files from this folder into the folder in Kudu to upload them.

    Captura de pantalla de la carpeta de Kudu con 40 archivos agregados

Finalizar la función de AzureFinish the Azure Function

  1. Vuelva a navegar hasta la función de Azure y expanda la pestaña Archivos de la parte derecha.Go back to your Azure Function and expand the files tab to the right.

    Captura de pantalla de la pestaña Ver archivos

  2. Seleccione Cargar y cargue el archivo de plantilla de aprovisionamiento que ha creado anteriormente.Select Upload and upload the provisioning template file that you created earlier.

  3. Reemplace el script de PowerShell por lo siguiente:Replace the PowerShell script with the following:

    $in = Get-Content $triggerInput -Raw
    Write-Output "Incoming request for '$in'"
    Connect-PnPOnline -AppId $env:SPO_AppId -AppSecret $env:SPO_AppSecret -Url $in
    Write-Output "Connected to site"
    Apply-PnPProvisioningTemplate -Path D:\home\site\wwwroot\ApplyPnPProvisioningTemplate\FlowDemoTemplate.xml
    

Tenga en cuenta que está usando dos variables de entorno: SPO_AppId y SPO_AppSecret.Notice that you're using two environment variables: SPO_AppIdand SPO_AppSecret. Para establecer esas variables, vaya a la página principal de Function App en Azure Portal (la que tiene el icono del rayo amarillo), seleccione Configuración y agregue dos nuevas opciones de configuración de la aplicación:To set those variables, go to the main Function App page in the Azure Portal, select Application Settings, and add two new application settings:

  1. SPO_AppId: establezca el valor en el identificador de cliente que ha copiado en el primer paso al crear la aplicación en el espacio empresarial.SPO_AppId - Set the value to the Client ID you copied in the first step when you created your app on your tenant.
  2. SPO_AppSecret: establezca el valor en el secreto de cliente que ha copiado en el primer paso al crear la aplicación en el espacio empresarial.SPO_AppSecret - Set the value to the Client Secret that you copied in the first step when you created your app on your tenant.

Crear el diseño de sitioCreate the site design

Abra PowerShell y asegúrese de que el Shell de administración de SharePoint Online esté instalado.Open PowerShell and make sure that you have the SharePoint Online Management Shell installed.

Conéctese al espacio empresarial con Connect-SPOService.Connect to your tenant using Connect-SPOService.

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

Ahora puede obtener los diseños de sitio existentes.Now you can get the existing site designs.

Get-SPOSiteDesign

Para crear un diseño de sitio, primero debe crear un script de sitio.To create a site design, you first need to create a site script. Un diseño de sitio es un contenedor que hace referencia a uno o más scripts de sitios.A site design is a container that refers to one or more site scripts.

  1. Copie el siguiente código JSON en el Portapapeles y modifíquelo.Copy the following JSON code to your clipboard and modify it. Establezca la propiedad url en el valor que ha copiado al crear el flujo.Set the url property to the value you copied when you created the flow. La dirección URL tendrá un aspecto similar al siguiente:The URL looks similar to the following:

    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. Vuelva a seleccionar el JSON y cópielo de nuevo en el Portapapeles.Select the JSON again and copy it again to your clipboard.

  3. Abra PowerShell y escriba lo siguiente para copiar el script en una variable y crear el script de sitio:Open PowerShell and enter the following to copy the script into a variable and create the site script:

    $script = Get-Clipboard -Raw
    Add-SPOSiteScript -Title "Apply PnP Provisioning Template" -Content $script
    Get-SPOSiteScript
    
  4. Verá una lista de uno o más scripts de sitio, incluido el script de sitio que acaba de crear.You will see a list of one or more site scripts, including the site script you just created. Seleccione el identificador del script de sitio que ha creado y cópielo en el Portapapeles.Select the ID of the site script that you created and copy it to the clipboard.

  5. Use el comando siguiente para crear el diseño de sitio:Use the following command to create the site design:

    Add-SPOSiteDesign -Title "Site with footer" -SiteScripts [Paste the ID of the Site Script here] -WebTemplate "64"
    

El cmdlet Add-SPOSiteDesign asocia el diseño de sitio con el sitio de grupo.The Add-SPOSiteDesign cmdlet associates the site design with the team site. Para asociar el diseño con un sitio de comunicación, use el valor "68".If you want to associate the design with a communication site, use the value "68".

Comprobación de los resultadosVerify the results

Después de crear Azure Queue Storage, creó el identificador de la aplicación para el acceso solo de aplicación, la función de Azure y el diseño del sitio.After you created your Azure Queue storage, you created the app ID for app-only access, the Azure Function, and the site design. Después, desencadenó Microsoft Flow desde el diseño del sitio.You then triggered the Microsoft Flow from the site design.

Para probar los resultados, cree un sitio.To test the results, create a new site. En el espacio empresarial de SharePoint, seleccione SharePoint > Crear sitio > Sitio de grupo.In your SharePoint tenant, select SharePoint > Create Site > Team Site. El nuevo diseño de sitio debería mostrarse como una opción de diseño.Your new site design should show up as a design option. Tenga en cuenta que el diseño de sitio se aplica una vez que se ha creado el sitio.Notice that the site design is applied after the site is created. Si lo ha configurado correctamente, el flujo se desencadenará.If you configured it correctly, your flow will be triggered. Puede comprobar el historial de ejecución del flujo para asegurarse de que se ha ejecutado correctamente.You can check the run history of the flow to verify that it ran correctly. Tenga en cuenta que el pie de página podría no mostrarse de inmediato. Si no aparece, espere un minuto y vuelva a cargar el sitio para volver a comprobarlo.Note that the footer might not show up immediately; if you don't see it, wait a minute and reload your site to check again.