Modelo de acciones universal

Artículo
08/29/2023

Context

Tarjetas adaptables ofrece fragmentos de código de interfaz de usuario independientes de la plataforma, creados con un formato JSON ligero, que las aplicaciones y los servicios pueden compartir. Tarjetas adaptables no solo se adapta a la apariencia y el funcionamiento del host, sino que también proporciona abundantes funcionalidades de interacción. Para obtener más información acerca de Tarjetas adaptables, visite adaptivecards.io.

A medida que el formato de Tarjetas adaptables crecía en popularidad, los distintos hosts comenzaron a admitir diferentes modelos de acción, lo que produjo fragmentación. Para solucionar este problema, los equipos de Teams, Outlook y Tarjetas adaptables trabajaron en la creación de un nuevo modelo de acción de bot universal compatible entre hosts. Este trabajo dio lugar a lo siguiente:

La generalización de bots y de Bot Framework como método para implementar escenarios basados en Tarjetas adaptables para Teams (bots) y Outlook (mensajes que requieren acción).
Action.Execute como sustituto de Action.Submit (que actualmente utilizan los bots) y Action.Http (que actualmente usan los mensajes que requieren acción).
Características populares que solo admite la característica Mensajes que requieren acción disponibles para los bots, es decir:
- Capacidad de actualizar una tarjeta en el momento en que se muestra.
- Capacidad de las acciones Action.Execute para devolver una tarjeta actualizada que se mostrará inmediatamente en el cliente.

Para obtener más información acerca de los mensajes que requieren acción en Outlook, consulte la documentación sobre los mensajes que requieren acción.

Para obtener más información sobre los distintos escenarios posibles con acciones universales en Teams, consulte la referencia sobre las tarjetas de Teams.

Antes de `Action.Execute`	Con `Action.Execute`

Origen: Tarjetas adaptables en Microsoft Build 2020

El resto de este documento se centra en documentar el modelo de acción de bot universal en el contexto de Teams y Outlook. Si ya usa Tarjetas adaptables en Teams con bot, puede usar el mismo bot con algunos cambios para admitir Action.Execute. Si usa Mensajes que requieren acción en Outlook, tendrá que desarrollar un bot que admita Action.Execute. Actualmente, la compatibilidad con los clientes de Outlook para el modelo de acción de bot universal se está desarrollando activamente.

Esquema

IMPORTANTE

El modelo de acción de bot universal se presenta en el esquema de Tarjetas adaptables, versión 1.4. Para poder usar estas nuevas funcionalidades, la propiedad version de Tarjetas Adaptables debe establecerse en 1.4 o superior, como se muestra en los ejemplos siguientes. Tenga en cuenta que esto hará que la tarjeta adaptable sea incompatible con clientes más antiguos (Outlook o Teams) que no admitan el modelo de acción de bot universal.

Si usa la propiedad refresh o Action.Execute y especifica una versión de tarjeta de una versión < 1.4, ocurrirá lo siguiente:

Remoto Comportamiento

Outlook La tarjeta NO funcionará. refresh no se respetará y Action.Execute no se representará. Es posible que la tarjeta se rechace por completo.

Teams Es posible que la tarjeta NO funcione (que no se respete la propiedad refresh y que las acciones Action.Execute no se representen) en función de la versión del cliente de Teams.

Para garantizar la máxima compatibilidad en Teams, considere la posibilidad de definir las acciones de Action.Execute con una acción Action.Submit en la propiedad fallback.

Consulte la sección Compatibilidad con versiones anteriores a continuación para obtener más información.

Remoto	Comportamiento
Outlook	La tarjeta NO funcionará. `refresh` no se respetará y `Action.Execute` no se representará. Es posible que la tarjeta se rechace por completo.
Teams	Es posible que la tarjeta NO funcione (que no se respete la propiedad `refresh` y que las acciones `Action.Execute` no se representen) en función de la versión del cliente de Teams. Para garantizar la máxima compatibilidad en Teams, considere la posibilidad de definir las acciones de `Action.Execute` con una acción `Action.Submit` en la propiedad `fallback`.

Action.Execute

Al crear Tarjetas adaptables, utilice Action.Execute en lugar de Action.Submit y Action.Http. El esquema de Action.Execute es muy similar al de Action.Submit.

Ejemplo de JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Propiedades

Propiedad	Type	Obligatorio	Descripción
type	`"Action.Execute"`	Sí	Debe ser `"Action.Execute"`.
verbo	string	No	Cadena de conveniencia que el desarrollador puede usar para identificar la acción.
data	`string`, `object`	No	Datos iniciales con los que se combinarán los campos de entrada. Son, básicamente, propiedades "ocultas".
title	`string`	No	Etiqueta del botón o vínculo que representa esta acción.
iconUrl	`uri`	No	Icono opcional que se mostrará en la acción junto con el título. Admite el URI de datos en las Tarjetas adaptables versión 1.2 y posteriores.
style	`ActionStyle`	No	Controla el estilo de una acción, que influye en cómo se muestra, dice, etc.
fallback	`<action object>`, `"drop"`	No	Describe qué hacer cuando Action.Execute no es compatible con el cliente que muestra la tarjeta.
requires	`Dictionary<string>`	No	Serie de pares clave-valor que indican las características que el elemento requiere con la versión mínima correspondiente. Cuando una característica falta o tiene una versión insuficiente, se desencadena la propiedad fallback.

Mecanismo de actualización

Junto con Action.Execute, ahora se admite un nuevo mecanismo de actualización, que permite crear tarjetas adaptables que se actualizan automáticamente en el momento en que se muestran. Esto garantiza que los usuarios siempre vean los datos actualizados. Un caso de uso de actualización típico es una solicitud de aprobación: una vez aprobada, es mejor que no se muestre una tarjeta a los usuarios para solicitarles que la aprueben cuando ya se ha hecho, sino que se les proporcione información sobre el momento en que se aprobó y quién lo hizo.

Para permitir que una tarjeta adaptable se actualice automáticamente, defina su propiedad refresh, que inserta un elemento action de tipo Action.Execute, así como una matriz de userIds.

Propiedad	Type	Obligatorio	Descripción
action	`"Action.Execute"`	Sí	El valor debe ser una instancia del tipo `"Action.Execute"`.
userIds	`Array<string>`	Sí	Matriz de datos `MRI` de usuarios para los que se debe habilitar la actualización automática. IMPORTANTE: Si la propiedad de lista `userIds` no se incluye en la sección `refresh` de la tarjeta, esta no se actualizará automáticamente en la pantalla. En su lugar, se presentará un botón al usuario para que la pueda actualizar manualmente. El motivo es que los chats o canales de Teams pueden incluir un gran número de miembros. Si todos los miembros ven el canal al mismo tiempo, la actualización automática incondicional devolvería muchas llamadas simultáneas al bot, que no se escalaría. Para mitigar el posible problema de escalado, la propiedad `userIds` se debe incluir siempre para identificar qué usuarios deben obtener una actualización automática, con el máximo de 60 identificadores de usuario que se permiten actualmente. Consulte los valores de userIds en la propiedad refresh para obtener más información. Tenga en cuenta que la propiedad `userIds` se ignora en Outlook y que la propiedad `refresh` siempre se respeta automáticamente. No hay ningún problema de escalado en Outlook, ya que los usuarios, normalmente, ven la tarjeta en momentos diferentes.

Ejemplo de JSON

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "originator":"c9b4352b-a76b-43b9-88ff-80edddaa243b",
  "version": "1.4",
  "refresh": {
    "action": {
      "type": "Action.Execute",
      "title": "Submit",
      "verb": "personalDetailsCardRefresh"
    },
    "userIds": []
  },
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    { 
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": "Action.Submit"
        }
      ]
    }
  ]
}

Nota importante para desarrolladores de Mensajes que requieren acción de Outlook

Al desarrollar escenarios de Mensajes que requieren acción de Outlook, se debe especificar la propiedad originator de la tarjeta adaptable. originator es un identificador único global (GUID) que se genera en el momento en que un bot se suscribe al canal de Outlook. Outlook lo usa para validar que un bot autorizado envió la tarjeta adaptable. La tarjeta adaptable no se representará en Outlook si la propiedad originator no está presente. La propiedad originator se ignora en Teams.

Actividad Invoke `adaptiveCard/action`

Cuando se ejecuta una acción Action.Execute en el cliente (ya sea la acción de actualización o una acción realizada explícitamente por un usuario al hacer clic en un botón), se realiza un nuevo tipo de actividad Invoke (adaptiveCard/action) en el bot. Una solicitud de actividad Invoke adaptiveCard/action típica tendrá un aspecto similar al siguiente:

Formato de solicitud

{ 
  "type": "invoke",
  "name": "adaptiveCard/action",

  // ... other properties omitted for brevity

  "value": { 
    "action": { 
      "type": "Action.Execute", 
      "id": "abc", 
      "verb": "def",
      "data": { ... } 
    },
    "trigger": "automatic | manual" 
  }
}

Campo	Descripción
value.action	Copia de la acción tal y como se define en la tarjeta adaptable. Igual que en la acción `Action.Submit`, la propiedad `data` de la acción incluye los valores de las distintas entradas de la tarjeta, si hay alguna.
value.trigger	Indica si la acción se desencadenó explícitamente (al hacer clic en un botón el usuario) o implícitamente (mediante la actualización automática).

Formato de respuesta

Si el bot procesó una actividad Invoke adaptiveCard/action entrante (es decir, si el código del bot estuvo involucrado de alguna forma en el procesamiento de la solicitud), el código de estado de la respuesta HTTP devuelto por el bot debe ser igual a 200 y el cuerpo de la respuesta HTTP debe tener el formato siguiente:

{ 
    "statusCode": <number (200 – 599)>, 
    "type": "<string>", 
    "value": "<object>"
}

Campo	Descripción
statusCode	Un código de estado de respuesta HTTP de 200 no significa necesariamente que el bot pueda procesar la solicitud correctamente. Una aplicación cliente siempre debe examinar la propiedad `statucCode` en el cuerpo de la respuesta para saber cómo procesó el bot la solicitud. La propiedad `statusCode` es un número comprendido entre 200 y 599 que refleja los valores de código de estado HTTP y está pensado para ser un subestado del resultado del bot que procesa la actividad Invoke. Un valor que falta, es null o no está definido para la propiedad `statusCode` implica un código 200 (correcto).
type	Conjunto de constantes de cadena conocidas que describen la forma esperada de la propiedad value.
value	Objeto específico del tipo de cuerpo de la respuesta.

Códigos de estado admitidos

En la tabla siguiente se enumeran los valores permitidos para statusCode, type y value en el cuerpo de respuesta del bot:

Código de estado	Tipo	Esquema de valor	Notas
200	`application/vnd.microsoft.card.adaptive`	`Adaptive Card`	La solicitud se procesó correctamente y la respuesta incluye una tarjeta adaptable que el cliente debería mostrar en lugar de la actual.
200	`application/vnd.microsoft.activity.message`	`string`	La solicitud se procesó correctamente y la respuesta incluye un mensaje que el cliente debe mostrar.
400	`application/vnd.microsoft.error`	Objeto de error (TAREA: se necesita un vínculo)	La solicitud entrante no era válida.
401	`application/vnd.microsoft.activity.loginRequest`	OAuthCard (TAREA: se necesita un vínculo)	El cliente debe pedir al usuario que se autentique.
401	`application/vnd.microsoft.error.inccorectAuthCode`	nulo	El estado de autenticación que pasó el cliente era incorrecto y se produjo un error de autenticación.
412	`application/vnd.microsoft.error.preconditionFailed`	Objeto de error (TAREA: se necesita un vínculo)	Error en el flujo de autenticación de SSO.
500	`application/vnd.microsoft.error`	Objeto de error (TAREA: se necesita un vínculo)	Se ha producido un error inesperado.

Resumen: cómo aprovechar el modelo de acción de bot universal

Use Action.Execute en lugar de Action.Submit. Para actualizar un escenario existente en Teams, reemplace todas las instancias de Action.Submit por Action.Execute. Para actualizar un escenario existente en Outlook, consulte la sección de compatibilidad con versiones anteriores a continuación.
En el caso de las tarjetas que se deben mostrar en Outlook, agregue el campo originator. Consulte el ejemplo de JSON anterior.
Agregue una cláusula refresh a la tarjeta adaptable si quiere sacar provecho del mecanismo de actualización automática o si su escenario requiere vistas específicas del usuario. Asegúrese de especificar la propiedad userIds para identificar qué usuarios (60 como máximo) recibirán actualizaciones automáticas.
Controle las solicitudes Invoke adaptiveCard/action en el bot.
Siempre que el bot necesite devolver una nueva tarjeta como resultado del procesamiento de una acción Action.Execute, puede usar el contexto de la solicitud Invoke para generar tarjetas específicamente diseñadas para un usuario determinado. Asegúrese de que la respuesta se ajusta al esquema de respuesta definido anteriormente.

Compatibilidad con versiones anteriores

Outlook

El nuevo modelo de acción universal Action.Execute es una desviación del modelo de acción Action.Http que usan actualmente los Mensajes que requieren acción de Outlook, donde las acciones se codifican en la tarjeta adaptable como llamadas HTTP explícitas. El modelo Action.Execute permite a los desarrolladores implementar escenarios que "solo funcionan" en Outlook y Teams. Los escenarios de Mensajes que requieren acción pueden usar el modelo Action.Http o el nuevo modelo Action.Execute, pero no ambos. Los escenarios que usan el modelo Action.Execute universal deben implementarse como bots y suscribirse al canal Outlook Actionable Messages.

Notas importantes

Los escenarios implementados con el modelo Action.Execute universal no serán compatibles con versiones anteriores de Outlook.

El trabajo está en curso para permitir que los escenarios de Mensajes que requieren acción existentes se migren sin problemas al modelo Action.Execute universal.

Teams

Para que las tarjetas sean compatibles con versiones anteriores y funcionen para los usuarios de versiones anteriores de Teams, las acciones Action.Execute deberían incluir una propiedad fallback definida como Action.Submit. El bot debe codificarse de forma que pueda procesar los tipos de acciones Action.Execute y Action.Submit. Tenga en cuenta que no es posible que el bot devuelva una nueva tarjeta al procesar una acción Action.Submit, por lo que el comportamiento de reserva mediante Action.Submit proporcionará una experiencia degradada para el usuario final.

Nota importante

Algunos clientes de Teams más antiguos no admiten la propiedad fallback cuando no se encapsulan en una propiedad ActionSet. Para no provocar interrupciones en este tipo de clientes, se recomienda encarecidamente encapsular todas las acciones Action.Execute en la propiedad ActionSet. Vea el ejemplo siguiente sobre cómo encapsular la acción Action.Execute en la propiedad ActionSet.

En el ejemplo siguiente, observe que la propiedad version de la tarjeta está establecida en 1.2 y que la acción Action.Execute está definida con una acción Action.Submit como su propiedad fallback. Cuando se representa en un cliente de Teams que admite Tarjetas adaptables 1.4, la acción Action.Execute se representará y funcionará según lo previsto. En los clientes de Teams que no admiten Tarjetas adaptables 1.4, se representará la acción Action.Submit en lugar de la acción Action.Execute.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "Present a form and submit it back to the originator"
    },
    {
      "type": "Input.Text",
      "id": "firstName",
      "placeholder": "What is your first name?"
    },
    {
      "type": "Input.Text",
      "id": "lastName",
      "placeholder": "What is your last name?"
    },
    {
      "type": "ActionSet",
      "actions": [
        {
          "type": "Action.Execute",
          "title": "Submit",
          "verb": "personalDetailsFormSubmit",
          "fallback": {
            "type": "Action.Submit",
            "title": "Submit"
          }  
        }
      ]
    }
  ]
}

Compartir a través de

Modelo de acciones universal

Context

Esquema

IMPORTANTE

Action.Execute

Mecanismo de actualización

Nota importante para desarrolladores de Mensajes que requieren acción de Outlook

Actividad Invoke `adaptiveCard/action`

Formato de solicitud

Formato de respuesta

Resumen: cómo aprovechar el modelo de acción de bot universal

Compatibilidad con versiones anteriores

Outlook

Notas importantes

Teams

Nota importante

Referencias

Recursos adicionales

Compartir a través de

Modelo de acciones universal

Context

Esquema

IMPORTANTE

Action.Execute

Mecanismo de actualización

Nota importante para desarrolladores de Mensajes que requieren acción de Outlook

Actividad Invoke adaptiveCard/action

Formato de solicitud

Formato de respuesta

Resumen: cómo aprovechar el modelo de acción de bot universal

Compatibilidad con versiones anteriores

Outlook

Notas importantes

Teams

Nota importante

Referencias

Recursos adicionales

Actividad Invoke `adaptiveCard/action`