Opciones de implementación de las soluciones de SharePoint Framework para Microsoft Teams

Los desarrolladores tienen múltiples opciones al implementar soluciones de SharePoint Framework (SPFx) para usar dentro de Microsoft Teams. Este artículo explica las opciones respaldadas en SharePoint Online.

Nota

Antes de enero de 2021, SharePoint Online solo admitía una opción: cuando se cargaba una solución SPFx calificada en el catálogo de aplicaciones de espacio empresarial de SharePoint, el botón Sincronizar con Teams en la cinta del catálogo de aplicaciones de espacios empresariales.

SharePoint Online admite dos opciones para implementar soluciones SPFx en la tienda de aplicaciones de Microsoft Teams:

  1. Crear automáticamente el manifiesto y el paquete de la aplicación de Microsoft Teams
  2. Use el paquete y el manifiesto de la aplicación Microsoft Teams proporcionado por el desarrollador

Crear automáticamente el manifiesto de la aplicación de Microsoft Teams y el paquete

Esta funcionalidad es ideal cuando tiene una implementación simple que desea exponer automáticamente en Microsoft Teams.

En este escenario, cuando se carga una solución SPFx en el catálogo de aplicaciones de espacios empresariales de SharePoint Online, si la solución contiene componentes para Microsoft Teams, el botón Sincronizar con Teams en la cinta está habilitado.

Sincronizar con Teams

Este botón iniciará el siguiente proceso en SharePoint Online:

  1. SharePoint creará dinámicamente el archivo de manifiesto de la aplicación Microsoft Teams
  2. SharePoint creará dinámicamente el paquete de la aplicación Microsoft Teams
  3. SharePoint implementará el paquete de aplicaciones de Microsoft Teams generado en la tienda de aplicaciones de Microsoft Teams del espacio empresarial

Cuando SharePoint crea el manifiesto de la aplicación, usará valores de la solución SPFx para generar algunos nombres. En la siguiente tabla se enumeran las propiedades del archivo de manifiesto de la aplicación Microsoft Teams y los valores en los que están configuradas.

Nota

Consulte el siguiente vínculo en la documentación de Microsoft Teams para obtener más detalles sobre el manifiesto de la aplicación: Esquema de manifiesto para Microsoft Teams.

propiedad manifest.json Propiedad en el manifiesto del elemento web de SPFx
packageName alias
id id
name.short preconfiguredEntries[0].title
description.short preconfiguredEntries[0].description
description.long preconfiguredEntries[0].description

Nota

El manifiesto del componente se extrae del manifiesto del componente (./src/webparts/../*.manifest.json).

Si una solución SPFx contiene varios elementos web designados para su uso en Microsoft Teams, SharePoint Online repetirá el proceso anterior para cada uno de ellos.

Nota

Si tiene curiosidad sobre la estructura del paquete generado, puede usar la siguiente API de REST para descargar el paquete para soluciones específicas:

_api/web/tenantappcatalog/downloadteamssolution(id)/$value

id es el identificador numérico de la solución en la biblioteca de catálogos de aplicaciones.

Puedes solicitar esta API en el contexto del catálogo de aplicaciones, por ejemplo, con la dirección URL de https://[yourtenant]].sharepoint.com/sites/appcatalog/_api/web/tenantappcatalog/downloadteamssolution(12)/$value. La llamada API iniciará el proceso de descarga del paquete de manifiesto generado.

Manifiesto y paquete de la aplicación Microsoft Teams proporcionados por el desarrollador

Cuando necesite más control sobre el manifiesto de la aplicación de Microsoft Teams o el paquete de la aplicación, puede crear su propio paquete. En este caso, cuando un administrador selecciona el botón Sincronizar con Teams, SharePoint Online buscará el siguiente archivo en el archivo *.sppkg: ./teams/TeamsSPFxApp.zip.

Si este archivo está presente, SharePoint Online lo implementará en la tienda de aplicaciones de Microsoft Teams del espacio empresarial en lugar de crearlo dinámicamente. Esta opción brinda a los desarrolladores un control total sobre el manifiesto y el paquete de la aplicación de Microsoft Teams.

Esta opción es ideal para los siguientes escenarios:

  • Los desarrolladores desean tener un control total sobre el contenido del manifiesto de la aplicación Microsoft Teams
  • Escenarios complejos de Microsoft Teams, como especificar bots, aplicaciones de reuniones, etc.
  • Especifique el Id., el nombre y la descripción de la aplicación de Microsoft Teams cuando la solución SPFx contenga más de un componente. Por ejemplo, si una solución SPFx contiene varios elementos web que se pueden usar como pestañas en Microsoft Teams, la generación automática del manifiesto seleccionará uno de los dos componentes para usar como Id., nombre y descripción de la aplicación de Microsoft Teams.

Para usar su propio paquete de aplicación y manifiesto de aplicación de Microsoft Teams en lugar de permitir que SharePoint Online lo cree dinámicamente, haga lo siguiente:

  1. Cree un manifiesto de la aplicación de Microsoft Teams según la documentación de Microsoft Teams:

    Importante

    en el manifiesto de la aplicación de Teams, asegúrese de agregar la siguiente entrada:

    "webApplicationInfo": {
    "resource": "https://{teamSiteDomain}",
    "id": "00000003-0000-0ff1-ce00-000000000000"
    }
    

    Esto es necesario para asegurarse de que cualquier llamada API del componente se realizará correctamente desde los clientes enriquecidos de Microsoft Teams. teamSiteDomain será el mismo inquilino que usa el cliente de Teams; esto no funcionará entre inquilinos o entre dominios, por lo que no podrá codificar de forma rígida otro dominio.

  2. Cree el paquete de la aplicación Microsoft Teams denominado TeamsSPFxApp.zip comprimiendo el contenido de la carpeta ./teams.

    Importante

    No comprima la carpeta, en su lugar, comprima el contenido de la carpeta. Si comprime la carpeta, será una subcarpeta de nivel superior para el archivo ZIP resultante, que no es un paquete de aplicación válido en Microsoft Teams.

  3. Guarde TeamsSPFxApp.zip en la carpeta ./teams de la solución SPFx.

  4. Cree el paquete SPFx de la misma manera que lo haría con una solución SPFx normal, utilizando gulp package-solution. Incluirá el paquete de aplicación personalizado de Microsoft Teams en el *.sppkg.

Hacer referencia de forma dinámica a las URL del sitio de SharePoint subyacente

El manifiesto de la aplicación Microsoft Teams debe apuntar a la ubicación de hospedaje implementada de los componentes SPFx. Sin embargo, estas URL no se conocen en el momento en que se crea el manifiesto de la aplicación de Microsoft Teams o el paquete de la aplicación.

Por lo tanto, cuando especifica el paquete de la aplicación en esta opción de implementación, debe usar las siguientes cadenas que Microsoft Teams reemplazará en tiempo de ejecución:

  • {teamSiteDomain}: la URL del espacio empresarial de SharePoint Online donde se implementa e instala la solución SPFx
  • {teamSitePath}: la ruta al sitio de SharePoint donde se instalaron los componentes de SPFx
  • {locale}: la configuración regional actual del cliente de Microsoft Teams

Al usar un elemento web en una solución personalizada de Microsoft Teams, puede usar estas cadenas para definir la URL de la página que cargará el elemento web. Por ejemplo, use la siguiente tabla como guía para crear la dirección URL de los elementos web que se usan en las aplicaciones de Microsoft Teams:

Importante

En los siguientes ejemplos, se asume que el ID del componente SPFx es{{SPFX_COMPONENT_ID}}. Asegúrese de reemplazar este valor con el ID de componente de su elemento web. SharePoint o Microsoft Teams no establecen dinámicamente este valor: es responsabilidad del desarrollador establecer este valor.

Componente de Microsoft Teams Propiedad de manifiesto de la aplicación de Microsoft Teams Propiedad de manifiesto de la aplicación de Microsoft Teams
Pestaña personal staticTabs[..].contentUrl https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamshostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Pestaña de chat del canal/grupo configurableTabs[..].configurationUrl https://{teamSiteDomain}{teamSitePath}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest={teamSitePath}/_layouts/15/teamshostedapp.aspx%3FopenPropertyPane=true%26teams%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}
Extensión de mensajería composeExtensions.commands[..].taskInfo.url https://{teamSiteDomain}/_layouts/15/TeamsLogon.aspx?SPFX=true&dest=/_layouts/15/teamstaskhostedapp.aspx%3Fteams%26personal%26componentId={{SPFX_COMPONENT_ID}}%26forceLocale={locale}