Información general sobre scripts de sitio y diseños de sitio de SharePointSharePoint site design and site script overview

Nota

Los scripts de sitio y diseños de sitio actualmente solo son compatibles con SharePoint Online.Site designs and site scripts are currently only supported by SharePoint Online.

Use diseños de sitio y scripts de sitio para automatizar el aprovisionamiento de nuevos sitios modernos de SharePoint, o ya existentes, con sus propias configuraciones personalizadas.Use site designs and site scripts to automate provisioning new or existing modern SharePoint sites that use your own custom configurations.

Cuando los usuarios de la organización crean sitios de SharePoint, con frecuencia es necesario garantizar algún nivel de coherencia.When people in your organization create new SharePoint sites, you often need to ensure some level of consistency. Por ejemplo, puede que necesite aplicar un tema y una personalización de marca adecuados a cada nuevo sitio.For example, you may need proper branding and theming applied to each new site. Puede que también tenga scripts detallados de aprovisionamiento de sitios, como el uso de un motor de aprovisionamiento de PnP, que es necesario aplicar cada vez que se crea un sitio.You may also have detailed site provisioning scripts, such as using the PnP provisioning engine, that need to be applied each time a new site is created.

En este artículo, se describe cómo usar diseños de sitio y scripts de sitio para aplicar una configuración personalizada cada vez que se cree un sitio.This article describes how you can use site designs and site scripts to provide custom configurations to apply when new sites are created.

Funcionamiento de los diseños de sitioHow site designs work

Los diseños de sitio son como una plantilla.Site designs are like a template. Este nivel de coherencia se puede usar cada vez que se cree un sitio para aplicar un conjunto de acciones coherentes.They can be used each time a new site is created to apply a consistent set of actions. También puede aplicarse a sitios modernos existentes (sitios de grupo y de comunicación conectados a grupos).They can also be applied to existing modern sites (group-connected Team and Communication sites). La mayoría de las acciones suelen afectar al sitio en sí, como configurar el tema o crear listas.Most actions typically affect the site itself, such as setting the theme or creating lists. Pero, en un diseño de sitio, también se pueden incluir otras acciones, como registrar la nueva URL de sitio en un archivo de registro o enviar un tweet.But a site design can also include other actions, such as recording the new site URL to a log, or sending a tweet.

Puede crear diseños de sitio y registrarlos en SharePoint en uno de los sitios de plantilla modernos: el sitio de grupo o el sitio de comunicación.You create site designs and register them in SharePoint to one of the modern template sites: the Team site or the Communication site. En los pasos siguientes verá el funcionamiento de esto.You can see how this works in the following steps.

  1. Vaya a la página principal de SharePoint en el espacio empresarial para desarrolladores.Go to the SharePoint home page on your developer tenant.

  2. Seleccione Crear sitio.Choose Create site.

    Verá los dos sitios de plantilla modernos: Sitio de grupo y Sitio de comunicación.You'll see the two modern template sites: Team site and Communication site.

  3. Seleccione Sitio de comunicación.Choose Communication site.

El sitio de comunicación tiene un cuadro Seleccionar un diseño, que incluye los diseños de sitio siguientes:The Communication site has a Choose a design box, which comes with the following site designs:

  • TemaTopic
  • PresentaciónShowcase
  • En blancoBlank

Estos son los diseños de sitio predeterminados.These are the default site designs. Por cada diseño de sitio, verá un título, una descripción y una imagen.For each site design, there is a title, description, and image.

Título, descripción e imagen de un diseño de sitio predeterminado en la plantilla de sitio de comunicación

Si selecciona la plantilla de sitio de grupo, solo contendrá un diseño de sitio predeterminado denominado Sitio de grupo.Had you chosen the Team site template, it contains only one default site design named Team site.

Para más información sobre cómo cambiar los diseños de sitio predeterminados, vea Personalizar un diseño de sitio predeterminado.For more information about how you can change the default site designs, see Customize a default site design.

Cuando se haya seleccionado un diseño de sitio, SharePoint creará el sitio y ejecutará scripts de sitio para el diseño de sitio.When a site design is selected, SharePoint creates the new site, and runs site scripts for the site design. En los scripts de sitio se especifican los detalles de los trabajos, como crear listas o aplicar un tema.The site scripts detail the work such as creating new lists or applying a theme. Estas acciones de script se ejecutan en segundo plano.These script actions are run in the background. Se muestra una barra de notificación, en la que el creador del sitio puede hacer clic para ver el estado de las acciones que se aplican.A notification bar will be displayed, which the site creator can click to view the status of the actions being applied.

Barra de notificación que muestra la aplicación de acciones de script en curso

Cuando se hayan completado los scripts cambiará el mensaje de la barra de notificación, que permite al creador del sitio actualizar la página para ver los resultados de los scripts aplicados o ver los detalles del script del sitio.When the scripts are complete the notification bar message will change - allowing the site creator to either refresh the page to see the results of the applied scripts or to view the site script details.

Barra de notificación que muestra la aplicación de acciones de script completada

El propietario de un sitio puede invocar el panel de información de diseño del sitio en cualquier momento para ver qué diseños de sitio se han aplicado al sitio (y los detalles del script) así como aplicar diseños de sitio nuevos o actualizados.The site design information panel can be invoked by a site owner at any time to see what site designs have been applied to the site (and their script details) as well as to apply new or updated site designs.

Nota

El panel de información de diseño del sitio empezó a implementarse para los clientes de la versión de destino en diciembre de 2018 y su implementación mundial se completará a principios de 2019.The site design information panel started rolling out to Target Release customers in December 2018 - and will complete WW rollout in early 2019.

Cuando las acciones en los scripts en un panel de progreso se completan, SharePoint muestra los resultados detallados de esas acciones en un panel de progreso.When the actions in the scripts are completed, SharePoint displays detailed results of those actions in a progress pane.

Panel de información de diseño de sitio

Nota

Ahora los diseños de sitio se pueden aplicar a colecciones de sitios modernos ya creadas.Site designs can now be applied to previously created modern site collections. Para más información, vea los artículos API de REST y PowerShell.For more information, see the REST API and PowerShell articles.

Anatomía de un script de sitioAnatomy of a site script

Los scripts de sitio son archivos JSON que especifican una lista ordenada de acciones que se ejecutarán al crear el sitio.Site scripts are JSON files that specify an ordered list of actions to run when creating the new site. Las acciones se ejecutan en el orden de la lista.The actions are run in the order listed.

El ejemplo siguiente es un script con dos acciones de nivel superior.The following example is a script that has two top-level actions. Primero se aplica un tema que se creó anteriormente denominado Exploradores de Contoso.First, it applies a theme that was previously created named Contoso Explorers. Luego se crea la lista Seguimiento de clientes.It then creates a Customer Tracking list.

{
  "$schema": "schema.json",
  "actions": [
    {
      "verb": "applyTheme",
      "themeName": "Contoso Explorers"
    },
    {
      "verb": "createSPList",
      "listName": "Customer Tracking",
      "templateType": 100,
      "subactions": [
        {
          "verb": "SetDescription",
          "description": "List of Customers and Orders"
        },
        {
          "verb": "addSPField",
          "fieldType": "Text",
          "displayName": "Customer Name",
          "isRequired": false,
          "addToDefaultView": true
        },
        {
          "verb": "addSPField",
          "fieldType": "Number",
          "displayName": "Requisition Total",
          "addToDefaultView": true,
          "isRequired": true
        },
        {
          "verb": "addSPField",
           "fieldType": "User",
          "displayName": "Contact",
          "addToDefaultView": true,
          "isRequired": true
        },
        {
          "verb": "addSPField",
          "fieldType": "Note",
          "displayName": "Meeting Notes",
          "isRequired": false
        }
      ]
    }
  ],
  "version": 1
}

Cada acción de un script de sitio se especifica con un valor de verb en el código JSON.Each action in a site script is specified by a verb value in the JSON. En el script anterior, la primera acción se especifica con el verbo applyTheme.In the previous script, the first action is specified by the applyTheme verb. Después, el verbo createSPList crea la lista.Next, the createSPList verb creates the list. Como puede ver, el verbo createSPList contiene su propio conjunto de verbos, que solo ejecutan acciones adicionales en la lista.Notice that the createSPList verb contains its own set of verbs that run additional actions on only the list.

Entre las acciones disponibles, se incluyen las siguientes:Available actions include:

  • Crear una lista o biblioteca (o modificar la predeterminada que se creó con el sitio)Creating a new list or library (or modifying the default one created with the site)
  • Crear columnas de sitio y tipos de contenido y configurar otras opciones de configuración de listaCreating site columns, content types, and configuring other list settings
  • Aplicar un temaApplying a theme
  • Establecer un logotipo de sitioSetting a site logo
  • Agregar funciones de navegaciónAdding navigation
  • Desencadenar un flujo de Microsoft FlowTriggering a Microsoft Flow
  • Instalar una solución implementada del catálogo de aplicacionesInstalling a deployed solution from the app catalog
  • Establecer la configuración regional del sitioSetting regional settings for the site
  • Agregar entidades de seguridad (usuarios y grupos) a los roles de SharePointAdding principals (users and groups) to SharePoint roles
  • Establecer la funcionalidad de uso compartido externo en el sitioSetting external sharing capability for the site

Para obtener una lista completa de acciones disponibles y sus parámetros, vea el esquema JSON.For a complete list of available actions and their parameters, see the JSON schema.

Los scripts de sitio se pueden volver a ejecutar en el mismo sitio después del aprovisionamiento.Site scripts can be run again on the same site after provisioning. Los scripts de sitio no son destructivos; por lo tanto, al volverlos a ejecutar, comprobarán que el sitio coincida con la configuración del script.Site scripts are non-destructive, so when they run again, they ensure that the site matches the configuration in the script.

Por ejemplo, si el sitio ya tiene una lista con el mismo nombre que creará el script de sitio, solo agregará los campos que falten a la lista existente.For example, if the site already has a list with the same name that the site script is creating, the site script will only add missing fields to the existing list.

Anteriormente se había limitado a 30 el número de acciones de script de sitio.We'd previously capped the limit of site script actions to 30. Este sigue siendo el límite para los scripts aplicados de forma sincrónica mediante el comando Invoke-SPOSiteDesign pero, en base a los comentarios de los usuarios y el soporte para acciones adicionales, hemos incrementado este límite a 300 acciones (o 100.000 caracteres) cuando los scripts se aplican de forma asincrónica (a través de la interfaz de usuario o mediante el comando Add-SPOSiteDesignTask).This remains the limit for scripts applied synchronously using the Invoke-SPOSiteDesign command, but based on customer feedback and support for additional actions we have bumped this limit to 300 actions (or 100,000 characters) when the scripts are applied asynchronously (either through the UI or using the Add-SPOSiteDesignTask command).

También hay un límite de 100 scripts de sitio y 100 diseños de sitio por inquilino.There is also a limit of 100 site scripts and 100 site designs per tenant.

Usar PowerShell o REST para trabajar con diseños de sitio y scripts de sitioUsing PowerShell or REST to work with site designs and site scripts

Puede crear diseños de sitio y scripts de sitio con PowerShell o con la API de REST.You can create site designs and site scripts by using PowerShell or the REST API. En el ejemplo siguiente, se crea un script de sitio y un diseño de sitio que usa el script de sitio.The following example creates a site script and a site design that uses the site script.

C:\> Get-Content 'c:\scripts\site-script.json' `
     -Raw | `
     Add-SPOSiteScript `
    -Title "Contoso theme and list"

Id          : 2756067f-d818-4933-a514-2a2b2c50fb06
Title       : Contoso theme and list
Description :
Content     :
Version     : 0

C:\> Add-SPOSiteDesign `
  -Title "Contoso customer tracking" `
  -WebTemplate "64" `
  -SiteScripts "2756067f-d818-4933-a514-2a2b2c50fb06" `
  -Description "Creates customer list and applies standard theme"

En el ejemplo anterior, el cmdlet Add-SPOSiteScript o la API de REST CreateSiteScript devuelven un identificador de script de sitio. Este se usa con el parámetro SiteScripts en la llamada siguiente al cmdlet Add-SPO-SiteDesign o a la API de REST CreateSiteDesign.In the previous example, the Add-SPOSiteScript cmdlet or CreateSiteScript REST API returns a site script id. This is used for the SiteScripts parameter in the subsequent call to the Add-SPO-SiteDesign cmdlet or CreateSiteDesign REST API.

El parámetro WebTemplate establecido al valor 64 indica que este diseño de sitio se registra con la plantilla de sitio de grupo.The WebTemplate parameter set to the value 64 indicates registering this site design with the Team site template. Si ha deshabilitado la creación moderna de grupos, publique los diseños de sitio con WebTemplate 1 para que se muestren para la plantilla de sitio de grupo "Sin grupo".If you have disabled modern Group creation, then publish your site designs using WebTemplate 1 so that they display for the "Group-less" Team site template. El valor 68 indicaría que se registra con la plantilla de sitio de comunicación.The value 68 would indicate registering with the Communication site template. Los parámetros Title y Description se mostrarán cuando un usuario vea diseños de sitio al crear un sitio de grupo.The Title and Description parameters are displayed when a user views site designs as they create a new Team site.

Nota

Un diseño de sitio puede ejecutar varios scripts.A site design can run multiple scripts. Los identificadores de script se pasan en una matriz y se ejecutan en el orden en que aparecen en la lista.The script IDs are passed in an array, and they run in the order listed.

Para información detallada sobre cómo crear un diseño de sitio, vea Introducción a la creación de diseños de sitio.For step-by-step information about creating a site design, see Get started creating site designs.

Aprovisionamiento y personalización de PnP con Microsoft FlowPnP provisioning and customization using Microsoft Flow

Una acción que ofrecen los scripts de sitio es la posibilidad de desencadenar un flujo de Microsoft Flow.One action provided by site scripts is the ability to trigger a Microsoft Flow. Esto le permite especificar cualquier acción personalizada que necesite además de las acciones especificadas de forma nativa en los scripts de sitio.This allows you to specify any custom action that you need beyond the actions provided natively in site scripts.

Si usa el motor de aprovisionamiento de PnP para automatizar la creación de sitios, podrá usar un flujo de Microsoft Flow para la integración con los diseños de sitio.If you use the PnP provisioning engine to automate site creation, you can use a Microsoft Flow to integrate with site designs. Puede mantener todos los scripts de aprovisionamiento existentes, así como crear scripts de aprovisionamiento personalizados con esta técnica.You can maintain all your existing provisioning scripts as well as create new custom provisioning scripts by using this technique.


Proceso de desencadenar un flujo de Microsoft Flow

El proceso funciona de esta forma:The process works as follows:

  1. El script crea una instancia de Microsoft Flow con una dirección URL que incluye detalles adicionales.The script instantiates your Microsoft Flow using a URL with additional details.

  2. El flujo envía un mensaje a una cola de Azure Storage que configuró.The flow sends a message to an Azure storage queue that you have configured.

  3. El mensaje desencadena una cadena a una función de Azure que configuró.The message triggers a call to an Azure function that you have configured.

  4. La función de Azure ejecuta el script personalizado, como el motor de aprovisionamiento de PnP, para aplicar las configuraciones personalizadas.The Azure function runs your custom script, such as the PnP provisioning engine, to apply your custom configurations.

Para obtener un tutorial detallado sobre cómo configurar su propia instancia de Microsoft Flow con el aprovisionamiento de PnP, vea Crear un diseño de sitio completo con el motor de aprovisionamiento de PnP.For a step-by-step tutorial about how to configure your own Microsoft Flow with PnP provisioning, see Build a complete site design using the PnP provisioning engine.

ÁmbitoScoping

Puede configurar los diseños de sitio para que solo aparezcan para grupos o usuarios específicos de la organización.You can configure site designs to only appear for specific groups or people in your organization. Esto es útil para garantizar que los usuarios solo vean los diseños de sitio adecuados.This is useful to ensure that people only see the site designs intended for them. Por ejemplo, puede que quiera que el Departamento de Contabilidad solo vea diseños de sitio creados específicamente para su departamento,For example, you might want the accounting department to only see site designs specifically for them. ya que no tiene mucho sentido que los diseños de sitio de contabilidad se muestren a otros usuarios.And the accounting site designs may not make sense to show to anyone else.

De manera predeterminada, todos los usuarios podrán ver un diseño de sitio cuando se cree.By default, a site design can be viewed by everyone when it is created. Los ámbitos se aplican con el cmdlet Grant-SPOSiteDesignRights o con la API de REST GrantSiteDesignRights.Scopes are applied by using the Grant-SPOSiteDesignRights cmdlet or the GrantSiteDesignRights REST API. Puede especificar el ámbito por usuario o por grupo de seguridad habilitado para correo.You can specify the scope by user or a mail-enabled security group.

En el ejemplo siguiente se muestra cómo agregar a Sergio (un usuario del sitio ficticio de Contoso) derechos de vista en un diseño de sitio.The following example shows how to add Nestor (a user at the fictional Contoso site) view rights on a site design.

Grant-SPOSiteDesignRights `
  -Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 `
  -Principals "nestorw@contoso.onmicrosoft.com" `
  -Rights View

Para más información sobre cómo trabajar con ámbitos, vea Ámbito de acceso a diseños de sitio.For more information about working with scopes, see Scoping access to site designs.

Ver tambiénSee also