Compartir a través de

Especificar los requisitos del entorno de ejecución del host de Microsoft 365 en el manifiesto de la aplicación

  • Artículo

Nota:

La capacidad de especificar los requisitos de tiempo de ejecución de host de Microsoft 365 en el manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams) está en versión preliminar para desarrolladores públicos.

Al actualizar la aplicación de extensión de mensaje o pestaña personal de Microsoft Teams para usar la versión 1.13 o posterior del manifiesto de la aplicación, está disponible en otros hosts de aplicaciones de Microsoft 365 de forma predeterminada. Sin embargo, si la aplicación también incluye funcionalidades que aún no se admiten en determinados hosts, es posible que la aplicación solo se cargue parcialmente, lo que da lugar a experiencias de usuario no planeadas.

Por ejemplo, considere una aplicación que se define con el esquema de manifiesto de aplicación versión 1.17 e incluye un bot y una pestaña de configuración que representa la configuración del bot. La aplicación se cargaría en outlook y en la aplicación de Microsoft 365 (Office), pero solo mostraría la pestaña de configuración del bot al usuario sin el propio bot.

Para asegurarse de que las experiencias de aplicación de alta calidad lleguen a la base de usuarios prevista, especifique los requisitos en tiempo de ejecución de la aplicación en el manifiesto de la aplicación. Esto le permite adaptar su comportamiento en los hosts de Microsoft 365 aplicables o omitirlo de la navegación en contextos que no está listo para admitir.

La especificación de los requisitos de tiempo de ejecución de la aplicación es útil en escenarios como:

  • Dependencias unidireccionales: cuando el único propósito de una funcionalidad de aplicación es admitir otra funcionalidad en la aplicación, puede asegurarse de que solo se muestre si se carga la funcionalidad de la aplicación principal. Por ejemplo, si la aplicación incluye una pestaña y una extensión de mensaje, y la pestaña funciona como una página de configuración para que los usuarios configuren la funcionalidad de extensión de mensaje, puede especificar que la pestaña configuración no se cargue en hosts que no admitan la extensión de mensaje.

  • Dependencias mutuas: Cuando la aplicación tiene funcionalidades de aplicación específicas que deben cargarse juntas para funcionar correctamente, puede asegurarse de que la aplicación solo está disponible en los hosts de Microsoft 365 que admiten todas las funcionalidades. Por ejemplo, si todas las funcionalidades de extensión de pestañas, bots y mensajes funcionan juntas para admitir un escenario de usuario principal en la aplicación, puede especificar que esas funcionalidades siempre se carguen juntas o no en absoluto.

  • Requisitos de funcionalidad: Cuando la aplicación tiene funcionalidades con requisitos en tiempo de ejecución que no se admiten en hosts específicos de Microsoft 365, puede asegurarse de que esas funcionalidades se omiten sin problemas (en lugar de cargarse, pero no son funcionales) de la experiencia de la aplicación que se ejecuta en esos hosts. Por ejemplo, si la aplicación incluye una vista de panel basada en pestañas de elementos que se pueden abrir como un cuadro de diálogo y cada cuadro de diálogo contiene información que luego se envía a un bot, puede especificar que los diálogos basados en bots son funcionalidades básicas necesarias para que la aplicación se cargue en un host determinado.

Compatibilidad con hosts de Microsoft 365

Las siguientes aplicaciones host de Microsoft 365 admiten la capacidad de especificar los requisitos en tiempo de ejecución en el manifiesto de aplicación:

Aplicación host de Microsoft 365 Web Escritorio Móvil
Teams ✔️ ✔️ ✔️
Outlook ✔️ ✔️ (Solo Outlook nuevo) ✔️
Microsoft 365 (Office)
Microsoft 365 Copilot

Especificar relaciones entre las funcionalidades de la aplicación (elementRelationshipSet)

Puede especificar relaciones entre las funcionalidades individuales de la aplicación mediante la inclusión de en el elementRelationshipSet manifiesto de la aplicación. Use este objeto para especificar las dependencias unidireccionales y las dependencias mutuas entre las funcionalidades de la aplicación.

Las siguientes funcionalidades de manifiesto de aplicación se pueden especificar como dependencias unidireccionales o mutuas:

  • Pestañas: personal (staticTabs) y configurable (configurableTabs)
  • Extensiones de mensaje (composeExtensions), incluidos comandos individuales
  • Bots (bots)

Cada funcionalidad de aplicación se define mediante la propiedad recién introducida, id, que se asigna a botId para bots, entityId para pestañas estáticas y id para pestañas configurables y extensiones de mensaje. Teams y otros hosts de Microsoft 365 admiten aplicaciones que contienen una sola pestaña configurable, una sola extensión de mensaje o ambas. La id propiedad prueba en el futuro la aplicación si la compatibilidad con el host se expande para dar cabida a varias instancias de estas funcionalidades.

Importante

Asegúrese de que las relaciones que cree cumplen las siguientes reglas de validación:

  1. Los elementos especificados en elementRelationshipSet deben tener definiciones en el manifiesto de la aplicación. Por ejemplo, un element objeto o commandId que aparece en la dependsOn sección de un oneWayDependencies objeto que no tiene una definición correspondiente en el manifiesto de la aplicación (con un valor coincidente id ) produce un error de validación de manifiesto. La id propiedad debe especificarse en o configurableTab para composeExtension que se reconozca en .elementRelationshipSet
  2. Un conjunto determinado de funcionalidades solo se puede agrupar por un mutualDependency o oneWayDependency, pero no por ambas. Por ejemplo, la especificación de una dependencia unidireccional (A depende de B) y una dependencia mutua (A y B dependen entre sí) da como resultado un error de validación de manifiesto, ya que la relación A depende de B se representa dos veces.
  3. No se permiten las dependencias unidireccionales cíclicas. Por ejemplo, la especificación de una A depende de la relación B y una relación B depende de que una relación A produzca un error de validación del manifiesto.

Dependencias unidireccionales

Use la oneWayDependencies matriz para describir los casos en los que un componente de la aplicación depende de otro componente. Para cada objeto de la matriz, especifique el componente dependiente (element) y el componente del que depende (dependsOn). También puede especificar comandos individuales que requieran compatibilidad con funcionalidades de aplicación específicas. Si esas funcionalidades no se admiten en el host en tiempo de ejecución, no estarán disponibles para el usuario (aunque se ejecuten todos los demás comandos).

El siguiente fragmento de código JSON muestra comandos de extensión de mensaje específicos que tienen una dependencia unidireccional en un bot:

    "elementRelationshipSet": {
      "oneWayDependencies" : [
        {
          "element" : {
            "name" : "composeExtensions",
            "id" : "composeExtension-id",
            "commandIds": ["exampleCmd1", "exampleCmd2"]
          },
          "dependsOn" : [
              {"name" : "bots", "id" : "bot-id"}
            ]
        }
      ]
    }

Dependencias mutuas

Use la mutualDependencies matriz para agrupar las funcionalidades de la aplicación que deben cargarse juntas para admitir su función prevista. Cada objeto de la matriz representa un conjunto de funcionalidades de aplicación mutuamente dependientes. El siguiente fragmento de código JSON muestra un bot, una pestaña estática, una extensión de mensaje y una pestaña configurable que dependen mutuamente entre sí:

    "elementRelationshipSet": {
      "mutualDependencies" : [
        [
                {"name" : "bots", "id" : "bot-id"}, 
                {"name" : "staticTabs", "id" : "staticTab-id"},
                {"name" : "composeExtensions", "id" : "composeExtension-id"},
                {"name" : "configurableTabs", "id": "configurableTab-id"}
        ]
      ]
    },

Especificar los requisitos en tiempo de ejecución para funcionalidades de aplicación específicas (requirementSet)

Dentro de las definiciones de funcionalidad de aplicación individuales, puede especificar requisitos específicos del entorno de ejecución de TeamsJS mediante .requirementSet Esto garantiza que la funcionalidad de la aplicación solo se cargue en hosts de Microsoft 365 con compatibilidad con las funcionalidades críticas de TeamsJS.

Las siguientes funcionalidades de TeamsJS se pueden especificar como requisitos en tiempo de ejecución para staticTabs, composeExtensionsy bots:

El siguiente fragmento de código JSON muestra una pestaña estática que requiere que su host admita diálogos HTML (denominados módulos de tareas en TeamsJS v1.x) invocados desde pestañas y bots:

    "staticTabs": [
        {
            "entityId": "idForPage",
            "name": "Display name of tab",
            "contentUrl": "https://contoso.com/content?host=msteams",
            "contentBotId": "Specifies to the app that tab is an Adaptive Card Tab. You can either provide the contentBotId or contentUrl.",
            "websiteUrl": "https://contoso.com/content",
            "scopes": [
                "personal"
            ],
            "requirementSet": {
                "hostMustSupportFunctionalities": [
                  {"name": "dialogUrl"},
                  {"name": "dialogUrlBot"}
                ]
            }
        }
    ],

Ejemplos de código

Ejemplo de nombre Descripción JavaScript
Destino de requisitos: dependencia unidireccional Aplicación de ejemplo que muestra cómo especificar relaciones de dependencia unidireccionales entre las funcionalidades de la aplicación. View
Destino de requisitos: dependencia mutua Aplicación de ejemplo que muestra cómo especificar relaciones de dependencia mutua entre las funcionalidades de la aplicación. Ver

Consulte también